create-skill

Files (14)

• SKILL.md
• evals.json · evals/
• trigger-eval.json · evals/
• agent-prompts.md · references/
• eval-system.md · references/
• frontmatter-fields.md · references/
• schemas.md · references/
• skill-anatomy.md · references/
• specification-urls.md · references/
• generate_report.py · scripts/
• improve_description.py · scripts/
• package_skill.py · scripts/
• quick_validate.py · scripts/
• run_eval.py · scripts/

SKILL.md (first lines)

# Create Skill

Create new agent skills with specification-driven generation, backed by live documentation fetching and interactive planning.

`<skill-dir>` below is this skill's directory.

## Writing Philosophy

Apply these when drafting the generated skill's description and body in Phase 4: they make the difference between a skill that works once vs. one that works reliably across varied inputs:

**Descriptions lead with use case.** Open with the concrete use case, then the trigger phrases a user would actually type: third person, WHAT the skill does + WHEN to use it. If a sibling skill covers adjacent territory, add one "Not for X (use <sibling>)" clause per real overlap: that single clause prevents more wrong triggers than three extra trigger phrases. Cap at 1024 chars (the bundled validator enforces it).

**Explain WHY only at hard boundaries.** Add reasoning only where an agent would otherwise plausibly do the wrong thing (e.g. "fetch live specs: cached docs go stale within weeks"). Everywhere else, a plain imperative ("Run the validator.") is faster to read and no less correct. Justifying every line is noise, not guidance.

**Keep it lean; reserve ALL-CAPS for true invariants.** Remove instructions that aren't pulling their weight: a 100-line skill often beats a 500-line skill diluted with edge cases that never occur. CRITICAL/MUST/ALWAYS/NEVER should mark the handful of things that really are non-negotiable; a word repeated ten times protects nothing.

**Generalize, don't overfit**: Skills designed only around their own test examples fail in practice. Design for the pattern, not the specific instance. Ask: "Would this instruction still apply if the user's request looked different?"

**Mine conversations first**: Users rarely articulate needs perfectly upfront. Extract information they've already provided before asking more questions.

**Refusal and precondition paths end at the question.** When the generated skill needs the user to resolve an ambiguity or confirm before a destructive step, its instruction should stop at asking. Never write "ask, then proceed anyway if there's no reply." A non-interactive eval run can't pause mid-task, so a skill written to assume it can either hangs or silently guesses.

## Workflow

Copy this checklist and tick each step as you finish it. Gates say where to return or stop.

```
- [ ] 0. Fetch both live specs (fetch fails -> use bundled references/skill-anatomy.md and references/frontmatter-fields.md)
- [ ] 1. Mine the conversation, then ask only the open questions
- [ ] 2. Research existing patterns and composable skills
- [ ] 3. Present the blueprint (not approved -> stop; no files written)
- [ ] 4. Generate files, then run the self-check list
- [ ] 5. Run quick_validate (fails -> fix and re-run, max 3 rounds, then report what still fails)
- [ ] 6. Evals, if worthwhile: missing run transcripts -> re-run those before grading; score under 4/5 -> fix the class of problem and return to 4 (stop when no progress)
```

### Phase 0: Fetch Live Specifications

Fetch latest specs before every creation: never rely on memory or bundled docs, because specifications evolve. This is two small fetches, not a research task, call WebFetch directly rather than spawning agents for it:

1. WebFetch `https://agentskills.io/specification.md`: frontmatter fields, directory rules
2. WebFetch `https://platform.claude.com/docs/skills/best-practices.md`: progressive disclosure, writing style, anti-hallucination patterns. If the fetch fails, fall back to bundled `references/skill-anatomy.md` and `references/frontmatter-fields.md`

Hold both results in context.

### Phase 1: Understand Requirements

**Step 1: Mine the conversation.** Read what the user already said and extract:
- What skill/command/workflow they want
- Examples of triggers they mentioned
- The tools, files, or outputs they described
- Who will use it, whether that's personal, team-wide, or org-wide

Extract answers from conversation history before asking questions: don't ask what's already there.

