Skills builder

Universal Skills Builder

Build ANY type of Claude skill — from simple reference guides to complex multi-MCP workflow automations, visual generators, and everything in between. Use ultrathink for complex skill generation.

Critical Rules

• Iron Law (TDD): NO SKILL WITHOUT A FAILING TEST FIRST. Run a baseline scenario WITHOUT the skill present, capture verbatim failures, then write the skill. Applies to NEW skills AND EDITS. See references/source-patterns-2026.md §1.
• ALWAYS ask the user clarifying questions before generating, but CAP at 2-3 questions for action skills (mattpocock pattern) — start exploring after.
• For interview skills: ONE question per message, never batch.
• If you don't know enough about a domain, use WebSearch to research it first.
• Generate complete, production-ready skills — not stubs or placeholders. Minimal is fine — a 50-word skill that does one thing well beats a 500-line skill (mattpocock grill-me is 4 lines).
• Validate every generated skill: python ${CLAUDE_SKILL_DIR}/scripts/validate-skill.py <path>
• Cross-skill conflict detection: python ${CLAUDE_SKILL_DIR}/scripts/validate-skill.py --check-conflicts <path> (gap #3)
• Security-scan every generated skill: python ${CLAUDE_SKILL_DIR}/scripts/security-scan.py <path>
• Scaffold new skills: bash ${CLAUDE_SKILL_DIR}/scripts/scaffold-skill.sh <name> [target-dir] [--style minimal|gstack|mattpocock|discipline|default]
• Phase checkpoint (compaction-safe): bash ${CLAUDE_SKILL_DIR}/scripts/state-checkpoint.sh <skill-dir> set <phase> (gap #2)
• Snapshot before edit: bash ${CLAUDE_SKILL_DIR}/scripts/snapshot.sh <skill-dir> [tag] (gap #6)
• Restore: bash ${CLAUDE_SKILL_DIR}/scripts/restore.sh <skill-dir> --latest (gap #6)
• Live RED test: bash ${CLAUDE_SKILL_DIR}/scripts/red-test.sh <skill-dir> <scenario.txt> (gap #1)
• Hard-gate hook (one-time install per env): copy ${CLAUDE_SKILL_DIR}/hooks/settings-snippet.json into ~/.claude/settings.json to enforce "no Write to SKILL.md without <dir>.plan.approved marker" (gap #5)
• Skills work across Claude.ai, Claude Code, and API. Build for portability.
• Keep generated SKILL.md bodies under 500 lines (MAX, not target). Move detail into references/.
• Front-load the most important instructions in the first 5,000 tokens (compaction keeps only that much).
• Description = trigger conditions ONLY, never workflow summary. Workflow in description = Claude follows the description and skips the body. See references/source-patterns-2026.md §2.
• Self-Containment Promise: skills-builder runs end-to-end on its own bundled scripts and references. NEVER invoke another skill (grill-me, superpowers:brainstorming, superpowers:writing-plans, office-hours, etc.) at runtime. All grill / brainstorm / plan / TDD logic is owned inline + in references/built-in-*.md. Inspiration is credited in references/source-patterns-2026.md but NEVER chained.

Security Rules (Apply to EVERY Skill You Build)

• No hardcoded secrets — NEVER put API keys, tokens, passwords in any skill file. Use $ENV_VAR.
• No shell injection — NEVER pass $ARGUMENTS into dynamic context (exclamation-backtick) syntax. Use sanitize.py to validate input first.
• Least privilege tools — NEVER use allowed-tools: "Bash(*)". Scope to specific commands. Review if granting 5+ tool patterns.
• Side-effect guard — Skills that deploy, send, delete, or modify external state MUST set disable-model-invocation: true.
• Script safety — Bundled scripts MUST use subprocess.run([...]) not os.system() or shell=True. No network access unless explicitly required. No pip install from untrusted sources.
• Path safety — Validate file paths with python ${CLAUDE_SKILL_DIR}/scripts/sanitize.py --validate-path <path>. Never write to system directories.
• Output safety — Skills generating HTML MUST escape user content. Use python ${CLAUDE_SKILL_DIR}/scripts/sanitize.py --html-escape <content>.
• Rate limiting — Skills calling MCP/APIs in loops MUST include batch limits and delays. Never make unbounded API calls.
• Isolation — Use context: fork with agent: Explore for processing untrusted input (read-only sandbox).
• Rollback — Destructive skills MUST include rollback instructions. See references/rollback-patterns.md.
• Team trust — Project skills run for ALL team members. Recommend CODEOWNERS review for .claude/skills/ changes.
• See references/security-guide.md for the full threat model, checklist, and enterprise controls.

Instructions

Step 0: Determine Intent

User wants to...	Go to
Build a new skill from scratch	Workflow A
Build a skill from existing code/repo	Workflow B
Review/audit an existing skill	Workflow C
Fix or improve an existing skill	Workflow D
Convert a repetitive workflow into a skill	Workflow E
Find, download, and install an existing skill from GitHub	Workflow F

If unclear, ask: "Do you want to build a new skill, find an existing one, review one, or improve one?"

---

Workflow A: Build a New Skill (Interactive)

Phase 0: RED — Baseline Test (NEW, mandatory)

Before writing the skill, run a pressure scenario WITHOUT it present. Document verbatim:

• What the agent did
• What rationalizations it used
• Which pressures triggered violations

This is the failing test. If you can't articulate what failure looks like, you don't know what the skill should fix. See references/source-patterns-2026.md §1.

For new domains where there's no existing failure to baseline (e.g. "build me a skill for FastAPI docs"), skip this phase but flag the skill as untested in the final report.

Phase 1: Discovery

Mode selection — ask the user FIRST:

"Quick discovery (4-6 questions) or full grill (relentless one-by-one until every decision branch resolved)? Default: quick."

Mode	When to use	Style
quick	Skill purpose is clear, simple scope	Conversational, ~5 Qs total
grill	Complex skill, multiple modes, fuzzy requirements, user said "grill", "stress-test", "make sure this is right"	One Q per message, walk every branch, propose recommended answer for each

---

Quick mode:

Have a conversation — do NOT dump all questions at once.

First, ask these two:

1. What should the skill do? (Get a clear outcome)
2. What would someone say to trigger it? (Get 2-3 natural phrases)

Then, based on answers, follow up with:

• Who will use it? (Just you / team / public)
• Does it need external tools or MCP servers?
• Should it be manual-only (/skill-name) or auto-invoked by Claude?
• Does it take arguments? (e.g., /deploy staging, /fix-issue 123)

If the description is vague or you're unfamiliar with the domain, use WebSearch to research before proceeding.

---

Grill mode (skills-builder built-in relentless interview):

Owned by skills-builder. Full method in references/built-in-grill-method.md. Do NOT delegate to any other skill.

Walk every branch of the decision tree. ONE question per message. Wait for answer. Provide a recommended answer with each question.

Decision tree to walk (in order):

1. Outcome — what artifact does this skill produce? Concrete example?
2. Triggers — list 5+ phrases users would actually say. Reject jargon-only.
3. Mode — manual-only (/skill), auto-invoked by Claude, or both?
4. Side effects — does it deploy/send/delete/modify external state?
   • If yes → MUST use disable-model-invocation: true and rollback plan
5. Arguments — none, positional, or --flag-style? Variadic? Optional?
6. External deps — MCP servers? CLI tools? APIs? Auth?
7. Failure modes — top 3 ways it could go wrong. How to handle each?
8. Anti-pattern — what's the #1 way someone WILL misuse this?
9. Skill type — discipline / technique / pattern / reference / interview / pipeline-stage?
10. Style — default / minimal / gstack-specialist / mattpocock-XML / discipline?
11. Body length budget — <150 words / <200 / <500 / >500 (split refs)?
12. Chain — what skill comes BEFORE this? AFTER? (benefits-from, "After Completion")
13. Domain language — does the project have CONTEXT.md / docs/adr/? If yes, what terms are load-bearing?
14. Test plan — what's the RED scenario (run the failure WITHOUT skill present)?
15. Audience — just you / team / public marketplace?
16. Permissions — minimum tool set? Any Bash(*) warnings?

Rules during grill:

• ONE question per message. Never batch.
• Always propose a recommended answer ("My recommendation: X. Sound right?")
• If user answer is vague, push back: "Be more specific. Give me an example."
• If a question can be answered by exploring the codebase, explore the codebase instead of asking the user.
• Stop only when all 16 branches resolved OR user says "ship it".

After grill, the rest of Workflow A proceeds as normal — but with much higher resolution input.

Phase 1.5: Brainstorm (self-contained — built-in brainstorm method)

Owned by skills-builder. Full method in references/built-in-brainstorm-method.md. Do NOT delegate to any other skill.

Before settling on a design, explore intent and alternatives. Run if ANY of these are true:

• Skill scope spans 2+ workflows or modes
• User said "brainstorm", "think through", "options", "approach"
• Same problem could plausibly be solved by extending an existing skill instead

Three forcing prompts (answer all before continuing):

1. Intent — what problem is this skill solving for the user, in their voice? Not "build X" but "I waste 20 min every release figuring out which tests to run."
2. Alternatives — list 3+ ways to solve it. New skill / extend existing skill / hook / settings change / docs entry. Why is "new skill" the right shape?
3. Design surface — name the inputs, outputs, side effects, and the smallest possible interface. If the interface needs >5 args, the skill is doing too much.

If any answer is fuzzy, loop back to Phase 1 grill on that branch.

Skip Phase 1.5 when: skill is trivial (minimal-style 4-line skill), user explicitly says "skip brainstorm", or scope is one verb / one outcome.

Phase 1.7: Plan (self-contained — built-in plan method)

Write a plan artifact BEFORE generating code. Plan = ~/.claude/skills/<name>.plan.md (or .claude/skills/<name>.plan.md for project skills).

This phase is owned by skills-builder. Full method in references/built-in-plan-method.md. Do NOT delegate to any other skill.

Plan template:

# Plan: <skill-name>

## Goal
[One sentence — what the skill produces, for whom.]

## Non-goals
- [Out of scope 1]
- [Out of scope 2]

## Inputs / Outputs
- Inputs: [args, files, MCP, env vars]
- Outputs: [files written, side effects, return artifact]

## Phase checklist
- [ ] Frontmatter (name, description, allowed-tools, paths)
- [ ] Body skeleton (style: default | minimal | gstack | mattpocock | discipline)
- [ ] Scripts (list each + purpose)
- [ ] References (list each + purpose)
- [ ] Assets (list each)
- [ ] RED baseline test scenario captured
- [ ] Security review (10 domains)
- [ ] Pro Quality Gate score ≥ 14/18
- [ ] Test plan (triggering + functional + security)

## Review checkpoints
1. After frontmatter → user approves description + triggers
2. After body skeleton → user approves structure
3. Before security review → user approves complete content
4. After validation → user approves install location

## Risks
- [Risk 1 + mitigation]
- [Risk 2 + mitigation]

## Out-of-band tools / MCP needed
- [list]

## Done when
- [Acceptance criterion 1]
- [Acceptance criterion 2]

Rules:

• Write the plan to disk. NOT just in conversation. Survives compaction.
• Present plan to user. Get explicit approval. Quote: "Approve plan? (yes/edit)".
• Edits trigger re-write — do NOT just acknowledge verbally and proceed.
• Plan checkpoints become hard gates in Phase 6 generation.

Skip Phase 1.7 only when: minimal-style skill (single instruction, no scripts/references) AND user opts out explicitly.

Phase 2: Identify Type and Pattern

Match the user's need to a skill type and architectural pattern. Consult these references:

• For skill types (web, app, API, DevOps, data, docs, security, MCP, etc.): see references/skill-type-catalog.md
• For architectural patterns (pure instructions, scripts, templates, visual output, sequential, multi-MCP, iterative, subagent fork, etc.): see references/skill-patterns.md
• For ready-to-copy blueprints: see references/skill-type-blueprints.md

Tell the user which type and pattern you recommend and why. Get approval before continuing.

Phase 3: Generate Frontmatter

Build the YAML frontmatter. Consult references/frontmatter-reference.md for all fields, rules, and examples.

Key rules (always apply these):

• --- delimiters on both sides
• name: kebab-case, max 64 chars, no spaces/capitals, no "claude"/"anthropic" prefix
• description: TRIGGER CONDITIONS ONLY — never summarize the workflow. Start with "Use when...". Front-load symptoms, error messages, situations, file types, jargon. Workflow summaries become a shortcut Claude takes INSTEAD of reading the body (proven via testing — see references/source-patterns-2026.md §2). Make it slightly pushy on triggers — Claude under-triggers by default.
• Add disable-model-invocation: true for skills with side effects (deploy, send, delete)
• Add paths: for file-type-specific skills (e.g., "**/*.py")
• Add argument-hint: if the skill takes input
• No XML angle brackets anywhere in frontmatter

Description formula (updated 2026-04 — see references/source-patterns-2026.md §2):

Use when [trigger phrase 1], [trigger phrase 2], or [symptom/jargon].
[One short capability sentence — what it produces, no workflow steps.]
[Optional: Do NOT use for X.]

Anti-pattern — workflow summary in description:

# WRONG — summary becomes a shortcut Claude takes instead of reading the body
description: Use for TDD - write test first, watch fail, write minimal code, refactor

# RIGHT — triggers + outcome only
description: Use when implementing any feature or bugfix, before writing implementation code

Present the frontmatter to the user for approval before continuing.

Phase 4: Write the Skill Body (Superpowers Pattern)

ALL skills MUST follow the superpowers structure pattern. This is non-negotiable.

CRITICAL: Before writing any skill body, read references/superpowers-writing-guide.md. It contains:

• Category-specific templates (interview, automation, analysis, process, workflow)
• 15 golden rules from superpowers + mattpocock + gstack (84k-star repo)
• Writing techniques: hard gates, confrontation patterns, stage-aware routing, push patterns
• gstack pro patterns: parameterized arguments, allowed-tools scoping, cross-skill integration, trend output, conservative updates, mode detection

Match the template for the skill's category. Apply gstack patterns for professional-grade skills.

# Skill Name

[1-2 sentence overview of what the skill does and when it's used.]

<HARD-GATE>
[Non-negotiable constraint — what must NOT happen before X is done.
Example: "Do NOT write code until the user approves the design."]
</HARD-GATE>

## Anti-Pattern: "[Common Mistake Name]"
[Call out the #1 way people misuse this skill and why it fails.]

## Checklist

You MUST create a task for each of these items and complete them in order:

1. **Step name** — what to do
2. **Step name** — what to do
3. **Step name** — what to do
[...]

## Process Flow

` ` `dot
digraph skill_name {
    "Step 1" [shape=box];
    "Decision?" [shape=diamond];
    "Step 2" [shape=box];
    "Terminal state" [shape=doublecircle];
    
    "Step 1" -> "Decision?";
    "Decision?" -> "Step 2" [label="yes"];
    "Decision?" -> "Step 1" [label="no, revise"];
    "Step 2" -> "Terminal state";
}
` ` `

## The Process

**[Phase name]:**
- Detailed instructions for this phase
- Specific actions, not vague language
- One question/action at a time

**[Phase name]:**
- Next phase details
[...]

## Key Principles

- **Principle 1** — explanation
- **Principle 2** — explanation
- **Principle 3** — explanation

## After Completion

[What skill to invoke next, or what output to produce.]
[Skills MUST chain explicitly: "Invoke the X skill to proceed."]

Pattern rules (enforce on every skill):

• Hard gates first — <HARD-GATE> tags for non-negotiable constraints at the top
• Anti-patterns — call out the #1 misuse explicitly, right after the gate
• Numbered checklist — ordered steps Claude must track as tasks
• Process flow diagram — dot notation showing decision points and terminal states
• One question per message — skills that interact with user ask ONE thing at a time
• Explicit transitions — every skill names which skill comes next
• Pushy descriptions — descriptions front-load action verbs, include "You MUST" or "Use when" phrasing
• Be specific: python scripts/build.py --target prod not "build the thing"
• Put critical instructions at the very top — first 5,000 tokens survive compaction
• Use $ARGUMENTS / $0 / $1 for user input
• Use ${CLAUDE_SKILL_DIR} to reference bundled files
• Reference bundled files explicitly: "See reference.md"
• Keep under 500 lines — move details to references/

Side-effect skills (deploy, send, delete): set disable-model-invocation: true, add confirmation steps, include rollback instructions per references/rollback-patterns.md.

Visual output skills (HTML, charts): bundle a Python/JS script, use webbrowser.open(), keep output self-contained. ALWAYS escape user content with sanitize.py --html-escape before embedding in HTML to prevent XSS.

MCP skills: name exact tools (Call MCP tool: create_issue), handle disconnections, verify between calls. Add rate limiting when calling MCP tools in loops — max N items per batch, delay between calls, require user confirmation for large batches.

Skills taking $ARGUMENTS: validate input with python ${CLAUDE_SKILL_DIR}/scripts/sanitize.py --validate-path for file paths, --sanitize-args for shell arguments, --validate-url for URLs. NEVER pass raw $ARGUMENTS to shell commands.

Skills for teams (project-level): note in the skill's instructions that it runs for all team members. Recommend adding .claude/skills/ to CODEOWNERS. Use context: fork with agent: Explore for processing untrusted input in a read-only sandbox.

Phase 5: Plan File Structure (Superpowers Layout)

Single skill:

skill-name/
├── SKILL.md              # Required — main instructions (under 500 lines)
├── scripts/              # Optional — deterministic logic
├── references/           # Optional — loaded on demand by Claude
└── assets/               # Optional — templates, static files

Plugin with multiple sub-skills (superpowers pattern):

plugin-name/
├── SKILL.md              # Plugin entry — overview + skill index
├── references/           # Shared knowledge across all sub-skills
│   ├── patterns.md
│   └── templates.md
├── skills/               # Individual sub-skills
│   ├── skill-one/
│   │   └── SKILL.md      # Registers as plugin-name:skill-one
│   └── skill-two/
│       └── SKILL.md      # Registers as plugin-name:skill-two
├── hooks/                # Optional — PreToolUse/PostToolUse hooks
├── agents/               # Optional — subagent definitions
├── scripts/              # Optional — shared scripts
└── plugin.json           # Optional — for marketplace publishing

When to use plugin structure: If building 3+ related skills that share references or chain together, use plugin layout. Sub-skills auto-register as plugin-name:skill-name.

Rules: SKILL.md exact spelling, folder = kebab-case matching name, no README.md inside, scripts use stdlib only when possible.

Or run: bash ${CLAUDE_SKILL_DIR}/scripts/scaffold-skill.sh <name> [target-dir]

Phase 6: Generate Everything

After user approves:

1. Create folder structure (or use scaffold script)
2. Write complete SKILL.md
3. Write all scripts (make executable with chmod +x)
4. Write all references and assets
5. Validate: python ${CLAUDE_SKILL_DIR}/scripts/validate-skill.py <path>
6. Provide installation instructions:

Scope	Path
Personal (all projects)	~/.claude/skills/<name>/SKILL.md
Project-only	.claude/skills/<name>/SKILL.md
Plugin	<plugin>/skills/<name>/SKILL.md
Managed (org-wide)	Via managed settings
Monorepo package	packages/<pkg>/.claude/skills/<name>/SKILL.md
Claude.ai	Zip folder → Settings → Skills → Upload
API	/v1/skills endpoint with container.skills

Phase 7: Security Review

Run the automated security scanner:

python ${CLAUDE_SKILL_DIR}/scripts/security-scan.py <path>

Then manually verify all 10 security domains:

#	Check	How
1	No secrets	No API keys/tokens/passwords in any file
2	Input validated	$ARGUMENTS validated with sanitize.py before use, never in shell
3	Output escaped	HTML skills escape user content (no XSS)
4	No untrusted deps	No pip install/npm install from unknown sources, no curl|sh
5	Least privilege	allowed-tools scoped to specific commands, not Bash(*)
6	Rollback included	Destructive skills have rollback instructions
7	Isolation used	context: fork for untrusted input processing
8	Side-effects guarded	disable-model-invocation: true for deploy/send/delete skills
9	Team-safe	Project skills don't grant excessive permissions to all devs
10	Rate-limited	MCP/API loops have batch limits and delays

Fix ALL findings before proceeding. See references/security-guide.md.

Phase 8: Pro Quality Gate (run before declaring skill complete)

Score every generated skill against these 18 checks. Minimum 14/18 to ship.

#	Check	Pass?
1	Has <HARD-GATE> with clear blocking constraint (discipline skills only)
2	Has named anti-pattern section
3	Has numbered checklist (tasks Claude tracks)
4	Description = TRIGGER CONDITIONS only — no workflow summary
5	Critical rules in first 5,000 tokens
6	One question per message for interview skills; max 2-3 questions for action skills
7	Explicit skill chaining ("Invoke X skill next")
8	Stage-aware routing (skips irrelevant steps based on context)
9	Confrontation/push patterns for weak answers (interview skills)
10	Tables for decisions, not prose
11	Good/Bad paired examples where applicable
12	ALWAYS/NEVER list for content modification skills
13	allowed-tools scoped (not Bash(*))
14	Arguments support if skill has modes (/skill arg)
15	Key Principles section at bottom (3-5 rules)
16	NEW: Baseline RED test run WITHOUT the skill — failures documented
17	NEW: Word count in budget (wc -w SKILL.md: <150 for getting-started, <200 frequently-loaded, <500 other)
18	NEW: Domain-language aware — reads CONTEXT.md / UBIQUITOUS_LANGUAGE.md / docs/adr/ if present, uses project terms in output, no file/line citations

Score < 14: Fix before shipping. Show user which checks failed. Score 14-16: Ship with notes on what could improve. Score 17-18: Perfect — ship it.

See references/source-patterns-2026.md for the full rationale behind checks 16-18 (TDD-for-skills, token efficiency, domain awareness — sourced from superpowers, mattpocock, gstack).

Phase 9: Test Plan

TRIGGERING:
  Should trigger: ["exact phrase", "paraphrased", "domain jargon"]
  Should NOT trigger: ["unrelated", "similar but out-of-scope"]

FUNCTIONAL:
  Test 1 (happy path): Given X → When Y → Then Z
  Test 2 (edge case): Given unusual input → graceful handling

SECURITY:
  Test: Invoke with malicious $ARGUMENTS (shell metacharacters, path traversal)
  Expected: Skill handles gracefully, no code execution, no file access outside scope

VERIFY:
  Ask Claude: "When would you use the [name] skill?"
  Invoke: /skill-name and check output

---

Workflow B: Build Skill from Existing Code/Repo

When the user points to existing code, a repo, a script, or a URL:

Step 1: Explore the Source

• Read the code/files the user points to
• If it's a URL, fetch it with WebFetch
• If it's a repo, explore the structure with Glob/Grep
• Understand: what does this code do? What's the workflow?

Step 2: Extract the Pattern

• What steps does the process follow? (sequential, branching, iterative?)
• What's constant vs. what changes each run?
• What are the inputs, outputs, and side effects?
• What domain knowledge is embedded that Claude needs?

Step 3: Identify Variables

• What changes per use → these become $ARGUMENTS or $0, $1
• What's configurable → these go in the instructions as decision points
• What's hardcoded → these become the skill's embedded knowledge

Step 4: Research if Needed

Use WebSearch to understand frameworks, APIs, or domain conventions the skill needs.

Step 5: Build

Proceed to Workflow A Phase 2 with the discovered information. Tell the user what you extracted and get confirmation before generating.

Example flow:

User: "Turn my deploy.sh into a skill"
→ Read deploy.sh
→ Extract: it runs tests, builds Docker image, pushes to ECR, updates ECS
→ Variables: environment ($0), image tag ($1)
→ Pattern: Sequential Workflow with side effects
→ Frontmatter: disable-model-invocation: true, argument-hint: "[env] [tag]"
→ Generate skill with the deploy steps as instructions

---

Workflow C: Review/Audit an Existing Skill

First run automated checks:

python ${CLAUDE_SKILL_DIR}/scripts/validate-skill.py <path>
python ${CLAUDE_SKILL_DIR}/scripts/security-scan.py <path>

Then manually audit across 5 levels:

Level 1 — Structure (Critical)

• File named exactly SKILL.md, folder is kebab-case
• YAML --- delimiters, no XML angle brackets
• name valid (lowercase, hyphens, max 64, no reserved prefix)

Level 2 — Security (Critical)

• No hardcoded secrets in any file (API keys, tokens, passwords, connection strings)
• No $ARGUMENTS in dynamic context (exclamation-backtick) — input validated with sanitize.py before use
• allowed-tools scoped to specific commands (never Bash(*), review if 5+ patterns)
• disable-model-invocation: true on skills with side effects
• Scripts use subprocess.run([...]) not os.system() or shell=True
• Scripts don't access network or env vars unless documented
• No credential files (.env, *.key) in the skill folder
• No pip install/npm install from untrusted sources, no curl|sh
• File write operations validate paths (no system directories)
• HTML output escapes user content (no XSS)
• MCP/API calls in loops have rate limits and batch caps
• context: fork considered for untrusted input processing
• Rollback instructions included for destructive operations
• Project skills safe for all team members (no excessive permissions)
• See references/security-guide.md for full checklist

Level 3 — Triggering (High)

• Description has WHAT + WHEN with specific trigger phrases
• First 250 chars contain the key use case (truncated in listings)
• Slightly "pushy" (Claude under-triggers by default)
• Negative triggers if needed ("Do NOT use for...")
• paths: set for file-type-specific skills

Level 4 — Instructions (Medium)

• Critical rules in first 5,000 tokens (survives compaction)
• Specific and actionable — no vague language
• Examples provided (2+), error handling included
• Under 500 lines, heavy content in references/
• $ARGUMENTS used correctly if skill takes input
• Bundled files referenced explicitly

Level 5 — Pro Patterns (High — from superpowers/gstack)

• Has <HARD-GATE> blocking constraint at top
• Has named anti-pattern section ("Anti-Pattern: [Name]")
• Has numbered checklist (tasks Claude tracks in order)
• Has Key Principles section at bottom (3-5 rules)
• Stage-aware routing (detects context, skips irrelevant steps)
• Confrontation/push patterns for interview questions
• Tables for decisions (not prose paragraphs)
• Good/Bad paired examples where applicable
• ALWAYS/NEVER lists for content modification
• Arguments support if skill has modes
• Explicit skill chaining to next skill
• DOT process flow diagram for complex workflows
• version in frontmatter

Level 6 — Advanced (Suggestions)

• Progressive disclosure (frontmatter → body → references)
• Scripts for critical validations
• allowed-tools pre-approves relevant tools
• context: fork for heavy isolated tasks
• Performance notes / "ultrathink" for complex skills
• Cross-skill integration via .context/ marker files
• Trend/comparison output with history persistence

Output: summary table with severity (Critical/High/Medium/Low) and specific fixes. Run Pro Quality Gate (Phase 8) scoring — report score out of 15.

---

Workflow D: Improve a Skill from Feedback

Symptom	Cause	Fix
Never triggers	Description too vague	Add trigger phrases, make pushier
Triggers on everything	Description too broad	Add "Do NOT use for...", set paths:, narrow scope
Instructions ignored	Critical rules buried	Move to top (first 5,000 tokens), use ## Critical header
Inconsistent results	Ambiguous language	Replace with exact commands/scripts
Model seems "lazy"	No encouragement	Add Performance Notes, include "ultrathink"
Context bloat / slow	Body too large	Move to references/, keep under 500 lines
MCP calls fail	Wrong tool names	Verify exact MCP tool names, add connection checks
Stops working mid-chat	Compaction dropped it	Keep critical rules in first 5,000 tokens, re-invoke after compaction
Works in Claude.ai not Code	Platform difference	Check compatibility, verify tool availability
Too many skills conflict	Description budget exceeded	Set SLASH_COMMAND_TOOL_CHAR_BUDGET env var to raise the 8,000-char default
Feels amateur/shallow	Missing pro patterns	Run Pro Quality Gate (Phase 8) — add hard gates, anti-patterns, push patterns
Asks too many questions at once	No interaction discipline	Enforce ONE question per message, multiple choice preferred
User skips important steps	No hard gate	Add <HARD-GATE> blocking progression until prerequisite met
Same questions for all contexts	No stage routing	Add mode detection + context-based step skipping
Weak answers accepted	No confrontation	Add push patterns with specific rebuttals per question

For each fix, provide before/after examples and new test cases. Run Pro Quality Gate scoring after improvements.

---

Workflow E: Convert a Repetitive Workflow into a Skill

When the user says "I keep doing X manually" or "every time I need to...":

1. Ask them to walk through it — step by step, or paste their usual prompts
2. Identify the pattern — what's constant vs. what changes?
3. Extract variables — what changes becomes $ARGUMENTS
4. Determine automation level — scriptable (deterministic) vs. needs Claude's judgment?
5. Build the skill — proceed to Workflow A Phase 2

---

Workflow F: Discover, Download & Install Existing Skills

When the user wants to find an existing skill rather than building from scratch. Requires gh CLI (check with python ${CLAUDE_SKILL_DIR}/scripts/skill-store.py check-env).

See references/discovery-guide.md for full details and search strategies.

Phase 1: Understand Need

Ask the user:

1. What capability do you need? (e.g., "code review", "deploy to AWS", "generate docs")
2. Do you have a specific repo/URL, or should we search?

If they have a URL → skip to Phase 3 (preview). If they describe a need → proceed to Phase 2 (search).

Phase 2: Search & Present

Run: python ${CLAUDE_SKILL_DIR}/scripts/skill-store.py search "<user's description>"

Present results as a table showing name, stars, trust level, repo. Ask which skill interests them. If no results found, offer to build from scratch via Workflow A.

Phase 3: Preview & Security Audit

Run: python ${CLAUDE_SKILL_DIR}/scripts/skill-store.py preview <repo> --path <skill-path>

This fetches the SKILL.md to a quarantine directory and runs both validate-skill.py and security-scan.py. Present to user:

• Skill name, description, trust level, stars
• Validation results (pass/fail)
• Security scan results (CRITICAL = blocked, HIGH = warning, clean = safe)

Ask: "Do you want to download the full skill?"

Phase 4: Download to Quarantine

Run: python ${CLAUDE_SKILL_DIR}/scripts/skill-store.py download <repo> --path <skill-path>

This downloads ALL files (SKILL.md, scripts/, references/, assets/) to /tmp/skill-quarantine-<uuid>/. Full security scan runs on everything. Present results.

If CRITICAL findings → recommend NOT installing, suggest alternatives. If clean → proceed to Phase 5.

Phase 5: Customize

Ask: "Would you like to customize this skill before installing?"

If yes, offer changes:

• Rename: python ${CLAUDE_SKILL_DIR}/scripts/skill-store.py customize <path> --name <new-name>
• Tighten tools: --remove-tool "Bash(*)" or --allowed-tools "Read Grep Glob"
• Update description: --description "My customized version for..."
• Edit instructions: Read and Edit the quarantined SKILL.md directly for deeper changes

Re-validate after every change.

Phase 6: Install

Ask: "Install to personal (all projects) or project (this repo only)?"

Run: python ${CLAUDE_SKILL_DIR}/scripts/skill-store.py install <quarantine-path> --scope <personal|project>

This runs final validation + security scan, copies to target, and cleans quarantine. Provide:

• Install location
• How to test (invoke with /skill-name)
• How to remove (skill-store.py uninstall <name>)

---

End-to-End Example

Here's a complete interaction showing how this skill builds another skill:

User: "Build me a skill for generating API documentation"

Phase 1 — Discovery:
  Claude asks: "What should the skill produce — OpenAPI specs, markdown docs, 
  or HTML reference pages? And what would you say to trigger it?"
  User: "Markdown docs from my code. I'd say 'document this API' or 'generate API docs'"
  Claude asks: "Does your API use a specific framework? And is this just for you or your team?"
  User: "FastAPI, just for me"

Phase 2 — Type & Pattern:
  Claude: "This is a Document Creation skill using the Scripts + Resources pattern.
  I'll have it analyze your FastAPI routes and generate markdown. Sound good?"
  User: "Yes"

Phase 3 — Frontmatter:
  ---
  name: api-docs
  description: Generate markdown API documentation from FastAPI code. Use when 
  user says "document this API", "generate API docs", or "create endpoint docs".
  allowed-tools: "Read Grep Write"
  argument-hint: "[path-to-api-routes]"
  ---
  User: "Looks good"

Phase 6 — Generated files:
  api-docs/
  ├── SKILL.md           (instructions for analyzing routes + generating docs)
  ├── scripts/
  │   └── extract-routes.py  (parses FastAPI decorators, extracts schemas)
  └── references/
      └── doc-template.md    (markdown template for the output)

Phase 7 — Test plan:
  Should trigger: "document this API", "generate API docs", "create endpoint reference"
  Should NOT trigger: "build an API", "fix this endpoint", "write a test"

Troubleshooting

"Could not find SKILL.md" — File not named exactly SKILL.md (case-sensitive).

"Invalid frontmatter" — Missing --- delimiters, unclosed quotes, or XML brackets.

"Skill loads but does nothing" — If using context: fork, the skill needs task instructions, not just guidelines.

"Description too long in listings" — Front-load key use case in first 250 characters.

"Skill disappears mid-conversation" — Compaction kept only first 5,000 tokens. Put critical rules at top. Re-invoke with /skill-name to restore.

"Too many skills, descriptions cut short" — Raise the budget: export SLASH_COMMAND_TOOL_CHAR_BUDGET=16000

Stuck on unfamiliar domain — Use WebSearch to research, check anthropics/skills repo for examples, start simple and iterate.

"GitHub CLI (gh) not installed" — Required for Workflow F. Install: https://cli.github.com then run gh auth login.

"GitHub API rate limit hit" — Wait 1 min for search (30/min) or use authenticated gh for 5000 req/hr.

"CRITICAL security issues in downloaded skill" — Installation blocked. Choose a different skill or fix issues manually in quarantine before installing.

"No skills found for query" — Try broader keywords, or search official repo: skill-store.py search "repo:anthropics/skills".