Skill Creator

Skill Creator

Create, evaluate, and iterate on high-quality agent skills. This skill guides the entire lifecycle: planning what the skill should do, writing SKILL.md and reference files, scoring quality against a rubric, and iterating until the skill meets production standards.

Philosophy: A great skill is not a long skill. It is a precise skill: exhaustive triggers, explicit defaults, clear steps with exit gates, deferred complexity via reference files, and a structured output template.

Core rule — always dynamic, never static: Skills MUST detect what tools, libraries, and auth are available at runtime and adapt their behavior accordingly. Never hardcode a single method. Always provide a detection flow with a decision tree and fallback paths. See references/dynamic-calling.md for the complete pattern catalog.

Step 1: Understand What the User Wants

Classify the request into one of these modes:

If ambiguous, ask: "Do you want to create a new skill, improve an existing one, or evaluate one?"

Gather Requirements (for Create mode)

Before writing anything, answer these questions (ask the user if unclear):

Step 2: Plan the Skill Architecture

Before writing SKILL.md, plan the structure. Read references/architecture-patterns.md for detailed guidance on each pattern.

Choose a Structural Pattern

Plan the Step Outline

Write out the step names before writing content. Every skill should have:

1. Detection flow (Step 1) -- dynamically detect available tools, auth state, and runtime environment; build a decision tree for which method to use
2. Core methodology (Steps 2-N) -- the actual work, with pass/fail gates; each step that calls an external tool should have method alternatives based on what Step 1 detected
3. Respond to user (Final step) -- structured output template

Target 5-9 steps total. More than 9 means the skill should be split or use a router pattern.

Plan the Detection Flow

Every skill that touches external tools MUST start with a runtime detection flow. Read references/dynamic-calling.md for all patterns. The detection flow answers:

The detection output feeds into a decision tree that the rest of the skill follows. Never assume — always check.

Plan Reference Files

Decide what goes in SKILL.md vs references/:

Step 3: Write the SKILL.md

Read references/writing-guide.md for detailed instructions on writing each section. Read references/frontmatter-guide.md for the complete YAML field reference.

Key Rules

1. Frontmatter first: name (lowercase-hyphenated, max 64 chars) and description (exhaustive trigger list, max 1024 chars) are required. Description needs 5+ triggers including sideways entry points.

1. Step 1 = detection flow: Use !command` with fallbacks to detect available tools, auth state, and runtime. Build a decision tree with multiple method paths (e.g., CLI preferred, Python fallback, built-in tools last resort). Never hardcode a single tool — always detect and adapt. See references/dynamic-calling.md`.

1. Core steps with method alternatives: Each step that calls an external tool should offer at least 2 paths based on what Step 1 detected. Use pattern: "If TOOL_A detected → Method 1, otherwise → Method 2." Each step gets ## Step N: [Verb] [Object], a decision table if routing, a pass/fail gate if evaluative, and a reference pointer for deep content.

1. Defaults table: Every parameter MUST have an explicit default. No skill should ever stall waiting for input.

1. Final step = output template: Number every output section. Specify exactly what data goes in each. Include a verdict/grade system if evaluative.

See references/skill-examples.md for annotated examples of each pattern.

Step 4: Write Reference Files

Read references/writing-guide.md for the full reference file authoring guide.

Key Rules

1. Naming: lowercase-hyphenated.md, one file per concept-cluster
2. Size: Quick lookup 50-150 lines, deep guide 150-400 lines, catalog 400-900 lines
3. Structure: H1 title, H2 sections, code blocks, tables, edge cases section at end
4. Linking: Use backtick paths in SKILL.md steps and a ## Reference Files section at the end

Step 5: Quality Check Before Delivery

Run the skill through the quality rubric in references/quality-rubric.md. Score each dimension.

Quick Checklist

• [ ] Frontmatter has name and description (both required)
• [ ] Description has 5+ distinct trigger phrases
• [ ] Description includes sideways entry points
• [ ] SKILL.md is under 300 lines (ideally under 250)
• [ ] Every parameter has an explicit default
• [ ] Steps are numbered (## Step N: ...)
• [ ] Each step has a clear exit condition or deliverable
• [ ] Final step specifies exact output structure with numbered sections
• [ ] Complex content is in reference files, not inline
• [ ] Reference file pointers use backtick paths
• [ ] Step 1 has a detection flow with !command` checks and fallbacks (|| echo "..."`)
• [ ] Detection flow produces a decision tree with 2+ method paths
• [ ] Core steps adapt behavior based on detection results (not hardcoded to one tool)
• [ ] Separate runtimes treated as separate environments (terminal vs execute_code)
• [ ] Legal/ethical disclaimers included where appropriate
• [ ] No hardcoded ticker lists, tool paths, or static data that will go stale

If any item fails, fix it before delivering to the user.

Step 6: Improve an Existing Skill

When the user asks to improve a skill:

6a: Read the Current Skill