Task: Design and Create a New Skill

Task: Design and Create a New Skill

Objective

Given a description of what a skill should do, produce or refine a complete skill directory — a SKILL.md file and any supporting reference files — that follows project conventions, works with autonomous agents, produces self-contained document output with trackable frontmatter, and never requires human interaction during execution. When refining an existing skill, preserve what works, adapt to its established structure and references, and make targeted improvements rather than forcing a rewrite into a rigid template. The result is a skill that an agent can invoke to produce a structured output file from start to finish.

Inputs

1. Skill requirements (required) — what the skill should do, what it produces, what triggers it. Can be a description, user stories, a reference to an existing workflow phase, or feedback on an existing skill to refine.
2. Existing skill directory (auto-discovered) — if refining an existing skill, read the current SKILL.md and all files in references/ to understand the skill's established structure, conventions, and content before making changes.
3. Workflow context (optional) — where this skill fits in a larger pipeline. What skills run before it (providing input), what skills run after it (consuming output). This informs the input/output contracts.
4. Existing skills (auto-discovered) — read existing skills in skills/*/SKILL.md to understand conventions, voice, and patterns in use. Match their style.

Workflow

Skill creation or refinement follows three phases: design, write, and validate.

Phase 1: Design

Before writing anything, make these design decisions. If refining an existing skill, start by reading its current SKILL.md and all files in its references/ directory to understand the established structure.

1. New or refine? Determine whether this is a new skill or a refinement of an existing one. If refining, inventory what already exists — the current sections, reference files, conventions, and what's working well. The goal is targeted improvement, not a rewrite into a canonical template. Preserve the skill's existing structure and voice where they serve the skill's purpose.

2. Name and output file. Choose the output filename — always CAPITALIZED_WITH_UNDERSCORES.md. The name should clearly identify what the document is (e.g., SPEC.md, CODE_REVIEW.md, DEPLOYMENT_PLAN.md). This becomes the name field in frontmatter. If refining, keep the existing name unless explicitly asked to change it.

3. Folder name. Choose the skill's directory name under skills/ — lowercase, hyphenated (e.g., code-review, deployment-plan). This is how the skill is referenced in the plugin system.

4. Workflow or Rules (or both). Decide the core structure:

• Workflow — if the skill follows a sequential process with distinct phases (explore → analyze → write). Use when the order of operations matters.
• Rules — if the skill enforces properties the output must satisfy, regardless of how it gets there. Use when the constraints matter more than the process.
• Both — a workflow for the process and rules for output constraints. Common for skills that have a defined process but also need to guarantee output properties.

This is a judgment call. Look at the skill's nature: does it feel more like "follow these steps" or "satisfy these properties"? When in doubt, lean toward guidelines with clear principles rather than rigid step-by-step instructions.

5. Subagent decomposition. Decide if the skill needs subagents:

• Does it span multiple independent analysis dimensions? → subagents