Create new skills, modify and improve existing skills

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:

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 response template
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	Steps	Example
Linear	Single workflow, no branching	5-7	earnings-preview, etf-premium
Router	Multiple sub-tasks under one umbrella	3 + sub-skills	stock-correlation (4 sub-skills)
Methodology	Complex domain framework with sequential gates	7-9	sepa-strategy (9-step trading methodology)
Widget	Generates interactive UI output	4-5	options-payoff (extract + compute + render)
API Wrapper	Wraps an external API with many endpoints	3-5 + heavy references	fintel-data (6 steps, 1 reference file)

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:

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

In SKILL.md (under ~250 lines)	In references/
Step-by-step workflow	Detailed API documentation
Routing/decision tables	Code templates (>20 lines)
Parameter defaults table	Formulas and edge cases
Output format template	Troubleshooting database
Quick examples (1-3)	Comprehensive examples (4+)

---

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.

2. 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.

3. 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.

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

5. 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:

Dimension	Score	Issue
Trigger quality	6/10	Missing beginner phrasing
Defaults coverage	3/10	No defaults table
Step structure	8/10	Good, but Step 3 lacks exit gate
Output template	4/10	Vague "summarize results"
Reference usage	7/10	Good split, but missing troubleshooting

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:

Skill	Score	Why
sepa-strategy	~90/100	9 steps, 7 refs, exhaustive triggers, structured verdict
options-payoff	~85/100	Strong defaults, working code, live data, clean output
stock-correlation	~80/100	Router pattern, 4 sub-skills, good defaults

---

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