**Step 2: Four key questions** (ask only what the conversation didn't already answer) using AskUserQuestion:

1. **What does this skill do?** Focus on the outcome. "Generates ADRs in the Nygard format from a decision description" beats "helps with documentation." The more specific, the better the description will be.

2. **When should it trigger?** Give 2-3 examples of exactly what a user would type to activate it. These become the description. Think about different phrasings the same intent might take.

3. **What does success look like?** Describe the output or end state specifically. "Creates a numbered file in docs/adr/ with YAML frontmatter and four required sections" is useful; "produces documentation" isn't.

4. **Is this worth measuring?** Would you want to compare this skill's output against a no-skill baseline to know it's actually helping? This matters most for model-invoked skills that trigger automatically on vague prompts.

Adapt communication style to the user. Technical users: use precise terms (frontmatter, YAML, subprocess). Non-technical users: explain concepts ("the skill's metadata tells agents when to activate it").

**Step 3: Interview for edge cases.** Before planning, clarify:
- What are 2-3 common ways this could go wrong?
- Are there input variations that need different handling?
- What should the skill explicitly NOT do (to set scope boundaries)?

### Phase 2: Research Existing Patterns & Composition

No `Task` tool here? Do this research yourself, sequentially: read the same targets each agent below would, one after the other. The two research tracks are what matters, not the parallel dispatch.

Spawn 2 parallel Explore agents (model: haiku) using the Task tool:

```
Agent 1 - Internal Pattern Analysis:
- subagent_type: "Explore"
- model: "haiku"
- prompt: "Search skills/ directory for skills similar to [SKILL_PURPOSE].
  Extract:
  1. Similar skill patterns: frontmatter structure, phase organization, tool usage
  2. Composable skills: existing skills this new skill could reference or invoke
     Example: A deploy skill could invoke git-commit; a testing skill could invoke fix-bug
  3. scripts/ usage patterns: when scripts are included vs not
  Return: Patterns summary with file paths + composable skills list"

Agent 2 - External Example Research:
- subagent_type: "Explore"
- model: "haiku"
- prompt: "Research external skill examples:
  1. WebFetch https://skills.sh — search for skills similar to [SKILL_PURPOSE]
  2. WebFetch https://raw.githubusercontent.com/anthropics/skills/main/skills/skill-creator/SKILL.md — extract: workflow phases, frontmatter patterns, anti-hallucination techniques used in Anthropic's own skill-creator reference implementation
  3. Look for anti-hallucination and verification patterns
  Return: Best practices and common patterns with sources"
```

Consolidate into: pattern summary, composable skills list, decision rationale.

### Phase 3: Plan Skill Structure (User Approval Required)

Use EnterPlanMode to require explicit user approval before generating any files. If EnterPlanMode isn't available, present the same blueprint as plain text and wait for an explicit go-ahead: do not generate files on silence or an ambiguous reply.

Present a complete blueprint:

**1. Frontmatter Design:**
```yaml
name: skill-name          # kebab-case, ≤64 chars, no leading/trailing/consecutive hyphens
description: "..."        # assertive, covers multiple trigger phrasings, 50-1024 chars
[disable-model-invocation: true]   # add only for explicit /slash-command-only skills
[argument-hint: "[hint]"]          # add if skill accepts a positional argument
```

Allowed frontmatter keys: `name`, `description`, `license`, `allowed-tools`, `metadata`, `compatibility`, `disable-model-invocation`, `argument-hint`, `context`, `agent`, `hooks`. Reject anything else: unknown keys cause validation failures. Leave `allowed-tools` out: in Claude Code it only pre-approves tools for the turn that invokes the skill, restricts nothing, and is a permission grant every user has to vet. Add `context: fork` + `agent: <type>` only when the skill should be isolated from conversation history (the SKILL.md content becomes the subagent's entire prompt). See `references/frontmatter-fields.md` for the full field reference and `$ARGUMENTS`/`$0`/`$1` substitution syntax.

If the new skill builds on an existing one, follow the **Skill composition** convention in `AGENTS.md`: name the sibling skill in prose and state its tool-neutral fallback in the same sentence (via the `Skill` tool where available, otherwise apply its documented steps), don't invent `uses:`/`composes:` frontmatter for it.

From mgiovani/cc-arsenal, MIT.

More from mgiovani/cc-arsenal