Skill Architect: The Authoritative Meta-Skill

The unified authority for creating expert-level Agent Skills. Encodes the knowledge that separates a skill that merely exists from one that activates precisely, teaches efficiently, and makes users productive immediately.

Philosophy

Great skills are progressive disclosure machines. They encode real domain expertise (shibboleths), not surface instructions. They follow a three-layer architecture: lightweight metadata for discovery, lean SKILL.md for core process, and reference files for deep dives loaded only on demand.

When to Use This Skill

✅ Use for:

• Creating new skills from scratch or from existing expertise
• Auditing/reviewing skills for quality, activation, and progressive disclosure
• Improving activation rates and reducing false positives
• Encoding domain expertise (shibboleths, anti-patterns, temporal knowledge)
• Designing skills that subagents consume effectively
• Building self-contained tools (scripts, MCPs, subagents)
• Debugging why skills don't activate or activate incorrectly

❌ NOT for:

• General Claude Code features (slash commands, MCP server implementation)
• Non-skill coding advice or code review
• Debugging runtime errors (use domain-specific skills)
• Template generation without real domain expertise to encode

Quick Wins (Immediate Improvements)

For existing skills, apply in priority order:

1. Tighten description → Follow

   [What] [When to use]. NOT for [Exclusions]

   formula
2. Check line count → SKILL.md must be <500 lines; move depth to

   /references

3. Add NOT clause → Prevent false activation with explicit exclusions
4. Add 1-2 anti-patterns → Use shibboleth template (Novice/Expert/Timeline)
5. Remove dead files → Delete unreferenced files in

   scripts/

   and

   references/

   (no phantoms)
6. Test activation → Write 5 queries that should trigger and 5 that shouldn't

Progressive Disclosure Architecture

Skills use three-layer loading. The runtime scans metadata at startup, loads SKILL.md on activation, and pulls reference files only when the agent decides it needs them.

name

description

Critical rules:

• Keep SKILL.md under 500 lines. Move depth to

  /references

  .
• Reference files are NOT auto-loaded. Only SKILL.md enters context on activation.
• In SKILL.md, list each reference file with a 1-line description of when to consult it. This teaches the agent what's available without loading it.
• Never instruct "read all reference files before starting." Instead: "Read only the files relevant to the current step."
• If a reference file is large, the agent should skim headings first, then drill into the relevant section.

Frontmatter Rules

Required Fields

name

description

[What] [When to use]. NOT for [Exclusions]

Optional Fields

allowed-tools

Read,Write,Grep

argument-hint

"[path] [format]"

license

MIT

disable-model-invocation

true

/skill-name

true

user-invocable

true

context

fork

fork

agent

context: fork

code-reviewer

model

sonnet

hooks

metadata

author: your-org

dependencies

python>=3.8, pandas>=1.5.0

bundled-resources

distribution

npm

pip

zip

