skill-creator

Skill Creator

Create, evaluate, and iterate on high-quality agent skills. This skill covers the whole 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 precise, not long. Its description routes the right requests to it. Its body gives the model the context it can't get anywhere else — the environment, tool contracts, defaults, domain judgment, and the reasons behind each constraint — and leaves out what a capable model already does on its own. Current Claude models follow instructions closely and literally, so every line gets acted on: an over-scripted or shouting skill produces rigid, over-cautious output, while a clear goal and quality bar let the model plan the work itself. references/writing-guide.md covers this in detail.

Runtime adaptation: Skills that touch external tools should detect what is installed, authenticated, and reachable at runtime and adapt, rather than assuming a single method. Offer fallback paths where real alternatives exist. See references/dynamic-calling.md for the pattern catalog.

---

Step 1: Understand What the User Wants

Classify the request into one of these modes:

User Intent	Mode	Jump To
Create a brand-new skill	Create	Step 2
Improve / fix an existing skill	Improve	Step 6
Evaluate / score a skill's quality	Evaluate	Step 7

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):

Question	Why it matters
What task does the skill automate?	Defines the core workflow
Who is the target user?	Determines complexity and terminology level
What tools/APIs/CLIs does it use?	Determines dependencies and platform restrictions
What does the user provide as input?	Defines parameters and defaults
What should the output look like?	Defines the output contract
Does it need API keys or credentials?	Determines required_environment_variables
Should it work on Claude.ai or only CLI?	Determines platform field and dynamic commands

---

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

Pattern	When to use	Shape	Example
Linear	Single workflow, no branching	Setup → fetch → analyze → respond	earnings-preview
Router	Multiple sub-tasks under one umbrella	Setup + routing table + sub-skills	stock-correlation (4 sub-skills), etf-premium
Methodology	Formal domain framework with real gates	Ordered checks, each able to stop the analysis	sepa-strategy
Widget	Generates interactive UI output	Extract → compute → render → explain	options-payoff
API Wrapper	Wraps an external API with many endpoints	Auth + endpoint map + heavy references	fintel-data

Plan the Outline

Every skill has three parts:

1. Setup / detection — detect available tools, auth state, and runtime environment, and decide which method to use. Skills with no external dependencies can skip this.
2. The work — numbered steps where the order genuinely matters (fetch before compute, a gate that can end the analysis), plus the judgment the model has to exercise, stated as goals, criteria, and domain heuristics rather than a script.
3. Respond to the user — the output contract: what the answer leads with, what it must contain, which caveats apply, and any verdict scale.

If a skill needs more than about nine steps, split it or use the Router pattern.

Plan the Detection Flow

Skills that touch external tools should start with a runtime detection flow. Read references/dynamic-calling.md for all patterns. The detection flow answers:

Question	How to detect	Decision
Is the CLI tool installed?	command -v tool	CLI path vs Python fallback
Is the user authenticated?	tool auth status / echo $API_KEY	Skip auth setup vs guide through it
Which runtime has the library?	import lib in terminal vs execute_code	Route to correct runtime
Is a richer tool available?	gh --version vs git --version	Rich path vs minimal path
Is live data reachable?	curl -s endpoint	Live data vs cached/default

The detection output feeds a decision tree that the rest of the skill follows — check rather than assume.

Plan Reference Files

Decide what goes in SKILL.md vs references/:

In SKILL.md (under ~250 lines)	In references/
Workflow and decision points	Detailed API documentation
Routing/decision tables	Code templates (>20 lines)
Parameter defaults table	Formulas and edge cases
Output contract	Troubleshooting database
Quick examples (1-3)	Comprehensive examples (4+) and dated datasets

---

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 (max 1024 chars, no angle brackets) are required. The description is routing text that rides along in every request: say what the skill does, name the categories of requests it serves and the distinctive vocabulary users will use (methods, tools, data types, entities), and point to sibling skills for neighboring requests. Name intent categories instead of listing near-synonymous phrasings.

2. Detection flow for external dependencies: use !command`` probes with fallback sentinels to detect tools, auth state, and runtime, then route to a method. Offer a second path where a real alternative exists (CLI vs Python library vs built-in tool). See references/dynamic-calling.md.

3. Match specificity to fragility: give exact commands, flags, and code for fragile operations — installs, auth, CLI syntax, API contracts, calculations that must be right. For judgment work — analysis, interpretation, writing — state the goal, the criteria, and the domain heuristics, and let the model plan. Put a pass/fail gate wherever a failed check really ends the analysis.

