Skill Distillery

Skill Distillery

Distill raw material into potent skills. Articles, talks, frameworks, recent AI work, or just an idea — skill-distillery extracts the strategy bottom-up and builds interactive, well-architected skills from it.

The core insight: Good skills aren't restructured content — they're distilled strategy. A 5,000-word article becomes a 300-line skill by extracting principles, mental models, and decision frameworks, not by reformatting paragraphs.

Quick Start

From an article or framework:

/skill-distillery https://example.com/great-article-about-design-systems

/skill-distillery ~/Documents/talk-transcript.md

From recent AI work:

/skill-distillery capture — "I just figured out a great process for X, help me turn it into a skill"

From a description:

/skill-distillery — "I want a skill that helps me write better API documentation"

Audit an existing skill:

/skill-distillery audit ~/.claude/skills/my-skill

/skill-distillery review — "Can you evaluate the language-market-fit skill?"

Add to an existing skill:

/skill-distillery add reference — "I want to add a new reference file to my-skill"

---

Core Principles

These apply to everything skill-distillery does:

1. Bottom-up synthesis over content restructuring — Extract principles and mental models from source material. Don't reformat — distill.

2. Interactive by default — Use AskUserQuestion for tappable decisions. Ask 2-3 questions at a time, not a wall. Provide shortcuts when context is already available.

3. Propose before building — Always present synthesis, architecture, and approach for user approval before creating files. Wait gates at every decision point.

4. Progressive disclosure — SKILL.md stays lean (200-300 lines). Reference files contain depth. Load conditionally based on what the user needs.

5. Opinionated defaults — Suggest interactive patterns from proven skills (design-portfolio-assistant's discovery phase, language-market-fit's mode detection). The user can override, but the defaults should be good.

6. Research on demand, not by default — Most skill creation doesn't need research. Trigger it only when external APIs/libraries are involved or the user explicitly asks. See Research Protocol below.

7. Tailored to the user's specific goal — Not generic skill-making advice. Every decision adapts to what this particular user is building for this particular purpose.

8. Gotchas are the highest-signal content — The most valuable part of any skill is where Claude typically fails. Every skill should have a dedicated gotchas section documenting specific failure points with "don't do X because Y" structure. Gotchas come from anticipating Claude's failure modes, not theoretical anti-patterns.

9. Publication-ready by default — Every skill gets a README.md assuming it may be published on GitHub. After building, offer to publish via npx skills add (the skills.sh ecosystem). Ask about target agents early — Claude Code only vs. universal — since it shapes how features like AskUserQuestion are implemented.

---

Research Protocol

When and how to research during skill creation.

When to trigger:

• Skill involves external APIs or libraries needing current docs
• Domain where best practices shift fast (frameworks, deployment patterns)
• Audit reveals the skill references outdated libraries or patterns
• User explicitly asks: "Can you research X?"

When NOT to trigger:

• Source material is self-contained (articles, talks)
• User already knows the domain
• Skill is about internal processes or conventions
• Simple skills that don't reference external tools

How to ask: One gate before spawning anything:

This involves [X]. Want me to research current best practices, or do you have enough context?

If AskUserQuestion is available:

• Yes, research first — Fetch current documentation for accurate implementation
• No, I have context — Proceed with what we have

How to execute: Spawn 2-3 parallel Sonnet agents (fast, cheap, good at retrieval) with specific, scoped questions. Not "research everything about X" — scope to what you actually need.

Example agent prompts:

• "Fetch current Supabase RLS patterns from official docs"
• "Find 2026 best practices for React Native navigation libraries"
• "Check if [library] is still actively maintained"

Use Context7 MCP when available: resolve-library-id → query-docs for library documentation.

How to use results: Feed research back into synthesis and strategy — inform the principles and architecture. Don't dump raw findings into reference files. Present key findings to user before proceeding.

---

Entry Point Detection

Detect what the user provided and route to the right workflow:

Detection Logic

1. Check $ARGUMENTS for URLs → from-source-material 2. Check $ARGUMENTS for file paths → read the file, determine if it's a skill (has YAML frontmatter with name/description) or source material 3. Check $ARGUMENTS for keywords: "audit", "review", "evaluate", "improve" → audit-existing-skill 4. Check $ARGUMENTS for keywords: "add reference", "add workflow", "add component" → add-component 5. Check $ARGUMENTS for keywords: "capture", "just did", "turn this into" → from-recent-work 6. If $ARGUMENTS contains a description → from-description 7. If no arguments, ask:

If AskUserQuestion is available:

• Turn source material into a skill — I have an article, talk, or framework
• Capture recent work — I just did something and want to save the process
• Describe what I want — I'll explain what the skill should do
• Audit an existing skill — Evaluate a skill I have or found

Otherwise ask: "What would you like to do? (1) Turn source material into a skill, (2) Capture a recent process, (3) Describe what I want, (4) Audit an existing skill"

After selecting a workflow, read it and follow it exactly.

---

Reference Index

All supporting knowledge in references/:

Workflow Index

Templates

Ready-to-copy starting points in templates/:

Skill Distillery

An agent skill that turns raw material — articles, talks, frameworks, recent AI work, or just an idea — into strategic, interactive skills. Bottom-up synthesis, not content reformatting.

What it does

Skill-distillery is a skill that creates skills. It works from four entry points:

