Skill Author

When to use

• Authoring a new skills/<kebab-name>/SKILL.md.
• Reworking a weak skill that failed skillcheck lint/score.
• The user asks to "write a skill", "pack a skill", or "make this skillcheck-grade".

When not to use

• General application feature work unrelated to agent skills.
• One-off chat instructions that will not be saved as a skill file.
• Generating dozens of broad "do everything" mega-skills in one pass.

Assumptions

• Output path follows skills/<kebab-name>/SKILL.md with YAML frontmatter.
• skillcheck may be available (skillcheck lint / skillcheck score); use it when present.
• Do not overwrite existing published skills without confirmation.
• Do not embed live secrets, proprietary customer data, or copyrighted dumps in examples.

Workflow

1. Pick a single job-to-be-done; name it kebab-case.
2. Draft frontmatter description that starts with triggers ("Use when …") and states the outcome.
3. Fill required sections: When to use / When not to use / Assumptions / Workflow / Steps / Success criteria / Out of scope.
4. Run skillcheck lint + score; fix until clean and high-scoring.
5. Stop — do not bolt on unrelated responsibilities.

Steps

1. Scope — One concern only. If you need "and also", split into another skill.
2. Frontmatter — name matches folder; description is one tight paragraph with when + outcome (not vague adjectives).
3. Triggers & boundaries — Concrete bullets for when/when-not; include confirmation gates for destructive ops under Assumptions.
4. Procedure — Numbered Workflow plus actionable Steps (commands, artifacts, decision points).
5. Done checks — Success criteria as checkboxes an agent can verify; Out of scope to prevent mission creep.
6. Quality gate — No unfinished markers, stub text, or placeholders. Prefer skillcheck: lint 0 issues, score aiming for excellent (90–100).

Success criteria

• SKILL.md has valid frontmatter (name, non-vague description).
• All required sections are present with real content (no stubs).
• Destructive actions require confirmation in Assumptions.
• Success criteria are concrete checkboxes; scope is narrow.
• skillcheck lint is clean and skillcheck score is high when the tool is available.

Out of scope

• Building the skillcheck or skillstack CLIs themselves.
• Marketplace marketing copy unrelated to skill quality.
• Multi-skill product roadmaps (author one excellent skill at a time).