Skill Lifecycle

Use this when a repeated workflow should become a skill, or when an existing skill fails and needs to be updated.

Triggers

Use this skill when the user says:

• "create a skill"
• "turn this into a skill"
• "update this skill"
• "improve this workflow"
• "the skill missed a step"

Preflight

• [ ] Is this workflow likely to repeat?
• [ ] Is the output format stable?
• [ ] Does the workflow have steps that an agent might skip?
• [ ] Is there already a similar skill in skills/INDEX.md?
• [ ] Are we creating a new skill or updating an existing one?

Decision: Create Or Update

Create A Skill

Step 1: Name The Skill

• Use lowercase kebab-case, such as publish-report.
• Make the name action-oriented.

Checkpoint: the name is unique in skills/INDEX.md.

Step 2: Define The Contract

Write these five fields before drafting:

• Trigger: when should the agent use it?
• Inputs: what does it need?
• Steps: what does the agent do?
• Output: what is produced?
• Failure modes: what usually goes wrong?

Checkpoint: each field has a concrete answer.

Step 3: Draft SKILL.md

Use this template:

---
name: "skill-name"
description: "Trigger + output in one sentence."
dependencies:
  tools: []
  files: []
  skills: []
---

# Skill Title

> One-sentence purpose.

## Triggers

- Use when...

## Preflight

- [ ] Required condition

## Steps

### Step 1: ...

- Action
- Must: non-negotiable rule

Checkpoint: how to know this step is complete.

## Verification

- [ ] Final check

## Failure Handling

- If X fails, do Y.

## Version History

- v1 (YYYY-MM-DD): Initial version.

Step 4: Make It Weak-Model Friendly

Add:

• explicit "Must" rules for non-negotiable behavior;
• checkpoints after important steps;
• at least one common failure mode;
• a final verification section.

Checkpoint: a weaker model can follow the skill without relying on hidden context.

Step 5: Add It To The Index

Update skills/INDEX.md with:

| `skill-name` | trigger | output | `skills/skill-name/SKILL.md` |

Checkpoint: the new skill can be found from the index.

Step 6: Record The Reason

Add an entry to feedback/log.md explaining why this skill was created.

Checkpoint: the log entry has an Updated: line.

Update A Skill

Step 1: Diagnose The Failure

Classify the update:

Checkpoint: the failure type is named before editing.

Step 2: Read Current State

Read the full current SKILL.md before editing.

Checkpoint: you can summarize the current trigger, steps, and version history.

Step 3: Edit Precisely

• Do not rewrite the whole skill unless the user asks.
• Add the smallest rule, step, or checkpoint that prevents recurrence.
• If triggers changed, update skills/INDEX.md.
• If environment assumptions changed, update memory/env.md.

Checkpoint: the edit matches the diagnosis.

Step 4: Append Version History

Add one line:

- vN (YYYY-MM-DD): What changed and why.

Checkpoint: old version history remains intact.

Step 5: Route The Feedback

Add an entry to feedback/log.md, then use feedback/update-checklist.md.

Checkpoint: the log says exactly which files were updated.

Verification

• [ ] Skill file exists.
• [ ] skills/INDEX.md matches trigger and path.
• [ ] Checkpoints exist after important steps.
• [ ] Feedback entry explains why the skill exists or changed.
• [ ] No private user data is included.

Version History

• v1 (2026-05-03): Initial public starter-kit version combining create and update into one lifecycle skill.