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

Load the skill with skill_view(name) or read the SKILL.md directly. Also read all reference files.

6b: Score It Against the Rubric

Use the quality rubric from references/quality-rubric.md. Present the score breakdown to the user:

6c: Propose Specific Improvements

List concrete changes ranked by impact:

1. [Highest impact] Add defaults table with 8+ parameters
2. [High impact] Rewrite description with 10+ trigger phrases
3. [Medium impact] Add structured output template to final step
4. ...

6d: Apply Changes

After user approval, edit the skill. Use skill_manage(action='patch', ...) for targeted changes or skill_manage(action='edit', ...) for full rewrites.

Step 7: Evaluate a Skill

When the user asks to evaluate or score a skill:

7a: Load and Analyze

Read the full SKILL.md and all reference files. Count lines, steps, triggers, defaults, reference files.

7b: Score Against Rubric

Use the comprehensive rubric from references/quality-rubric.md. Score each of the 10 dimensions on a 1-10 scale.

7c: Present the Scorecard

## Skill Quality Scorecard: [skill-name]

| # | Dimension | Score | Notes |
|---|---|---|---|
| 1 | Trigger quality | 8/10 | 12 triggers, includes sideways entries |
| 2 | Defaults coverage | 9/10 | All 11 parameters have defaults |
| 3 | Step architecture | 8/10 | 5 clear steps with gates |
| 4 | Reference file strategy | 7/10 | 2 files, could use troubleshooting |
| 5 | Dynamic content | 10/10 | Dep check + live data injection |
| 6 | Output template | 9/10 | 5 numbered sections + verdict |
| 7 | Error handling | 6/10 | Missing data handling unclear |
| 8 | Code/formula quality | 8/10 | Working JS, copy-paste ready |
| 9 | SKILL.md conciseness | 7/10 | 196 lines, well within target |
| 10 | Domain accuracy | 9/10 | BS formulas correct, edge cases covered |

**Overall: 81/100** -- Production quality

### Top 3 Improvements
1. ...
2. ...
3. ...

Benchmark Reference

For context, here are scores for known high-quality skills in this repo:

Step 8: Respond to the User

For Create mode

Deliver:

1. The complete SKILL.md content
2. All reference files
3. A README.md for the skill directory
4. The quality scorecard (from Step 5)
5. Suggested next steps (test it, iterate, publish)

For Improve mode

Deliver:

1. Before/after quality scores
2. Summary of changes made
3. Remaining improvement opportunities

For Evaluate mode

Deliver:

1. The full quality scorecard
2. Comparison to benchmark skills
3. Prioritized improvement list

Reference Files

• references/dynamic-calling.md -- Core reference: Detection flows, decision trees, method fallbacks, runtime awareness, and multi-tool adaptation patterns with annotated examples from production skills
• references/writing-guide.md -- Detailed instructions for writing SKILL.md sections, environment checks, defaults tables, output templates, and reference files
• references/architecture-patterns.md -- Linear, Router, Methodology, Widget, and API Wrapper patterns with examples and anti-patterns
• references/frontmatter-guide.md -- Complete YAML frontmatter field reference (name, description, platform, env vars, config, credentials)
• references/quality-rubric.md -- 10-dimension scoring rubric with 1-10 scales, benchmark scores, and score interpretation
• references/skill-examples.md -- Annotated excerpts from top skills showing why specific patterns work