Note: The Skills API uses hyphenated variants (

context-fork

model-override

Custom Keys (Safe to Use)

Custom keys like

category

tags

version

Invalid Keys (Confusingly Similar to Valid Ones)

# ❌ These look like valid keys but aren't — use the correct alternatives
tools: Read,Write           # Use 'allowed-tools' instead
integrates_with: [...]      # Use SKILL.md body text instead
outputs: [...]              # Use SKILL.md Output Format section instead
python_dependencies: [...]  # Use 'dependencies' in frontmatter instead

Platform Constraints

Cross-surface behavior: Skills do NOT sync across Claude.ai, Claude API, and Claude Code. Each surface requires separate upload/management. Maintain source files in Git as single source of truth.

Recall limits: Too many active skills degrades Claude's selection accuracy. Test coexistence when adding new skills — verify the new skill doesn't steal triggers from existing ones.

Description Formula

Pattern:

[What it does] [When to use — be slightly pushy]. NOT for [Exclusions].

The description is the most important line for activation. Claude's runtime scans descriptions to decide which skill to load. A weak description means zero activations or constant false positives.

How activation works: Claude evaluates descriptions semantically, not via keyword matching. It reasons about whether your description covers the user's intent. This means specific, context-rich descriptions outperform keyword lists. Claude also tends to undertrigger — it errs toward NOT activating skills. Combat this by making descriptions slightly pushy: explain when the skill should be used, even if it seems obvious.

db-migration

db-migration

Full guide with more examples: See

references/description-guide.md

SKILL.md Template

---
name: your-skill-name
description: [What it does] [When to use — be slightly pushy]. NOT for [Exclusions].
allowed-tools: Read,Write
---

# Skill Name
[One sentence purpose]

## When to Use
✅ Use for: [A, B, C with specific trigger keywords]
❌ NOT for: [D, E, F — explicit boundaries]

## Core Process
[Mermaid diagrams — 23 types available. See visual-artifacts.md for full catalog]

## Anti-Patterns
### [Pattern Name]
**Novice**: [Wrong assumption]
**Expert**: [Why it's wrong + correct approach]
**Timeline**: [When this changed, if temporal]

## References
- `references/guide.md` — Consult when [specific situation]
- `references/examples.md` — Consult for [worked examples of X]

The 6-Step Skill Creation Process

flowchart LR
  S1[1. Gather Examples] --> S2[2. Plan Contents]
  S2 --> S3[3. Initialize]
  S3 --> S4[4. Write Skill]
  S4 --> S5[5. Validate]
  S5 --> S6{Errors?}
  S6 -->|Yes| S4
  S6 -->|No| S7[6. Ship & Iterate]

Step 1: Gather Concrete Examples

Collect 3-5 real queries that should trigger this skill, and 3-5 that should NOT.

Step 2: Plan Reusable Contents

For each example, identify what scripts, references, or assets would prevent re-work. Also identify shibboleths: domain algorithms, temporal knowledge, framework evolution, common pitfalls.

Step 3: Initialize

scripts/init_skill.py <skill-name> --path <output-directory>

For existing skills, skip to Step 4.

Step 4: Write the Skill

Order of implementation:

1. Scripts first (

   scripts/

   ) — Working code, not templates
2. References next (

   references/

   ) — Domain knowledge, schemas, guides
3. SKILL.md last — Core process, anti-patterns, reference index

Write in imperative form: "To accomplish X, do Y" not "You should do X."

Answer these questions in SKILL.md:

1. Purpose: What is this skill for? (1-2 sentences)
2. Activation: What triggers it? What shouldn't?
3. Process: Use Mermaid diagrams (23 types) — flowcharts for decisions, sequence for protocols, state for lifecycles, etc.
4. Anti-patterns: What do novices get wrong?
5. Visual artifacts: Render workflows, architectures, timelines as Mermaid diagrams (see

   references/visual-artifacts.md

   )
6. References: What files exist and when to consult them?

Step 5: Validate

python scripts/validate_skill.py <path>
python scripts/check_self_contained.py <path>

Fix ERRORS → WARNINGS → SUGGESTIONS.

Step 6: Iterate

After real-world use: notice struggles, improve SKILL.md and resources, update CHANGELOG.md.

Designing Skills for Subagent Consumption

When skills will be loaded by subagents (not just direct user invocation), apply these patterns:

Three Skill-Loading Layers

1. Preloaded (2-5 core skills): Injected into the subagent's system context. These are its standard operating procedures — always present.
2. Dynamically selected: Subagent receives a catalog (name + 1-line description) and picks 1-3 matching skills before starting. The orchestrator can also pre-filter.
3. Execution-time: Subagent reads each skill's "When to use" section, follows numbered steps in order, respects output contracts, and runs QA checks.

How Subagents Should Use Skills

Teach the subagent to treat each skill like a mini-protocol:

• Check the "When to use / When not to use" section for applicability
• Follow numbered steps in order (adapt only if task constraints force it)
• Respect the skill's output contract (templates, JSON shapes, required sections)
• Apply QA/validation steps last
• Reference skill steps by number: "Completed step 3 of refactor-plan-skill"

Subagent Prompt Structure

The subagent's prompt should have four sections:

1. Identity: "You are the [role]. You handle [narrow domain]. If outside scope, say so."
2. Skill usage rules: "Your skills define your methods. Decide which apply, follow their workflows."
3. Task loop: Restate → Select skills → Clarify → Plan → Execute step-by-step → Validate → Return (artifacts + skills used + remaining risks).
4. Constraints: Quality bar, safety rules, tie-breaking priorities.

Full templates and orchestration patterns: See

references/subagent-design.md

Visual Artifacts: Mermaid Diagrams & Code

Skills that include Mermaid diagrams serve two audiences at once. For humans, diagrams render as visual flowcharts, state machines, and timelines — instantly parseable. For agents, Mermaid is a text-based graph DSL —

A -->|Yes| B

Rule: If a skill describes a process, decision tree, architecture, state machine, timeline, or data relationship, include a Mermaid diagram. Use raw

```mermaid

Most Useful Diagram Types for Skills

flowchart TD

sequenceDiagram

stateDiagram-v2

timeline

erDiagram

mindmap

quadrantChart

architecture-beta

Full catalog (all 23 types) with syntax, examples, and YAML config: See

references/visual-artifacts.md

Encoding Shibboleths

Expert knowledge that separates novices from experts. Things LLMs get wrong due to outdated training data or cargo-culted patterns.

Shibboleth Template

### Anti-Pattern: [Name]
**Novice**: "[Wrong assumption]"
**Expert**: [Why it's wrong, with evidence]
**Timeline**: [Date]: [Old way] → [Date]: [New way]
**LLM mistake**: [Why LLMs suggest the old pattern]
**Detection**: [How to spot this in code/config]

What to Encode

• Framework evolution (React Classes → Hooks → Server Components)
• Model limitations (CLIP can't count; embedding models are task-specific)
• Tool architecture (Script → MCP graduation path)
• API versioning (ada-002 → text-embedding-3-large)
• Temporal traps (advice that was correct in 2023 but harmful in 2025)

Full catalog with case studies: See

references/antipatterns.md

Self-Contained Tools and the Extension Taxonomy

Skills are one of seven Claude extension types: Skills (domain knowledge), Plugins (packaged bundles for distribution), MCP Servers (external APIs + auth), Scripts (local operations), Slash Commands (user-triggered skills), Hooks (lifecycle automation at 17+ event points), and Agent SDK (programmatic Claude Code access). Most skills should include scripts. MCPs are only for auth/state boundaries. Plugins are for sharing skills across teams/community.

user-invocable: true

Evolution path: Skill → Skill + Scripts → Skill + MCP Server → Skill + Subagent → Plugin (for distribution). Only promote when complexity justifies it.

Full taxonomy with examples and common mistakes: See

references/claude-extension-taxonomy.md

references/self-contained-tools.md

references/plugin-architecture.md

Tool Permissions (Least Privilege)

allowed-tools

Read,Grep,Glob

Read,Write,Edit

Read,Write,Bash(npm:*,git:*)

Bash

Anti-Pattern Summary

/references

[What] [When to use]. NOT for [Exclusions]

Full case studies: See

references/antipatterns.md

Validation Checklist

□ SKILL.md exists and is <500 lines
□ Frontmatter has name + description (minimum required)
□ Description follows [What][When to use] NOT [Exclusions] formula
□ Description is specific and context-rich (semantic activation, not keyword lists)
□ Name and description are aligned (not contradictory)
□ At least 1 anti-pattern with shibboleth template
□ All referenced files actually exist (no phantoms)
□ Scripts work (not templates), have clear CLI, handle errors
□ Reference files each have a 1-line purpose in SKILL.md
□ Processes/decisions/lifecycles use Mermaid diagrams (23 types), not prose
□ CHANGELOG.md tracks version history
□ If subagent-consumed: output contracts are defined

Run automated checks:

python scripts/validate_skill.py <path>

python scripts/validate_mermaid.py <path>

Common Rejection Causes

name

description

tools:

allowed-tools:

allowed-tools:

allowed-tools

Read,Write,Edit

allowed-tools

[

]

Read,Write,Edit

triggers

outputs

my-skill-name

context:

fork

fork

disable-model-invocation:

true

false

Full validation:

python scripts/validate_skill.py <path>

Success Metrics

Reference Files

Consult these for deep dives — they are NOT loaded by default:

references/knowledge-engineering.md

references/description-guide.md

references/antipatterns.md

references/self-contained-tools.md

references/subagent-design.md

references/claude-extension-taxonomy.md

references/plugin-architecture.md

references/visual-artifacts.md

references/mcp-template.md

references/subagent-template.md

references/scoring-rubric.md

references/skill-composition.md

references/skill-lifecycle.md

references/activation-debugging.md

agents/cross-evaluator.md