4. Defaults table: give every parameter the user might omit an explicit default, so the skill never stalls waiting for input.

5. Output contract in the final step: what to lead with, what the answer must contain, which caveats apply, and any verdict or grade scale. Pin a section-by-section template only where the format itself matters (scorecards, widgets, checklists). Describe length qualitatively rather than with word or sentence counts, and label examples as illustrative rather than filling them with made-up figures for real companies.

6. Plain register: state each constraint once, with its reason. Leave out capitalized MUST/NEVER/CRITICAL, repeated warnings, and instructions current models follow by default ("be thorough", "think step by step", "double-check your answer") — they cause over-triggering and over-checking rather than better work. Keep real policy constraints (read-only, no trade execution, privacy) in plain words.

7. Keep volatile facts honest: fetch live data where you can, date-stamp anything that will go stale, and keep dated datasets in references/. Verify API names and response shapes against the current library before shipping.

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; the description is under 1024 characters with no angle brackets
• Description names what the skill does, the categories of intent it serves, and its distinctive vocabulary — not a list of near-synonymous phrasings
• Description points to sibling skills for neighboring requests, where they exist
• SKILL.md is under 300 lines (ideally under 250)
• Every parameter has an explicit default
• Numbered steps where order matters; judgment work is stated as goals, criteria, and heuristics
• Gates stop the analysis only where a failed check really ends it
• Final step states an output contract: what to lead with, required content, caveats, verdict scale
• No numeric length caps; examples are labeled illustrative
• Constraints are stated once, in plain words, with their reasons — no capitalized MUST/NEVER, no "think step by step" or "double-check" boilerplate
• Complex content is in reference files, not inline
• Reference file pointers use backtick paths
• External dependencies are detected at runtime with !command`` checks and fallbacks (|| echo "...")
• Separate runtimes treated as separate environments (terminal vs execute_code)
• Legal/ethical disclaimers included where appropriate
• No hardcoded ticker lists, tool paths, or undated static data that will go stale
• API names, fields, and code in the skill were checked against the current library

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

Read the SKILL.md and all reference files (on Hermes, skill_view(name) loads them).

6b: Score It Against the Rubric

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

Dimension	Score	Issue
Trigger quality	6/10	Twenty near-synonym phrasings; misses the ETF use case
Defaults coverage	3/10	No defaults table
Instruction design	5/10	Scripted steps for judgment work; capitalized warnings
Output contract	4/10	Rigid 9-section template with made-up example figures
Reference usage	7/10	Good split, but missing troubleshooting

6c: Propose Specific Improvements

List concrete changes ranked by impact:

1. [Highest impact] Add a defaults table covering every parameter
2. [High impact] Rewrite the description around intent categories and distinctive vocabulary
3. [Medium impact] Replace the fixed report template with an output contract
4. ...

6d: Apply Changes

After user approval, edit the skill files (on Hermes, 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, defaults, and reference files, and note the description's length and the intent categories it covers.

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 | Covers all four intent categories; one sibling boundary missing |
| 2 | Defaults coverage | 9/10 | All 11 parameters have defaults |
| 3 | Instruction design | 8/10 | Ordered setup and compute; analysis stated as criteria |
| 4 | Reference file strategy | 7/10 | 2 files, could use troubleshooting |
| 5 | Dynamic content | 10/10 | Dep check + live data injection |
| 6 | Output contract | 9/10 | Leads with verdict; required caveats; scale defined |
| 7 | Error handling | 6/10 | Missing data handling unclear |
| 8 | Code/formula quality | 8/10 | Working JS, copy-paste ready |
| 9 | Conciseness & register | 7/10 | 196 lines; two capitalized warnings to restate |
| 10 | Domain accuracy | 9/10 | BS formulas correct, edge cases covered |

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

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

Reference Skills

Skills in this repo that show each pattern well:

Skill	What it demonstrates
sepa-strategy	Methodology pattern: real gates, domain criteria in references, a verdict scale
options-payoff	Widget pattern: a default for every field, live data injection, a precise render spec
stock-correlation	Router pattern: intent routing table, self-contained sub-skills, metrics computed in code
earnings-preview	Output contract: a content checklist with one judgment section, lead-with-the-headline guidance
fintel-data	API wrapper: key resolution flow, endpoint map, error semantics

---

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 the reference 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 -- How to write each SKILL.md section for current Claude models: descriptions, detection flows, instructions matched to fragility, defaults, output contracts, 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, examples, and score interpretation
• references/skill-examples.md -- Annotated excerpts from top skills showing why specific patterns work