From source material (/skill-distillery https://example.com/article) — Give it a URL, file, or pasted content. It reads the source, extracts principles and mental models bottom-up, then collaboratively designs the skill architecture with you.

From a description (/skill-distillery) — Describe what you want. If your description is detailed, it proposes an approach directly. If it's vague, it brainstorms with you until the idea is clear.

From recent work (/skill-distillery capture) — Just did something with AI and want to save the process? It extracts the repeatable workflow, decision points, and gotchas, then packages them as a reusable skill.

Audit an existing skill (/skill-distillery audit ~/.claude/skills/my-skill) — Runs any skill through a five-lens evaluation framework: synthesis quality, architecture, interactive design, spec compliance, and cross-agent compatibility. Produces a rated assessment with prioritized improvements.

The approach

Most skill creators assume you already know what you want to build. Skill-distillery starts earlier — from raw material — and works bottom-up.

A 5,000-word article doesn't become a skill by restructuring paragraphs into SKILL.md format. It becomes a skill when you extract the 5 principles that make the approach work, the mental model that organizes the domain, and the decision heuristics someone needs while doing the work. Then you design an interactive architecture around those extracted elements.

The workflow is collaborative: extract → validate → strategize → propose architecture → build. Every phase has a checkpoint where you confirm before proceeding. The skill suggests interactive patterns from proven skills (discovery phases, mode detection, conditional loading, wait gates) as opinionated defaults you can override.

Best experience on Claude Code

Skill-distillery works with any agent that supports skills, but it's designed to shine on Claude Code thanks to:

• AskUserQuestion — Tappable multiple-choice options for strategy decisions
• Parallel research agents — Spawns Sonnet agents for fast, scoped research when needed
• Agent tool — Launches specialized subagents for deep research

On other agents, these features degrade gracefully — AskUserQuestion becomes a plain-text question, parallel research becomes sequential, and the core workflow works the same way.

Install

One command (all agents)

npx skills add kylezantos/skill-distillery

Auto-detects your installed agents and installs to each. Works with Claude Code, Codex, OpenCode, Cursor, Gemini CLI, Windsurf, and 35+ more.

Target specific agents

npx skills add kylezantos/skill-distillery -a claude-code
npx skills add kylezantos/skill-distillery -a codex -a opencode

Manual install

Copy the entire skill-distillery/ directory into your agent's skills path:

Or clone:

git clone https://github.com/kylezantos/skill-distillery.git ~/.claude/skills/skill-distillery

Usage

/skill-distillery https://example.com/great-article
/skill-distillery ~/Documents/talk-transcript.md
/skill-distillery capture
/skill-distillery audit ~/.claude/skills/my-skill
/skill-distillery add reference
/skill-distillery

What's inside

skill-distillery/
├── SKILL.md                              # Router + principles + research protocol
├── workflows/
│   ├── from-source-material.md           # Article → skill (flagship)
│   ├── from-description.md               # Idea → skill
│   ├── from-recent-work.md               # Process → skill
│   ├── audit-existing-skill.md           # 5-lens audit framework
│   └── add-component.md                  # Extend existing skills
├── references/
│   ├── official-spec.md                  # 2026 skill specification
│   ├── synthesis-patterns.md             # Bottom-up extraction methodology
│   ├── architecture-decisions.md         # When to use simple vs. router
│   ├── interactive-design-patterns.md    # Discovery, modes, wait gates
│   ├── quality-checklist.md              # Validation checklist
│   └── cross-agent-compatibility.md      # Cross-agent portability guide
└── templates/
    ├── simple-skill.md                   # Single-file template
    └── router-skill.md                   # Multi-file template

Attribution

Built by Kyle Zantos. Synthesizes knowledge from Anthropic's official skill specification, the create-agent-skills and skill-creator skills from Compound Engineering, and interactive design patterns from several other skills we've created and iterated on.

Architecture Decisions

How to choose the right file structure for a skill. The goal is right-sized architecture — not too simple, not over-engineered.

Simple vs. Router: Decision Tree

Does the skill have multiple distinct user intents?
├── No → Does the content exceed 200 lines?
│   ├── No → SIMPLE (single SKILL.md)
│   └── Yes → SIMPLE with references (SKILL.md + 1-3 reference files)
└── Yes → Does each intent share core principles?
    ├── No → Consider separate skills instead of one complex skill
    └── Yes → ROUTER (SKILL.md + workflows/ + references/)

"Distinct user intents" means fundamentally different tasks:

• Create vs. Audit vs. Improve → distinct intents (router)
• Build a React app vs. Build a Vue app → same intent, different context (simple with references)

When to Add Each File Type

references/ — Domain Knowledge

Add when:

• Multiple workflows need the same knowledge
• Content is too detailed for SKILL.md (> 50 lines of dense material)
• Information is loaded conditionally (not every invocation needs it)
• Knowledge changes independently from procedures

Don't add when:

• Only one workflow uses it (inline it in that workflow)
• It's short enough to live in SKILL.md (< 30 lines)
• It duplicates what's already in the workflow

Name by domain concern, not by category:

• craft-purists.md not reference-1.md
• supabase-rls-patterns.md not database-docs.md

workflows/ — Step-by-Step Procedures

Add when:

• The skill has 2+ distinct user intents that share principles
• Each workflow needs different reference files loaded
• Procedures are sequential (Step 1 → Step 2 → Step 3)

Don't add when:

• There's only one workflow (put it directly in SKILL.md)
• The "workflow" is just "read this reference" (that's not a workflow)

Each workflow should:

• Start with ## Required Reading listing which references to load
• Contain actual implementation steps (not just "read references")
• End with success criteria
• Be self-contained enough to follow without re-reading SKILL.md

templates/ — Output Structures

Add when:

• The skill produces consistent output structures (plans, specs, reports, skill files)
• Structure matters more than creative generation
• Users need a starting point they can customize

Don't add when:

• Output varies too much between invocations
• The template is simple enough to describe inline

scripts/ — Executable Code

Add when:

• Same code is rewritten every invocation
• Deterministic reliability is needed
• Operations are error-prone when generated fresh each time

Don't add when:

• The code is simple enough to generate inline
• The code needs to adapt to context every time
• You're the only user (scripts add distribution complexity)

File Count Guidance

Signs you have too many files:

• Reference files under 30 lines (merge them)
• Workflows that share 80%+ content (consolidate)
• Files that are only read once by one workflow (inline)

Signs you have too few files:

• SKILL.md over 400 lines (split into references)
• Workflows loading the same big block of knowledge (extract to reference)
• Distinct user intents handled by conditional logic instead of separate workflows

Reference Organization

Organize by domain concern, not by content type:

Good — organized by what the user needs:

references/
├── craft-purists.md          # What craft-focused advisors say
├── hiring-managers.md        # What hiring managers look for
├── storytelling-narrative.md # How to structure project stories
└── contradictions.md         # When advisors disagree

Bad — organized by document type:

references/
├── quotes.md
├── checklists.md
├── examples.md
└── principles.md

Architecture Comparison: Kyle's Skills

Key insight from this comparison: File count should match knowledge diversity, not skill complexity. dive-club has many files because it has 4 distinct knowledge bases (lenses). language-market-fit is complex but all the knowledge is one domain, so 2 files suffice.

SKILL.md Content Rules

SKILL.md is always loaded. Use this guarantee strategically.

Put in SKILL.md (unavoidable):

• Core principles (3-7 that apply to ALL workflows)
• Entry point detection / routing logic
• Research protocol (when and how to research)
• Reference index (what files exist and when to load each)

Keep out of SKILL.md (loaded on demand):

• Detailed procedures (→ workflows)
• Deep domain knowledge (→ references)
• Templates and boilerplate (→ templates)
• Executable code (→ scripts)

Target length: 200-300 lines for router skills, under 200 for simple skills.

Cross-Agent Compatibility

Guide for ensuring skills work across multiple AI coding agents. Skills published on skills.sh see installs from Claude Code, Codex, OpenCode, Gemini CLI, Cursor, GitHub Copilot, and Kimi CLI.

What Works Everywhere

These features are universally supported or gracefully ignored:

Claude Code-Specific Features

These only work in Claude Code. Each needs a fallback strategy:

AskUserQuestion

What it does: Presents tappable multiple-choice options in the terminal.

Fallback: Add a plain-text question nearby. Other agents will use the text version.

## Step 3: Choose Approach

If AskUserQuestion is available, present as tappable options:
- "Guided" — Full discovery phase with multiple questions
- "Direct" — Execute immediately from provided input
- "Adaptive" — Light clarification, then execute

Otherwise, ask: "How interactive should this skill be?
(1) Guided with discovery, (2) Direct execution, (3) Adaptive"

Agent Tool / Subagent Spawning

What it does: Spawns parallel research agents with specific models.

Fallback: Describe the research task inline. Other agents will do it sequentially.

## Research Protocol

In Claude Code: Spawn 2-3 parallel Sonnet agents with scoped questions.

In other agents: Perform the following research sequentially:
1. Search for current [library] documentation
2. Find 2026 best practices for [topic]
3. Check for deprecated patterns

context: fork

What it does: Runs the skill in an isolated subagent context.

Fallback: None — this is a Claude Code execution model feature. Safe to include in frontmatter (other agents ignore unknown fields).

allowed-tools

What it does: Grants automatic tool permissions without user prompts.

Fallback: Other agents ignore this field (permissive by default or use their own permission model). Safe to include.

Dynamic Context Injection (` !command `)

What it does: Runs shell commands at load time, injects output into skill content.

Fallback: Provide equivalent instructions to run the command manually.

## Context
- Current branch: !`git branch --show-current`

If dynamic injection is not supported, run: `git branch --show-current`

disable-model-invocation / user-invocable

What it does: Controls whether the agent can auto-load the skill.

Fallback: Other agents ignore these fields. Safe to include — worst case, the skill is always available.

model Field

What it does: Forces a specific model (haiku, sonnet, opus).

Fallback: Other agents ignore this. The skill runs on whatever model is configured.

Writing Portable Instructions

Use action-oriented language, not tool-specific language

# Bad — Claude Code specific
Use the Read tool to read the file at path/to/file.md.
Then use the Glob tool to find all *.md files.

# Good — portable
Read the file at path/to/file.md.
Find all *.md files in the directory.

Reference tools by intent, not by name

# Bad
Use WebFetch to get the URL content.
Use Grep to search for the pattern.

# Good
Fetch the content at [URL].
Search the codebase for [pattern].

Exception: allowed-tools frontmatter

Tool names in allowed-tools are fine — this field is Claude Code-specific anyway and other agents ignore it.

Graceful Degradation Patterns

Pattern: Conditional Feature

If AskUserQuestion is available, use it for the following decision.
Otherwise, ask the question in plain text and wait for a response.

Pattern: Research Agent with Sequential Fallback

## Research Phase

**Parallel approach (Claude Code):** Spawn research agents for each topic.
**Sequential approach (other agents):** Research each topic in order:
1. [Topic A] — search for [specific query]
2. [Topic B] — fetch docs for [specific library]

Pattern: Progressive Enhancement

Structure the skill so the core workflow works everywhere, with Claude Code features as enhancements:

Core workflow (universal):
  Discovery questions → Synthesis → Build → Validate

Enhanced with Claude Code:
  AskUserQuestion for discovery → Agent-based research → Build → Validate

Degradation Rating System

After reviewing a skill, rate its cross-agent compatibility:

Full Compatibility

Works identically across all agents. No Claude Code-specific features, or all features have equivalent behavior everywhere.

Degrades Gracefully

Core functionality works on all agents. Claude Code users get enhanced experience (tappable options, parallel research, auto-permissions). Other agents get plain-text fallbacks that achieve the same outcome.

This is the target for most skills. Full compatibility sacrifices too much; Claude Code-dependent limits your audience.

Claude Code-Dependent

The skill relies on Claude Code-specific features with no fallback. Won't function meaningfully on other agents.

Acceptable for: Personal skills, team-internal skills, or skills that fundamentally require Claude Code features (subagent orchestration, isolated execution).

Review Checklist

• [ ] All AskUserQuestion calls have plain-text fallback questions nearby
• [ ] All Agent/subagent references describe the task inline for sequential execution
• [ ] Instructions use action-oriented language ("read the file") not tool names ("use Read tool")
• [ ] Frontmatter-only features (allowed-tools, context, model) are safe to ignore
• [ ] Dynamic context injection has manual command fallbacks
• [ ] Core workflow functions without any Claude Code-specific features
• [ ] Degradation rating assigned: Full / Graceful / Dependent

Independent Review Brief

Instructions for a review sub-agent evaluating a freshly built skill. This agent has NOT been involved in the building process — that's the point. Fresh eyes catch what the builder rationalizes past.

Setup

The orchestrator spawns you as an independent reviewer. You receive: 1. The path to the skill directory 2. Access to skill-distillery's reference files

Your Job

Read the skill cold. Then evaluate it from these angles — each targets a specific blind spot that builder agents commonly have.

Review Angles

1. Distillation Integrity

Builder blind spot: The builder spent time with the source material and thinks they distilled it. Often they just reorganized it.

What to check:

• Read the core principles. Are they genuinely extracted strategy, or reworded summaries of the source?
• Test: Could you explain each principle WITHOUT referencing the source material? If not, it's still a summary, not a distillation.
• Are principles actionable and testable, or are they descriptive statements?
• Is there a coherent mental model, or just a list of good ideas?

Red flags:

• Principles that sound like section headers from the source
• "Do good X" statements with no operational definition
• 7+ principles (likely under-consolidated)

2. Cold Start Test

Builder blind spot: The builder has full context from the conversation. They unconsciously assume the skill reader will too.

What to check:

• Read only SKILL.md. Could you invoke this skill and know exactly what to do without reading the builder's conversation?
• Are there implicit assumptions that only make sense if you watched the skill get built?
• Does the description contain enough trigger keywords that Claude would auto-load it in the right situations?
• If the skill has modes: is it obvious from the description which mode to pick?

Red flags:

• References to context that doesn't exist in the skill files ("as discussed", implicit audience assumptions)
• Description that's too generic to trigger correctly
• Missing instructions for the no-arguments case

3. Gotchas Authenticity

Builder blind spot: Builders generate plausible-sounding gotchas to check a box. Real gotchas come from knowing where Claude actually fails.

What to check:

• For each gotcha: Is this a REAL Claude failure mode for this specific domain, or a generic warning?
• Test: Has Claude actually demonstrated this failure? Would it naturally make this mistake without the warning?
• Are gotchas specific enough to be checkable? ("Don't do X because Y" not "Be careful with X")
• Are there obvious Claude failure modes for this domain that AREN'T listed?

Red flags:

• Gotchas that apply to any skill ("don't make assumptions")
• Warnings that describe human mistakes, not Claude mistakes
• Fewer than 3 gotchas for a non-trivial skill

4. Architecture Fit

Builder blind spot: Builders sometimes over-engineer during the build (adding files that weren't in the plan) or under-split (cramming too much into SKILL.md to avoid creating files).

What to check:

• Does the file count match the knowledge diversity? (Many files = many distinct knowledge domains, not just "it's complex")
• Are there reference files under 30 lines that should be merged?
• Is SKILL.md over 300 lines with content that should be in references?
• Does every file get loaded by at least one workflow? (No orphans)
• Is progressive disclosure actually working — or does every invocation load everything?

Red flags:

• Reference files that are only read by one workflow and are short (inline them)
• SKILL.md over 350 lines
• Files organized by document type (quotes.md, examples.md) instead of domain concern

5. Interactivity Quality

Builder blind spot: Builders focus on content quality and treat interactivity as an afterthought. Or they add interactivity mechanically without considering whether it improves the experience.

What to check:

• Do interactive patterns serve the user, or do they just slow things down?
• Are there wait gates at genuine decision points (not just "does this look right?" after every step)?
• If AskUserQuestion is used: are options meaningfully different, with clear labels and implications?
• Are there shortcuts for when the user already provided context via $ARGUMENTS?
• Would a user enjoy interacting with this, or would it feel bureaucratic?

Red flags:

• Wait gates after every step (over-cautious)
• No wait gates at all for a complex skill (under-cautious)
• AskUserQuestion options that are vague or overlap
• No shortcut detection (always asks full question battery even when context was provided)

6. Action Test

Builder blind spot: Skills that inform without changing behavior. The builder thinks "this is useful knowledge" when the real question is "does this change what the agent does?"

What to check:

• If you removed this skill entirely, would the agent's behavior visibly change?
• Does the skill produce different outputs for different user contexts, or is it one-size-fits-all?
• Are instructions operational (do X, check Y, if Z then A) or descriptive (X is important, Y matters)?

Red flags:

• Long explanatory sections with no operational instructions
• Principles stated as beliefs rather than checks
• No conditional logic based on user context

Output Format

Return your findings as a structured list. For each finding:

FINDING: [Short title]
Angle: [Which review angle — 1-6]
Severity: [Critical / Important / Nit]
What I found: [Specific observation with file:line references]
Suggested fix: [Concrete recommendation]

Severity guide:

• Critical — Skill won't work correctly or will mislead users
• Important — Skill works but misses an opportunity or has a notable weakness
• Nit — Polish item, take it or leave it

Only report findings you're genuinely confident about. If something seems fine, don't force a critique. An empty findings list is a valid outcome.

What NOT to Review

• Spec compliance (frontmatter, file naming) — the builder already ran the quality checklist for this
• Cross-agent compatibility — already reviewed in a separate step
• Writing style/formatting — unless it actively hurts usability

Interactive Design Patterns

Patterns for making skills interactive, strategic, and responsive to user context. Extracted from high-performing skills (design-portfolio-assistant, language-market-fit, soleio-design-hiring).

Pattern 1: Discovery-First Intake

Start every complex skill with discovery questions before doing anything. Prevents generic advice.

How it works: 1. Ask 2-3 questions at a time (not a wall of questions) 2. Present your understanding in a structured summary 3. Wait for user confirmation before proceeding 4. Adapt subsequent questions based on what you've learned

Implementation:

## Step 1: Discovery

Ask 2-3 questions at a time, covering:
- **Identity** — Who is the user, what's their context?
- **Goal** — What are they trying to accomplish?
- **Current state** — What exists already?

### Present Understanding

DISCOVERY COMPLETE

User profile: [summary] Goal: [what they want] Current state: [what exists]

Does this feel right? Should I adjust before proceeding?

### Wait for Confirmation
**STOP and wait.** Do not proceed until the user confirms or adjusts.

Why it matters: The same skill gives different advice to different users. A junior designer gets different portfolio advice than a senior design engineer. Discovery makes the skill context-aware.

Pattern 2: Mode Detection

Support multiple modes of operation with automatic detection and manual fallback.

Three detection strategies:

Via $ARGUMENTS parsing

Accepts `$ARGUMENTS` for direct mode selection:
- Contains "audit", "review" → Audit mode
- Contains "compose", "write", "create" → Compose mode
- Ambiguous → Ask: "Would you like me to audit existing copy or compose new copy?"

Via explicit question

## Choose Your Mode

> I can help two ways:
> 1. **Compose** — Write new copy together
> 2. **Audit** — Tear apart existing copy and rebuild what's broken
>
> Which one? And what's the product/page?

Via AskUserQuestion (tappable)

Use AskUserQuestion with options:
- "Compose" — Write new [thing] from scratch
- "Audit" — Evaluate and improve existing [thing]

Best practice: Try $ARGUMENTS detection first, fall back to asking.

Pattern 3: Conditional Reference Loading

Don't load all references for every invocation. Load based on user's context.

Implementation:

## Step 2: Load Relevant Knowledge

Based on confirmed context:
- **Read `references/craft-purists.md`** if craft quality is primary concern
- **Read `references/hiring-managers.md`** if job search is the goal
- **Always read `references/contradictions.md`** — prevents conflicting advice

**Mode-specific:**
- **Read `audit-checklist.md`** — Audit mode only
- **Read `references/storytelling.md`** — Plan mode only

Why it matters: Loading everything wastes context window. A user auditing their portfolio doesn't need the project discovery questionnaire. A user planning doesn't need the audit checklist.

Pattern 4: Wait Gates

Explicit stops that prevent the skill from charging ahead without user alignment.

When to use:

• After presenting a synthesis or understanding
• After proposing an architecture or approach
• Before implementing changes
• Before any destructive or irreversible action

Implementation:

**Wait gate:** Present assessment and ask before implementing anything.

STOP. Do not proceed until the user:
1. Confirms the assessment is accurate
2. Selects which improvements to implement
3. Or redirects to a different approach

Common mistake: Adding so many wait gates that the skill feels bureaucratic. Use them at genuine decision points, not after every step.

Pattern 5: AskUserQuestion Patterns

When AskUserQuestion is available, use it for tappable multiple-choice decisions.

When to use AskUserQuestion

• Binary or small-set decisions (2-4 options)
• When options have clear labels and descriptions
• When tapping is faster than typing

When NOT to use AskUserQuestion

• Open-ended questions ("What problem does this solve?")
• When you need detailed context (use plain text conversation)
• When there are more than 4 distinct options

Effective option design

Use AskUserQuestion:
Question: "How interactive should this skill be?"
Options:
1. "Guided" — Discovery phase, multiple questions, wait gates
2. "Direct" — User provides input, skill executes immediately
3. "Adaptive" — Ask 1-2 clarifying questions, then execute

Each option needs:

• A short label (1-3 words)
• A description that explains the implication (what happens if you choose this)

Fallback for non-Claude agents

Always include a plain-text version nearby:

If AskUserQuestion is available, present as tappable options. Otherwise, ask:
"How interactive should this skill be? (1) Guided with discovery, (2) Direct execution, (3) Adaptive with light clarification"

Pattern 6: Shortcut Detection

Skip questions the user has already answered.

Implementation:

### Shortcut: Provided Context

Before asking questions, check if the user provided:
- **URL or file path** — Read it to extract context
- **Detailed description** — Parse for answers to standard questions
- **Mode selection** — Via $ARGUMENTS

If provided, skip redundant questions. Present extracted understanding for
confirmation instead of asking from scratch.

Example from dive-club: If user provides a resume file, the skill reads it and skips the "What's your role? What's your career stage?" questions — presents extracted understanding for confirmation instead.

Pattern 7: Stress-Testing

Before finalizing output, challenge your own work from the user's perspective.

Implementation (from language-market-fit):

### Phase 4: Stress-Test Together

Don't just present final output — walk the user through your stress-test:

> **Playing skeptical [audience] for a moment:**
> - [Quote a specific part] — A [user type] seeing this would think: "___." Does that match your intent?
> - [Quote another part] — This could mean [X] or [Y]. Which interpretation do we want?
> - The biggest risk with this version is ___. Here's how I'd mitigate that: ___.

When to use: After generating output that the user will present to others (copy, portfolios, plans, documentation).

Pattern 8: Transparency

Be explicit about what's grounded in evidence vs. what's inferred.

Implementation (from language-market-fit):

For each recommendation:
- **Grounded** — Based on actual data/source material provided
- **Inferred** — Best inference without direct evidence

Flag: "I'm working from inference here because [reason]. The fastest way to get
real signal would be [specific suggestion]."

When to use:

• Source material is incomplete
• Recommendations go beyond what the data supports
• User needs to know confidence levels to make decisions

Combining Patterns

Most effective skills use 3-5 of these patterns together:

Official Skill Specification (2026)

Source: code.claude.com/docs/en/skills

Commands and Skills Are Merged

Custom slash commands and skills are now the same thing. .claude/commands/review.md and .claude/skills/review/SKILL.md both create /review. If both exist, the skill takes precedence.

SKILL.md Structure

YAML frontmatter + standard markdown body:

---
name: my-skill
description: What it does and when to use it
---

# My Skill

## Quick Start
[Immediate actionable guidance]

## Instructions
[Step-by-step procedures]

## Examples
[Concrete usage examples]

Frontmatter Reference

All fields are optional. Only description is recommended.

Invocation Control

Use `disable-model-invocation: true` for workflows with side effects: deploy, commit, triage, send messages. Prevents Claude from deciding to deploy because your code looks ready.

Use `user-invocable: false` for background knowledge: coding conventions, domain context, legacy system docs.

Skill Locations & Priority

Enterprise (highest) → Personal → Project → Plugin (lowest)

String Substitutions

If $ARGUMENTS is not present in the skill content, arguments are appended automatically.

Dynamic Context Injection

The ` !command ` syntax runs shell commands before content reaches Claude:

## Context
- Current branch: !`git branch --show-current`
- Changed files: !`gh pr diff --name-only`

Commands execute at load time. Claude only sees the output.

Progressive Disclosure

Three-level loading system:

1. Metadata (name + description) — Always in context (~100 words, ~2% context budget) 2. SKILL.md body — When skill triggers (<500 lines) 3. Supporting files — As needed by Claude (unlimited)

my-skill/
├── SKILL.md           # Entry point (required, under 500 lines)
├── reference.md       # Detailed docs (loaded when needed)
├── examples.md        # Usage examples (loaded when needed)
└── scripts/
    └── helper.py      # Utility script (executed, not loaded)

Link from SKILL.md: For API details, see [reference.md](reference.md).

Keep references one level deep. Claude may partially read files referenced from other referenced files.

Subagent Execution

Add context: fork to run in isolation:

---
name: deep-research
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly...

The skill content becomes the subagent's prompt. No access to conversation history.

Hooks in Skills

Skills can define lifecycle hooks via the hooks frontmatter field. These run shell commands at specific points during skill execution.

Use cases:

• Safety guardrails — Block destructive commands (rm -rf, DROP TABLE, force-push) while the skill is active
• Directory constraints — Restrict edits to specific paths during the skill's execution
• Logging — Track skill invocations for usage measurement
• Setup/teardown — Run setup scripts when the skill starts, cleanup when it ends

Hooks defined in a skill are scoped to that skill's lifecycle only — they don't affect the rest of the session.

Persistent Data Storage

Skills that need to store data across invocations can use ${CLAUDE_PLUGIN_DATA} — a stable folder that persists beyond skill upgrades. Store:

• Text logs (gotchas captured during usage, run history)
• JSON config (user preferences, cached API responses)
• SQLite databases (for structured data accumulation)

This is distinct from the skill directory itself, which may be overwritten on updates.

Writing Effective Descriptions

Frame descriptions as trigger conditions, not summaries. Claude scans descriptions to decide when to invoke a skill. Write them as "when should Claude reach for this?" not "what does this skill contain?"

# Good — trigger-oriented, tells Claude WHEN to activate
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

# Bad — summary that doesn't tell Claude when to activate
description: Helps with documents

# Bad — describes contents instead of triggers
description: A comprehensive guide to PDF manipulation with examples and best practices

Key Rules

• SKILL.md under 500 lines — split detailed content into reference files
• Standard markdown headings — ##, ### (not XML tags)
• Concrete examples — not abstract descriptions
• Consistent terminology throughout
• No time-sensitive information (use "current method" / "legacy" pattern)
• Default to one recommended approach with escape hatch, not a menu of options
• disable-model-invocation: true for any workflow with side effects
• Test with real usage scenarios, not test cases

Distribution

• Project skills: Commit .claude/skills/ to version control
• Plugins: Add skills/ directory to plugin
• Enterprise: Deploy via managed settings
• Marketplace: Package and publish to skills.sh

Quality Checklist

Run through this checklist after building or auditing a skill. Items are grouped by category and ordered by impact.

Gotchas (Highest Priority)

The most valuable content in any skill. Gotchas document where Claude typically fails with this domain. Check these first.

• [ ] Dedicated ## Gotchas section exists in SKILL.md or a loaded reference
• [ ] Each gotcha uses "don't do X because Y" structure (not vague warnings)
• [ ] Gotchas come from real Claude failure modes, not theoretical anti-patterns
• [ ] Gotchas are specific and actionable (Claude can check its own work against them)
• [ ] Common misinterpretations of the domain are called out
• [ ] If the skill involves external APIs/tools, version-specific pitfalls are documented

Frontmatter

• [ ] Valid YAML between --- delimiters
• [ ] name is lowercase-with-hyphens, matches directory name, max 64 chars
• [ ] description is specific, includes trigger keywords, max 1024 chars
• [ ] description framed as trigger conditions ("Use when..."), not a summary of contents
• [ ] description written in third person ("This skill..." or "Use when...")
• [ ] disable-model-invocation: true if skill has side effects (deploy, commit, send)
• [ ] allowed-tools set if specific tools are needed
• [ ] argument-hint set if skill accepts arguments

Structure

• [ ] SKILL.md under 500 lines (target: 200-300 for router skills)
• [ ] All supporting files one level deep from SKILL.md
• [ ] No nested reference chains (SKILL.md → ref.md → detail.md)
• [ ] Every file referenced in SKILL.md actually exists
• [ ] Every file in the directory is referenced somewhere
• [ ] Reference files organized by domain concern, not arbitrary category
• [ ] File names are lowercase-with-hyphens and descriptive

Content

• [ ] Standard markdown headings (##, ###) — not XML tags
• [ ] Core principles stated upfront in SKILL.md (always loaded)
• [ ] Concrete examples present (not abstract descriptions)
• [ ] No explanation of concepts Claude already knows
• [ ] Consistent terminology throughout (not mixing synonyms)
• [ ] No time-sensitive information without versioning
• [ ] Default recommendation with escape hatch (not a menu of equivalent options)

Interactivity

• [ ] Discovery phase present (if skill adapts based on user context)
• [ ] Questions asked 2-3 at a time (not a wall of questions)
• [ ] Wait gates at genuine decision points (not after every step)
• [ ] Mode detection via $ARGUMENTS with fallback question
• [ ] Reference loading is conditional (not all files loaded every time)
• [ ] Shortcuts for when user has already provided context
• [ ] AskUserQuestion has plain-text fallbacks for non-Claude agents

Invocation

• [ ] Invocable via /skill-name and produces correct behavior
• [ ] Auto-triggering works when description keywords match user input
• [ ] $ARGUMENTS are handled correctly (or appended if not referenced)
• [ ] Skill works when invoked with no arguments (handles gracefully)

Writing Quality

• [ ] Imperative/instructional tone ("To do X, do Y" not "You should do X")
• [ ] Dense and operational (not explanatory prose)
• [ ] Tables used for comparisons, routing, and decision mapping
• [ ] Parenthetical design rationale where helpful (explains WHY)
• [ ] No filler, hedging, or unnecessary transitions

Router-Specific (if applicable)

• [ ] Entry point detection logic covers all common inputs
• [ ] Routing table maps user signals to specific workflows
• [ ] Each workflow has ## Required Reading header
• [ ] Each workflow has success criteria
• [ ] Reference index lists all files with when to load each
• [ ] Workflow index lists all workflows with one-line purpose

Synthesis Patterns

How to extract strategy from source material bottom-up. The goal is to distill — not restructure. A 5,000-word article becomes a 300-line skill by extracting the signal, not by reformatting paragraphs.

The Distillation Mindset

Source material contains three layers: 1. Principles — The fundamental ideas that make this approach work (keep these) 2. Explanation — Context that helps readers understand the principles (compress or discard) 3. Filler — Repetition, hedging, transitions, anecdotes (discard)

The skill needs layer 1 intact, a fraction of layer 2, and none of layer 3.

Principle Extraction

Read the entire source material, then ask:

"If someone could only remember 3-7 things from this, what should they be?"

These are the core principles. They should be:

• Actionable — Each one changes what you do, not just what you think
• Non-obvious — Claude doesn't already know this (skip "write clean code")
• Testable — You can check whether you're following them

Extraction technique

1. Highlight every claim, rule, or recommendation in the source 2. Group related claims into themes 3. For each theme, write one principle that captures the essence 4. Test: "Could I explain this principle without referencing the source?" If no, it's still too tied to the original phrasing.

Example: language-market-fit

Source: A long article about writing marketing copy that converts.

Extracted principles (the "5 mental filters"): 1. Would someone Googling their problem recognize this in under 2 seconds? 2. Can I point to a specific customer struggle this line addresses? 3. Does this complete "Now you can ___" or "Our product is ___"? 4. Could a competitor paste this on their site? 5. If I showed this for 5 seconds, could they explain what the product does?

Notice: These aren't summary sentences. They're operational checks — things you actually run through while doing the work.

Mental Model Identification

Mental models are frameworks for thinking, not instructions. Look for:

• Decision trees — "If X, do Y. If Z, do A instead."
• Taxonomies — Categories that organize the domain (e.g., dive-club's four advisor lenses)
• Spectrums — Scales with endpoints (e.g., "high freedom ↔ low freedom")
• Matrices — Two dimensions that create quadrants
• Process loops — Repeating cycles (build → test → refine)

Example: design-portfolio-assistant

Source: 16 podcast episodes with design leaders giving portfolio advice.

Extracted mental model: Four advisory lenses with context-dependent weighting.

• Craft Purists (visual quality, interactions)
• Hiring Managers (what actually gets hired)
• Builder-Launchers (shipping, visibility)
• The Strategist (business impact, narrative)

Plus a role-to-lens mapping table that determines which lens matters most based on the user's situation.

This mental model didn't exist in any single episode — it emerged from synthesis across all 16. That's the value of bottom-up extraction.

Context Separation

Not all advice applies universally. Separate:

Universal principles — Always true regardless of context:

• "Side projects speak louder than professional work" (portfolio advice)
• "Good copy comes from customer language, not clever wordsmithing" (copywriting)

Context-dependent guidance — True only in specific situations:

• "Lead with craft" (true for visual designers targeting agencies, not for product designers targeting startups)
• "Use struggle-framed headlines" (depends on product category and audience sophistication)

For context-dependent guidance, always document WHEN it applies. Use tables or conditional statements:

| Situation | Primary Approach | Why |
|-----------|-----------------|-----|
| Visual designer → agency | Lead with craft | Agencies hire on visual quality |
| Product designer → startup | Lead with impact | Startups hire on outcomes |

Anti-Pattern Mining

Every "do this" implies a "don't do that." Extract anti-patterns explicitly:

• Direct negatives — The source says "never do X" → document it
• Implied negatives — The source recommends A over B → document why B fails
• Common mistakes — The source describes what most people get wrong → document the patterns

Anti-patterns are often more useful than positive principles because they prevent specific failure modes.

Voice Preservation

The source material has a distinctive perspective. Preserve it:

• Keep signature phrases — If the author coined a term or has a memorable way of saying something, use it (with attribution)
• Maintain the stance — If the source is opinionated and direct, the skill should be too. Don't flatten a provocative framework into bland advice.
• Cite, don't plagiarize — Use quotes for distinctive phrases. Paraphrase for general ideas.

Bad: Flattening "Your copy either 'looks like food' instantly or gets ignored" into "Make sure your copy is immediately understandable."

Good: Keeping the "looks like food" metaphor because it's more memorable and actionable than the generic version.

Compression Strategy

How much to keep

What to put where

Compression rules

1. Cut explanation of obvious concepts — Claude knows what a headline is 2. Replace paragraphs with tables — Comparison prose → comparison table 3. Replace stories with principles — Anecdote → the lesson it teaches 4. Merge overlapping advice — 3 slightly different ways of saying the same thing → 1 clear statement 5. Keep code examples short — Minimal working example, not full application

Router Skill Template

Use this template for multi-workflow skills with shared principles. Copy and customize.

SKILL.md Template

---
name: {{SKILL_NAME}}
description: "{{What it does across all modes}}. Use when {{trigger conditions}}. Triggers on: {{keyword1}}, {{keyword2}}, {{keyword3}}, {{keyword4}}."
argument-hint: "[{{expected input}}]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# {{Skill Display Name}}

{{1-3 sentence description. What is this skill's core insight or philosophy?}}

## Quick Start

**{{Workflow A}}:**
> "{{example invocation}}"

**{{Workflow B}}:**
> "{{example invocation}}"

**{{Workflow C}}:**
> "{{example invocation}}"

---

## Core Principles

These apply to ALL workflows:

1. **{{Principle 1}}** — {{Brief explanation}}
2. **{{Principle 2}}** — {{Brief explanation}}
3. **{{Principle 3}}** — {{Brief explanation}}
4. **{{Principle 4}}** — {{Brief explanation}}
5. **{{Principle 5}}** — {{Brief explanation}}

---

## Entry Point Detection

Detect what the user provided and route accordingly:

- {{Signal A}} → `workflows/{{workflow-a}}.md`
- {{Signal B}} → `workflows/{{workflow-b}}.md`
- {{Signal C}} → `workflows/{{workflow-c}}.md`
- Ambiguous → Ask for clarification

| User Input | Route To |
|-----------|----------|
| {{keyword}}, {{keyword}} | `workflows/{{workflow-a}}.md` |
| {{keyword}}, {{keyword}} | `workflows/{{workflow-b}}.md` |
| {{keyword}}, {{keyword}} | `workflows/{{workflow-c}}.md` |
| Other | Clarify, then route |

**After selecting a workflow, read it and follow it exactly.**

---

## Reference Index

All domain knowledge in `references/`:

| File | Contents | Load When |
|------|----------|-----------|
| `{{reference-a}}.md` | {{What it contains}} | {{When to load it}} |
| `{{reference-b}}.md` | {{What it contains}} | {{When to load it}} |
| `{{reference-c}}.md` | {{What it contains}} | Always |

## Workflow Index

| Workflow | Purpose |
|----------|---------|
| `{{workflow-a}}.md` | {{One-line description}} |
| `{{workflow-b}}.md` | {{One-line description}} |
| `{{workflow-c}}.md` | {{One-line description}} |

Workflow Template

# Workflow: {{Workflow Name}}

## Required Reading

Read these reference files before proceeding:
1. `references/{{relevant-file}}.md`
2. `references/{{another-file}}.md`

## Step 1: {{First Action}}

{{What to do. Be specific — actual implementation steps, not "read the references."}}

## Step 2: {{Second Action}}

{{What to do.}}

If AskUserQuestion is available, present decision as tappable options.
Otherwise, ask: "{{plain-text version of the question}}"

## Step 3: {{Third Action}}

{{What to do.}}

**Wait gate:** Present results and ask before proceeding.

## Step 4: {{Validate}}

{{How to verify the output is correct.}}

## Success Criteria

This workflow is complete when:
- [ ] {{Criterion 1}}
- [ ] {{Criterion 2}}
- [ ] {{Criterion 3}}

Reference Template

# {{Reference Topic}}

{{Brief overview — what this reference covers and when to use it.}}

## {{Section 1}}

{{Dense, operational content. Tables, decision trees, examples.}}

| Option | When to Use | Trade-off |
|--------|------------|-----------|
| {{A}} | {{scenario}} | {{trade-off}} |
| {{B}} | {{scenario}} | {{trade-off}} |

## {{Section 2}}

{{More operational content.}}

## Gotchas

Common failure points — where Claude gets this wrong:

- **Don't {{X}}** because {{Y}}. Instead, {{correct approach}}.
- **Don't {{X}}** because {{Y}}. Instead, {{correct approach}}.
- **Don't {{X}}** because {{Y}}. Instead, {{correct approach}}.

Customization Notes

• SKILL.md target: 200-300 lines. Push detail into workflows and references.
• Workflows: Each should be self-contained with Required Reading + Steps + Success Criteria
• References: Organized by domain concern, not by document type
• Wait gates: At discovery completion and before building/implementing
• AskUserQuestion: Always include plain-text fallback for cross-agent compatibility

Simple Skill Template

Use this template for single-workflow skills under 200 lines. Copy and customize.

---
name: {{SKILL_NAME}}
description: "{{What it does}}. Use when {{trigger conditions}}. Triggers on: {{keyword1}}, {{keyword2}}, {{keyword3}}."
argument-hint: "[{{expected input}}]"
allowed-tools: Read, Bash
---

# {{Skill Display Name}}

{{1-2 sentence philosophy or core insight. What mental model does this skill operate from?}}

## Quick Start

**Example invocations:**
> "{{example user input 1}}"
> "{{example user input 2}}"

---

## How This Skill Thinks

{{3-5 core principles or mental filters. These should be operational — things you actually check while doing the work, not abstract values.}}

1. **{{Principle 1}}** — {{Brief explanation}}
2. **{{Principle 2}}** — {{Brief explanation}}
3. **{{Principle 3}}** — {{Brief explanation}}

---

## Choose Your Mode

{{If the skill has modes, present them. If not, delete this section.}}

If the user specifies a mode, go directly to it. If not, ask:

> I can help two ways:
> 1. **{{Mode A}}** — {{Description}}
> 2. **{{Mode B}}** — {{Description}}
>
> Which one?

---

## Mode 1: {{Mode A Name}}

### Phase 1: {{Understanding / Discovery}}

{{Ask 2-3 questions to understand context. Don't proceed without context.}}

### Phase 2: {{Generate / Execute}}

{{Core workflow steps.}}

### Phase 3: {{Review / Stress-Test}}

{{Validate output. Present to user for feedback.}}

---

## Mode 2: {{Mode B Name}}

### Phase 1: {{Intake}}

{{Mode-specific intake.}}

### Phase 2: {{Diagnose / Analyze}}

{{Core workflow steps.}}

### Phase 3: {{Prioritize / Deliver}}

{{Structured output.}}

---

## Gotchas

Common failure points — where Claude gets this wrong:

- **Don't {{X}}** because {{Y}}. Instead, {{correct approach}}.
- **Don't {{X}}** because {{Y}}. Instead, {{correct approach}}.
- **Don't {{X}}** because {{Y}}. Instead, {{correct approach}}.

---

## Working With Incomplete Information

{{How the skill adapts when user doesn't have everything.}}

For the complete {{reference material name}}, see [reference.md](reference.md).

Customization Notes

• Delete unused sections — If no modes needed, remove the mode selection and collapse into a single workflow
• Add wait gates at discovery and architecture decision points
• Keep under 200 lines — If it grows beyond that, consider the router template instead
• Description should be under 1024 chars with specific trigger keywords

Workflow: Add Component

Add a reference file, workflow, script, or template to an existing skill.

Required Reading

Read this reference file before proceeding: 1. references/architecture-decisions.md

---

Step 1: Understand the Existing Skill

Read the target skill:

• Glob for all files in the skill directory
• Read SKILL.md to understand structure and current architecture
• Note existing references, workflows, templates, scripts

Present:

Current structure of [skill-name]:

[Directory tree]

>

What would you like to add?

If AskUserQuestion is available:

• Reference file — Domain knowledge that workflows can load
• Workflow — Step-by-step procedure for a new user intent
• Script — Executable code for deterministic tasks
• Template — Output structure for consistent results

Otherwise ask: "What type of component? (reference, workflow, script, or template)"

---

Step 2: Design the Component

Based on the component type:

Reference File

• What domain knowledge does it contain?
• Which workflows will load it?
• Is it organized by domain concern?
• Does it overlap with existing references? (merge instead of creating new)

Workflow

• What user intent does it serve?
• Which references does it need?
• Does it share principles with existing workflows?
• Does SKILL.md's routing table need updating?

Script

• What task does it automate?
• What are the inputs/outputs?
• What error handling is needed?

Template

• What output structure does it define?
• What parts are customizable vs. fixed?

Propose the component:

I'd add [type]/[filename].md with:

- [What it contains]

- [Which existing files reference it]

- [Changes needed to SKILL.md]

>

Does this fit, or should I adjust?

Wait gate: Confirm before creating.

---

Step 3: Build

1. Create the new file following the appropriate template pattern 2. Update SKILL.md:

• Add to reference/workflow index
• Update routing table (if new workflow)
• Add to any relevant loading conditions

3. Update any workflows that should reference the new component

---

Step 4: Validate

Quick check:

• [ ] New file is linked from SKILL.md
• [ ] File name is lowercase-with-hyphens
• [ ] Content is one level deep from SKILL.md
• [ ] SKILL.md still under 500 lines after updates
• [ ] No duplicate content with existing files

---

Success Criteria

• [ ] Component type and content confirmed with user
• [ ] File created in correct location
• [ ] SKILL.md updated with references and routing
• [ ] Existing workflows updated if needed
• [ ] Validation passed

Workflow: Audit Existing Skill

Run an existing skill through the full skill-distillery framework. Six evaluation lenses (gotchas first), rated assessment, prioritized improvements.

Required Reading

Read ALL reference files before proceeding: 1. references/official-spec.md 2. references/synthesis-patterns.md 3. references/architecture-decisions.md 4. references/interactive-design-patterns.md 5. references/quality-checklist.md 6. references/cross-agent-compatibility.md

---

Step 1: Ingest the Skill

Locate and Read

• If user provides a path to a skill directory → read everything in it
• If user provides a SKILL.md path → read it and glob for siblings
• If user provides a skill name → search ~/.claude/skills/, .claude/skills/, and plugin caches

Glob for all files in the skill directory:

[skill-name]/
├── SKILL.md
├── **/*.md
├── **/*.py
└── **/*

Read SKILL.md and every supporting file (references, workflows, templates, scripts).

Present Inventory

SKILL INVENTORY: [skill-name]

Files: [count]
Total lines: [count]
Structure: [Simple / Simple + References / Router]

[Directory tree showing all files]

Understand Context

Ask: "What's the context for this audit?"

If AskUserQuestion is available:

• I built this — Give me improvement suggestions I can implement
• Plugin/marketplace skill — Tell me what I'd change if it were mine
• Evaluating before installing — Help me decide if it's worth using

Otherwise ask: "Did you build this, install it from a plugin, or are you evaluating it?"

This calibrates the audit tone: your own skill gets constructive suggestions, an external skill gets an honest assessment.

Wait gate: Confirm context before proceeding with evaluation.

---

Step 2: Gotchas Review (Highest Priority)

The most valuable content in any skill. Evaluate this first.

Questions to assess:

• Does the skill have a dedicated gotchas section?
• Are gotchas structured as "don't do X because Y" (not vague warnings)?
• Do they target real Claude failure modes for this domain?
• Are they specific enough that Claude can check its own work against them?
• Are common domain misinterpretations called out?
• For skills involving external tools/APIs: are version-specific pitfalls documented?

Rating:

• Strong — 5+ specific, actionable gotchas targeting real Claude failure points
• Present but weak — Has some gotchas/anti-patterns but they're vague or theoretical
• Missing — No gotchas section or only generic advice

---

Step 3: Synthesis Quality Review

Evaluate the skill's intellectual foundation.

Questions to assess:

• Are core principles clearly stated upfront in SKILL.md?
• Is there a coherent mental model, or is it just a list of instructions?
• Does it separate universal principles from context-dependent advice?
• Is the source material's distinctive perspective preserved, or was it flattened?
• Are anti-patterns documented?
• Would someone understand WHY the skill works, not just HOW to use it?

Rating:

• Strong — Clear principles, coherent mental model, distinctive perspective
• Adequate — Has some principles but could be more structured
• Needs work — Just instructions without underlying framework

---

Step 4: Architecture Review

Evaluate the file structure.

Questions to assess:

• Is the file structure right-sized? (too many tiny files? everything in one file?)
• Simple vs. router: is the choice appropriate for the skill's complexity?
• Are references organized by domain concern (not arbitrary category)?
• Is progressive disclosure working? (SKILL.md lean, references loaded conditionally?)
• Are there files that should be merged? Split? Moved?
• Does every file serve a clear purpose?

Rating:

• Well-architected — Right-sized, organized by concern, progressive disclosure works
• Functional — Works but could be better organized
• Needs restructuring — Over-engineered, under-structured, or poorly organized

---

Step 5: Interactive Design Review

Evaluate how the skill handles user interaction.

Questions to assess:

• Does the skill have a discovery phase? (should it, given its complexity?)
• Are there wait gates at critical decision points?
• Does it support multiple modes? (should it?)
• How does it handle $ARGUMENTS? (detection + fallback?)
• Does it use AskUserQuestion? (or should it?)
• Does it provide shortcuts when context is already available?
• Is it transparent about confidence levels?
• Does it ask 2-3 questions at a time (not a wall)?

Rating:

• Highly interactive — Discovery, modes, wait gates, conditional loading
• Moderately interactive — Some interactivity but could be more responsive
• Static — No adaptation to user context
• Needs interactivity — Would significantly benefit from interactive patterns

---

Step 6: Spec Compliance Review

Evaluate against the official specification.

Checklist:

• [ ] Valid YAML frontmatter between --- delimiters
• [ ] name is lowercase-with-hyphens, matches directory
• [ ] description specific with trigger keywords, under 1024 chars
• [ ] disable-model-invocation: true if skill has side effects
• [ ] SKILL.md under 500 lines
• [ ] Standard markdown headings (not XML tags)
• [ ] All referenced files exist and are properly linked
• [ ] References one level deep (no nested chains)
• [ ] Concrete examples present (not abstract)
• [ ] Consistent terminology

Rating:

• Fully compliant — All checklist items pass
• Minor issues — 1-3 items need fixes (cosmetic or low-impact)
• Needs fixes — 4+ items fail or critical issues present

---

Step 7: Cross-Agent Compatibility Review

Evaluate portability across AI coding agents.

Checklist:

• [ ] Claude Code-specific features identified
• [ ] AskUserQuestion calls have plain-text fallbacks
• [ ] Agent/subagent references describe tasks inline
• [ ] Instructions use action-oriented language (not tool names)
• [ ] Frontmatter-only features are safe to ignore
• [ ] Core workflow functions without Claude Code features

Rating:

• Full compatibility — Works identically across agents
• Degrades gracefully — Core works everywhere, enhanced on Claude Code
• Claude Code-dependent — Won't function on other agents

---

Step 8: Present Full Assessment

Format the results:

SKILL AUDIT: [skill-name]

Files: [count] | Lines: [total] | Structure: [type]

┌─────────────────────────────┬────────────────────┐
│ Lens                        │ Rating             │
├─────────────────────────────┼────────────────────┤
│ Gotchas                     │ [rating]           │
│ Synthesis Quality           │ [rating]           │
│ Architecture                │ [rating]           │
│ Interactive Design          │ [rating]           │
│ Spec Compliance             │ [rating]           │
│ Cross-Agent Compatibility   │ [rating]           │
└─────────────────────────────┴────────────────────┘

PRIORITY IMPROVEMENTS:

1. [Critical] [Title]
   What: [what's wrong]
   Why: [why it matters]
   Fix: [what the fix looks like]

2. [Important] [Title]
   What: [what's wrong]
   Why: [why it matters]
   Fix: [what the fix looks like]

3. [Opportunity] [Title]
   What: [could be better]
   Why: [the benefit]
   Fix: [what to change]

Wait gate: Present the full assessment. Ask before implementing anything.

---

Step 9: Implement Improvements

Present improvements as a selectable list.

If AskUserQuestion is available (multi-select):

• Each improvement as an option with description
• User taps which ones to implement

Otherwise: "Which improvements would you like me to implement? List the numbers."

For each selected improvement:

1. Read the relevant file(s) 2. Make the changes 3. Re-run the relevant review step to verify the fix

If restructuring is needed:

• Propose the new structure first
• Wait for approval
• Then implement (create new files, move content, update references)

---

Step 10: Final Report

After implementing selected improvements:

AUDIT COMPLETE: [skill-name]

Changes Made:
- [Improvement 1] — [what changed]
- [Improvement 2] — [what changed]

Rating Changes:
│ Lens                    │ Before    │ After     │
│ [lens]                  │ [rating]  │ [rating]  │

Remaining Recommendations:
- [Anything not implemented that's worth doing later]

---

Success Criteria

This workflow is complete when:

• [ ] All skill files read and inventoried
• [ ] Audit context understood (user built it, plugin, evaluating)
• [ ] All 6 lenses evaluated with ratings (gotchas first)
• [ ] Prioritized improvements presented
• [ ] User selected which improvements to implement
• [ ] Selected improvements implemented and verified
• [ ] Before/after comparison presented

Workflow: From Description

User describes what they want the skill to accomplish. Brainstorm if vague, propose directly if detailed.

Required Reading

Read these reference files before proceeding: 1. references/interactive-design-patterns.md 2. references/architecture-decisions.md

---

Step 1: Listen & Assess

Read what the user provided. Determine which path to take:

Path A: Detailed Description

The user gave a clear, specific description of what the skill should do. Signs:

• Named specific functionality
• Described who it's for
• Mentioned trigger conditions or use cases
• Referenced similar tools or approaches

Action: Skip heavy brainstorming. Go directly to proposal:

That's clear. To accomplish that, I'd structure it this way:

>

Name: [suggested-name]

Core function: [what it does]

Entry points: [how users would invoke it]

Complexity: [Simple / Medium / Complex]

>

Sound right, or should I dig deeper on anything?

If user confirms → proceed to Step 3 (Strategy).

Path B: Vague or Exploratory

The user has an idea but hasn't fleshed it out. Signs:

• "I want something that helps with..."
• "Can you make a skill for..."
• General domain without specific functionality
• No mention of who it's for or when to use it

Action: Brainstorm together. Ask 2-3 questions:

Use AskUserQuestion if available, plain text otherwise:

1. "What problem does this skill solve?"

• What's the frustration or gap today?
• What triggers someone to need this?

2. "What does success look like after using it?"

• What's different? What did they produce?
• How would they know it worked?

3. "Can you give an example of how you'd use it?"

• "I'd type /skill-name and then..."
• Concrete scenario, not abstract description

Identify Skill Type

Based on the user's answers, identify which type of skill they're building. This shapes architecture decisions downstream.

Present to user:

Based on what you've described, this sounds like a [type] skill. Does that match your intent?

This doesn't lock anything in — it's a lens that helps make better architecture choices later.

Decision Gate

After initial questions and type identification:

Ready to proceed with building, or would you like to explore more?

If AskUserQuestion is available:

• Proceed — I have enough context to propose an approach
• Explore more — There are more details to clarify
• Let me add context — I want to provide additional information

---

Step 2: Research (if needed)

Follow the Research Protocol from SKILL.md:

• If the skill involves external APIs/libraries, trigger the research gate
• Ask: "This involves [X]. Want me to research current best practices, or do you have enough context?"
• If yes: spawn 2-3 parallel Sonnet agents with scoped questions (Context7 for library docs, WebSearch for patterns)
• Feed findings back into the proposal — don't dump into skill files
• If the user already knows the domain well: skip entirely

---

Step 3-11: Convergent Process

From here, follow the same process as the source-material workflow:

Step 3: Skill Strategy — Interactive decisions about audience, invocation, interactivity, modes, complexity, and target agents. See workflows/from-source-material.md Step 3.

Step 4: Architecture Proposal — Propose exact file structure with rationale. Wait for approval. See workflows/from-source-material.md Step 4.

Step 5: Build — Create all files following official spec. See workflows/from-source-material.md Step 5.

Step 6: Gotchas Review — Ensure gotchas section is populated with real Claude failure modes. See workflows/from-source-material.md Step 6.

Step 7: Validate — Run quality checklist (gotchas first). See workflows/from-source-material.md Step 7.

Step 8: Cross-Agent Compatibility Review — Evaluate cross-agent support, informed by target agent choice. See workflows/from-source-material.md Step 8.

Step 9: Generate README — Create a publication-ready README.md with install command and skill overview. See workflows/from-source-material.md Step 9.

Step 10: Independent Review (Optional) — Offer fresh-eyes review from an independent sub-agent. See workflows/from-source-material.md Step 10.

Step 11: Publication (Optional) — Offer to publish to GitHub for npx skills add installation. See workflows/from-source-material.md Step 11.

---

Success Criteria

This workflow is complete when:

• [ ] User's intent clearly understood (via detailed description or brainstorming)
• [ ] Research done if external dependencies involved
• [ ] Strategy decisions made interactively (including target agents)
• [ ] Architecture proposed and approved
• [ ] All files created following official spec
• [ ] Gotchas section reviewed and populated
• [ ] Quality checklist passed
• [ ] Cross-agent compatibility reviewed
• [ ] README.md generated
• [ ] Independent review offered (and completed if accepted)
• [ ] Publication offered (and completed if accepted)

Workflow: From Recent Work

Capture a process you just did with AI as a reusable skill. Turn "I figured this out" into "anyone can do this."

Required Reading

Read these reference files before proceeding: 1. references/synthesis-patterns.md 2. references/architecture-decisions.md

---

Step 1: Understand What Happened

Figure out what the user just did and what they learned.

Gather Context

Ask 2-3 questions:

1. "What did you just do? What was the task?"

• What problem were you solving?
• What was the end result?

2. "What did you figure out along the way?"

• Any non-obvious steps or gotchas?
• Decisions you had to make?
• Things that didn't work before you found what did?

3. "Do you want me to review our recent conversation for context?"

• If conversation history is available, scan it for the process
• If git history is relevant, offer to check recent commits

Source Material Options

Depending on what's available:

• Conversation history — Review recent messages for the process, decisions, and lessons learned
• Git history — Scan recent commits for what changed and why
• User description — Work from what they tell you
• Combination — Use all available sources

---

Step 2: Extract the Reusable Process

From whatever context you gathered, extract:

Repeatable Workflow

What steps would apply next time someone faces this problem? Order matters — what has to happen first?

Decision Points

What choices did you face? What did you decide and why? These become the skill's interactive decision points.

Pitfalls & Gotchas

What went wrong before it went right? What would you warn someone about?

Essential Tools & Commands

What specific tools, libraries, commands, or APIs were critical?

Present Extraction

CAPTURED PROCESS: [Task Name]

Workflow (repeatable steps):
1. [Step] — [Why this step matters]
2. [Step] — [Decision point: if X, do Y; if Z, do A]
3. [Step] — [Gotcha: watch out for...]

Key Decisions:
- [Decision] → [What we chose and why]

Pitfalls:
- [Thing that went wrong] → [How to avoid it]

Tools Used:
- [Tool/library] for [purpose]

Here's what I captured from the process. Does this cover the important parts? Anything I'm missing or got wrong?

Wait gate: Confirm extraction accuracy before proceeding.

---

Step 3-9: Convergent Process

From here, follow the same process as the source-material workflow:

Step 3: Skill Strategy — Interactive decisions about audience, invocation, interactivity, modes, complexity. See workflows/from-source-material.md Step 3.

Step 4: Architecture Proposal — Propose exact file structure with rationale. Wait for approval. See workflows/from-source-material.md Step 4.

Step 5: Build — Create all files following official spec. See workflows/from-source-material.md Step 5.

Step 6: Gotchas Review — Ensure gotchas section is populated with real Claude failure modes. See workflows/from-source-material.md Step 6.

Step 7: Validate — Run quality checklist (gotchas first). See workflows/from-source-material.md Step 7.

Step 8: Cross-Agent Compatibility Review — Evaluate cross-agent support. See workflows/from-source-material.md Step 8.

Step 9: Independent Review (Optional) — Offer fresh-eyes review from an independent sub-agent. See workflows/from-source-material.md Step 9.

---

Success Criteria

This workflow is complete when:

• [ ] Process understood from conversation history, git history, or user description
• [ ] Reusable workflow extracted with decision points and pitfalls
• [ ] Extraction validated by user
• [ ] Strategy decisions made interactively
• [ ] Architecture proposed and approved
• [ ] All files created following official spec
• [ ] Gotchas section reviewed and populated
• [ ] Quality checklist passed
• [ ] Cross-agent compatibility reviewed
• [ ] Independent review offered (and completed if accepted)

Workflow: From Source Material

Turn an article, talk, framework, or advice into a strategic, interactive skill.

Required Reading

Read these reference files before proceeding: 1. references/synthesis-patterns.md 2. references/architecture-decisions.md

---

Step 1: Ingest Source Material

Detect what the user provided and ingest it:

• URL — Fetch with WebFetch, extract the content
• File path — Read the file (supports .md, .pdf, .txt, .html)
• Pasted content — Work with what's in the conversation

After reading, present a brief summary:

Here's what I'm working with: [title/topic] — [1-2 sentence summary of what the source covers].

Is this the right source? Anything I should know about your intent before I start extracting?

Wait gate: Confirm the source is correct before proceeding.

---

Step 2: Bottom-Up Extraction

Extract strategy from the source material. Do NOT restructure it — distill it.

For each of these categories, identify what the source provides:

Core Principles (3-7)

What are the fundamental ideas that make this approach work? Each should be actionable, non-obvious, and testable.

Mental Models

What frameworks does this teach for thinking about the problem? Decision trees, taxonomies, spectrums, matrices, or process loops.

Decision Heuristics

What rules-of-thumb does it provide? "If X, do Y. If Z, do A instead."

Context Separation

Which advice always applies (universal) vs. which depends on the situation (context-dependent)?

Gotchas & Anti-Patterns

What does it say NOT to do? What common mistakes does it call out? Where would Claude specifically be likely to fail when applying this knowledge? Structure each as "don't do X because Y."

Success Criteria

How would you know you're doing this well? What does good output look like?

Present Synthesis

Format as a structured summary:

SYNTHESIS: [Source Title]

Core Principles:
1. [Principle] — [One-line explanation]
2. [Principle] — [One-line explanation]
3. ...

Mental Model: [Brief description of the framework]

Key Heuristics:
- If [X], then [Y]
- If [Z], then [A]

Gotchas (where Claude will fail):
- Don't [X] because [Y]
- Don't [X] because [Y]

Context-Dependent (not universal):
- [Advice] applies when [condition]

Here's what I extracted from the source. Does this capture the essence? Anything missing, wrong, or that I'm weighting too heavily?

Wait gate: Do not proceed until the user validates the synthesis. Adjust if they push back.

---

Step 3: Skill Strategy

Interactive decisions about how the skill should work. Use AskUserQuestion where available, plain-text questions as fallback.

Question 1: Audience

"Who is this skill for?"

If AskUserQuestion is available:

• Just me — Personal use, can assume my context
• My team — Shared context, needs to be clear to others
• Public — Anyone installing it, needs to be self-explanatory

Otherwise ask: "Is this for personal use, your team, or public distribution?"

Question 2: Invocation

"What should trigger this skill?"

• Manual only — User invokes via /command (set disable-model-invocation: true)
• Auto-detect — Claude loads when relevant (description-driven)
• Both — User can invoke manually, Claude can also auto-detect (default)

Question 3: Interactivity

"How interactive should this skill be?"

• Guided — Discovery phase, multiple questions, wait gates (like design-portfolio-assistant)
• Direct — User provides input, skill executes immediately
• Adaptive — Ask 1-2 clarifying questions, then execute (like language-market-fit)

Question 4: Modes

"Does this skill need multiple modes?"

• Yes — [Ask user to describe the modes]
• No — Single workflow
• Not sure — "Based on the source material, I'd suggest [recommendation]. Does that feel right?"

Question 5: Complexity

"How complex is the knowledge?" (determines file structure)

• Simple — Everything fits in one file (<200 lines of instruction)
• Medium — Needs 1-3 reference files for depth
• Complex — Multiple workflows + references + maybe templates

Question 6: Target Agents

"Where will this skill be used?"

• Claude Code only — Personal/team use, can use all Claude Code features (AskUserQuestion, Agent tool, allowed-tools, etc.) without fallbacks
• Claude Code primary, others welcome (recommended for public skills) — Build for Claude Code but include plain-text fallbacks so other agents (Cursor, Codex, Kimi CLI, etc.) can use it
• Universal — Must work equally well across all agents. No Claude Code-specific features — use action-oriented language throughout, no AskUserQuestion, no Agent tool references

This answer shapes the entire build:

• Claude Code only: Use AskUserQuestion freely, reference specific tools, use allowed-tools and context: fork without concern
• Claude Code primary: Use AskUserQuestion with plain-text fallbacks, action-oriented language for instructions, allowed-tools is fine (ignored by other agents)
• Universal: Plain-text questions only, no tool-name references, no agent-specific features

Research Gate

If the skill involves external APIs, libraries, or domains where best practices shift fast:

This involves [X]. Want me to research current best practices before building, or do you have enough context?

If research requested: spawn 2-3 parallel Sonnet agents with scoped questions (one per topic). Present findings before proceeding.

---

Step 4: Architecture Proposal

Based on the strategy decisions, propose the exact file structure:

PROPOSED ARCHITECTURE: [skill-name]

Structure: [Simple / Simple + References / Router]

[skill-name]/
├── SKILL.md                    # [What goes here]
├── references/                 # [If needed]
│   ├── [file-a].md            # [What it contains]
│   └── [file-b].md            # [What it contains]
└── workflows/                  # [If router pattern]
    ├── [workflow-a].md         # [What it does]
    └── [workflow-b].md         # [What it does]

Rationale:
- [Why this structure vs. alternatives]
- [What goes in SKILL.md vs. references]
- [Why X reference files, not more/fewer]

Here's my proposed structure. Shall I proceed, or would you adjust anything?

Wait gate: Do not build until user approves the architecture.

---

Step 5: Build

Create all files following the official spec. Order: 1. Reference files first (foundation) 2. Workflow files (if router pattern) 3. SKILL.md last (references everything else)

For each file:

• Follow the appropriate template from templates/ as a starting point
• Adapt based on the synthesis from Step 2 and strategy from Step 3
• Use standard markdown headings
• Keep SKILL.md under the line limit (200 for simple, 300 for router)
• Include concrete examples from the source material

If decisions arise during build, use AskUserQuestion or ask in plain text. Don't guess on important choices.

---

Step 6: Gotchas Review

Before validation, explicitly review the skill's gotchas content. This is the highest-signal content in any skill.

Check:

• Does the skill have a dedicated ## Gotchas section (in SKILL.md or a reference file)?
• Are there at least 3-5 specific gotchas for non-trivial skills?
• Does each gotcha use "don't do X because Y" structure?
• Are gotchas based on real Claude failure modes (not theoretical warnings)?

If gotchas are thin or missing, think through: 1. What would Claude get wrong on first attempt applying this knowledge? 2. What are the most common misinterpretations of this domain? 3. What looks correct but is subtly wrong? 4. What does the source material explicitly warn against?

Add or strengthen gotchas before proceeding to validation.

---

Step 7: Validate

Read references/quality-checklist.md and run through every item (note: gotchas are now the first section):

• Frontmatter valid and complete
• Description includes trigger keywords
• Line counts within limits
• All files cross-referenced
• Standard markdown headings
• Concrete examples present
• Interactivity patterns in place (if applicable)

Present the validation report:

Skill created at [path]. Validation report:

- [X] items pass

- [Y] items need attention: [list them]

---

Step 8: Cross-Agent Compatibility Review

Read references/cross-agent-compatibility.md and evaluate:

• Identify every Claude Code-specific feature used
• Check for plain-text fallbacks
• Verify tool references are action-oriented (not tool-name-specific)
• Assign degradation rating

Present:

Cross-agent compatibility: [Degrades Gracefully / Full / Claude Code-Dependent]

- [X] features are Claude Code-enhanced with fallbacks

- [Y] features are universal

- [Specific fixes needed, if any]

---

Step 9: Generate README

Every skill gets a README.md — assume it may be published on GitHub.

Create README.md alongside SKILL.md with:

1. Skill name as heading 2. Install command prominently displayed:

   npx skills add <owner/repo>

Use a placeholder (owner/repo-name) if not yet published. Update later if the user publishes. 3. What it does — 2-3 sentences explaining the skill's purpose 4. Who it's for — target audience and common use cases 5. Usage examples — invocation commands (/skill-name, /skill-name argument) 6. What's inside — file tree showing SKILL.md + references 7. Compatibility — based on the target agent answer from Step 3:

• Claude Code only: "Built for Claude Code."
• Claude Code primary: "Built for Claude Code. Degrades gracefully on other agents (Cursor, Codex, Kimi CLI, etc.)."
• Universal: "Works across all coding agents."

8. License — MIT unless user specifies otherwise

Keep the README concise — under 100 lines. It's a landing page, not documentation.

---

Step 10: Independent Review (Optional)

After validation, offer a fresh-eyes review from an independent sub-agent. This catches blind spots the builder develops from being too close to the work.

Skill looks good from my end. Want me to get a second opinion? I can spawn an independent review agent that reads the skill cold — no context from our building conversation — and flags anything it catches.

If AskUserQuestion is available:

• Yes, get a second opinion — Spawn review agent for fresh-eyes feedback
• No, ship it — Skill is ready as-is

If the user opts in:

Spawn the Review Agent

Read references/independent-review-brief.md for the full review instructions.

Spawn one sub-agent (Sonnet — fast and sharp enough for review work) with this brief:

You are an independent reviewer evaluating a freshly built skill. You were NOT involved in building it — that's the point.

>

Skill to review: [full path to skill directory]

>

Your instructions are in: [path to skill-distillery]/references/independent-review-brief.md — read that first.

>

Also read these skill-distillery references for evaluation criteria:

- references/synthesis-patterns.md

- references/interactive-design-patterns.md

- references/architecture-decisions.md

>

Then read the entire skill (all files) and evaluate it according to the review brief. Return structured findings.

Filter and Present

When the review agent returns findings, don't just pass them through. Act as a filter:

For each finding, give your honest assessment:

REVIEW FINDING: [Title]
Severity: [Critical / Important / Nit]
Reviewer says: [Their observation]
My take: [AGREE / DISAGREE / PARTIALLY AGREE] — [Brief rationale from your building context]

Be honest. If the reviewer caught something you missed, say so. If you disagree, explain why — you have context the reviewer doesn't. The user benefits from seeing both perspectives.

After presenting all findings with your assessments:

These are the reviewer's findings with my take on each. Which ones would you like me to fix?

If AskUserQuestion is available, present fixable items as selectable options. Otherwise ask for numbers.

Implement selected fixes, then confirm what changed.

---

Step 11: Publication (Optional)

After the skill is complete, offer to publish it for npx skills installation.

Want to publish this skill to GitHub so anyone can install it with npx skills add?

If AskUserQuestion is available:

• Yes, create a GitHub repo — Create a public repo, push the skill files, and update the README with the real install command
• No, keep it local — Skill stays in the local skills directory

If the user opts in:

1. Create a public GitHub repo via gh repo create <skill-name> --public 2. Copy all skill files (SKILL.md, references/, README.md) into a temp directory 3. Initialize git, commit, and push 4. Update the README.md install command from placeholder to the real owner/repo 5. Present the repo URL and install command:

Published at: https://github.com/<owner>/<repo>

>

Anyone can install with:

```

npx skills add <owner>/<repo>

```

>

It will auto-appear on skills.sh once people start installing it.

---

Success Criteria

This workflow is complete when:

• [ ] Source material read and understood
• [ ] Synthesis validated by user
• [ ] Strategy decisions made interactively (including target agents)
• [ ] Architecture proposed and approved
• [ ] All files created following official spec
• [ ] Gotchas section reviewed and populated with real failure modes
• [ ] Quality checklist passed
• [ ] Cross-agent compatibility reviewed (informed by target agent choice)
• [ ] README.md generated
• [ ] Independent review offered (and completed if accepted)
• [ ] Publication offered (and completed if accepted)
• [ ] User can invoke the skill and it works as designed