Activation Triggers

WHEN

User specifically asks to create, audit, or modify a Skill (SKILL.md).

WHEN NOT

User asks to create an Agent or Command. User asks for general coding help.

Directory Structure

This skill uses the following directory structure:

• workflows/ - Step-by-step procedures (FOLLOW)
• references/ - Domain knowledge (READ)
• templates/ - Output structures (COPY + FILL)
• scripts/ - Reusable code (EXECUTE)

Essential Principles

Overview

Skills are modular, filesystem-based capabilities that provide domain expertise on demand. This skill teaches how to create effective skills.

Skills Are Prompts

All prompting best practices apply. Be clear, be direct, use XML structure. Assume Claude is smart - only add context Claude doesn't have.

SKILL.md Always Loaded

When a skill is invoked, Claude reads SKILL.md. Use this guarantee:

• Essential principles go in SKILL.md (can't be skipped)
• Workflow-specific content goes in workflows/
• Reusable knowledge goes in references/

Router Pattern

For complex skills, use this structure:

skill-name/
├── SKILL.md              # Router + principles
├── workflows/            # Step-by-step procedures (FOLLOW)
├── references/           # Domain knowledge (READ)
├── templates/            # Output structures (COPY + FILL)
└── scripts/              # Reusable code (EXECUTE)

SKILL.md asks "what do you want to do?" → routes to workflow → workflow specifies which references to read.

Folder usage:

• workflows/ - Multi-step procedures Claude follows
• references/ - Domain knowledge Claude reads for context
• templates/ - Consistent output structures Claude copies and fills (plans, specs, configs)
• scripts/ - Executable code Claude runs as-is (deploy, setup, API calls)

Structure Clarity

Use markdown headings for structure (#, ##, ###). Reserve XML only for highly structured elements like routing decisions:

# Objective

What this skill does

# Process

Step-by-step procedure

# Success Criteria

How to know it worked

Keep markdown formatting within content (bold, lists, code blocks). XML reserved for complex routing logic in router pattern skills.

Progressive Disclosure

SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed for the current workflow.

Direct Routing

Skills are passive cookbooks, not interactive wizards. Route based on input semantics, not user menu selections.

This skill routes directly to workflows based on the intent detected in the initial task or calling context. No interactive questions are asked.

<foundational_knowledge>

Critical: Read-First Protocol

BEFORE executing ANY workflow in this skill, you MUST read these files:

1. references/architecture-standards.md - Architecture standards, design principles, and validation checklist
2. references/system-standards.md - System standards with component-specific audit checklists

WHY: These files contain the axioms, validation rules, and quality standards that govern ALL skill operations. Skipping them leads to:

• Inconsistent skill structure
• Missing quality checks
• Broken validation logic
• Non-compliant architecture decisions

EXECUTION RULE: Read foundational knowledge IMMEDIATELY upon skill invocation, before routing or workflow execution. This is non-negotiable. </foundational_knowledge>

<routing> ## Intent-Based Routing

Analyze the task description or calling context to determine the appropriate workflow:

Intent Detected	Route To Workflow
"create skill", "build new skill", "new skill", "create a skill"	workflows/create.md
"create domain expertise", "exhaustive knowledge base", "domain expertise skill"	workflows/create-domain-expertise-skill.md
"audit", "check skill", "review", "verify quality"	workflows/audit.md
"verify content", "check if current", "validate"	workflows/verify-skill.md
"edit skill", "modify skill", "update skill", "enhance skill"	workflows/edit.md
"add workflow", "add reference", "add template", "add script"	workflows/add-{type}.md
"upgrade to router", "convert to router pattern"	workflows/upgrade-to-router.md
"help", "guidance", "what should I do?"	workflows/get-guidance.md

Execution Rule: Route immediately to the matching workflow without asking clarifying questions. If the intent is ambiguous, default to workflows/get-guidance.md for general guidance.

After routing, follow the workflow exactly. </routing>

Quick Reference

Simple skill (single file):

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

# Objective

What this skill does

# Quick Start

Immediate actionable guidance

# Process

Step-by-step procedure

# Success Criteria

How to know it worked

Example: Simple skill like "process-pdfs" has single SKILL.md with objective, quick start (extract with pdfplumber), and success criteria.

Complex skill (router pattern):

SKILL.md:
  Essential Principles - Always applies
  Intake - Question to ask
  Routing - Maps answers to workflows

workflows/:
  Required Reading - Which refs to load
  Process - Steps
  Success Criteria - Done when...

references/:
  Domain knowledge, patterns, examples

templates/:
  Output structures Claude copies and fills
  (plans, specs, configs, documents)

scripts/:
  Executable code Claude runs as-is
  (deploy, setup, API calls, data processing)

Example: Router skill like "create-plans" uses intent-based routing to delegate to create-brief, create-roadmap, or plan-phase workflows.

Pattern Selection

For comprehensive XML/Markdown decision guidelines, see:

• XML/Markdown Decision Framework

Quick Reference:

• Pure Markdown (0 tags): Default for simple, linear workflows
• Hybrid XML/Markdown (1-5 tags): When AI needs to organize multiple pathways, track state, or enforce critical constraints

For detailed patterns, examples, and guidelines, see:

• XML/Markdown Decision Framework

Reference Index

• references/architecture-standards.md - MASTER LIBRARY: Consolidated architecture standards, design principles, structure requirements, and validation checklist
• references/system-standards.md - System standards with component-specific audit checklists (Skills, Agents, Hooks, Commands)
• references/xml-markdown-decision-framework.md - Complete guide to XML/Markdown patterns (Pure Markdown, Hybrid XML/Markdown, Full XML deprecation)
• references/permissions-guide.md - Comprehensive permissions documentation for Agent Skills (allowed-tools field, pre-approval)
• references/recommended-structure.md - Recommended directory structure for different skill types
• references/router-pattern-examples.md - XML router pattern examples and best practices
• references/be-clear-and-direct.md - Writing clear instructions
• references/common-patterns.md - Common skill patterns
• references/workflows-and-validation.md - Workflow design
• references/using-templates.md - Template usage guide
• references/using-scripts.md - Script integration
• references/executable-code.md - Code execution patterns
• references/api-security.md - API security considerations
• references/iteration-and-testing.md - Testing skills
• references/cross-platform.md - Cross-platform compatibility (Claude Code, Roo Code, OpenCode)
• references/progressive-disclosure.md - Progressive disclosure design pattern

Examples Index

• examples/progressive-disclosure-skill.md - Skill with references for advanced topics (pdf-processing)
  • examples/references/OCR.md - OCR for scanned PDFs
  • examples/references/TABLES.md - Table extraction patterns
  • examples/references/FORMS.md - PDF form handling
• examples/domain-expertise-skill.md - Comprehensive knowledge base (react-patterns)
• examples/simple-skill-example.md - Simple task-execution skill (commit-messages)
• examples/xml-router-skill-example.md - XML router pattern with intent-based routing (project-analysis)

Templates Index

Skill templates in assets/templates/:

• assets/templates/minimal.md - Minimal SKILL.md template
• assets/templates/task-execution.md - Task-execution skill template
• assets/templates/progressive-disclosure.md - Progressive disclosure with references
• assets/templates/domain-expertise.md - Domain expertise knowledge base
• assets/templates/router-pattern.md - Router pattern with intent-based routing
• assets/templates/reference-file.md - Reference document template for references/ subdirectory

WHY: Templates ensure consistent structure, YAML frontmatter standards, and progressive disclosure best practices.

Workflows Index

• workflows/create.md - Build a skill from scratch
• workflows/create-domain-expertise-skill.md - Build exhaustive domain knowledge base
• workflows/edit.md - Modify or enhance an existing skill
• workflows/audit.md - Analyze skill against best practices
• workflows/verify-skill.md - Check if content is still accurate
• workflows/add-workflow.md - Add a workflow to existing skill
• workflows/add-reference.md - Add a reference to existing skill
• workflows/add-template.md - Add a template to existing skill
• workflows/add-script.md - Add a script to existing skill
• workflows/upgrade-to-router.md - Convert simple skill to router pattern
• workflows/get-guidance.md - Help decide what kind of skill to build

YAML Requirements

Required fields:

---
name: skill-name          # lowercase-with-hyphens, matches directory
description: ...          # What it does AND when to use it (third person)
---

Name conventions: create-*, manage-*, setup-*, generate-*, build-*

Available Tools

Skills may reference tools in their workflows. Use this comprehensive list for reference.

Standard/Core Tools (Always Available)

• Bash - Execute shell commands
• Glob - Find files based on pattern matching
• Grep - Search for patterns in file contents
• Read - Read file contents
• Edit - Make targeted edits to specific files
• Write - Create or overwrite files
• TodoWrite - Create and manage structured task lists

Claude-Specific Tools (Optional - Use Only When Required)

⚠️ WARNING: Use these tools ONLY when explicitly required by the user's request. Do not add them to skills by default.

• NotebookEdit (Claude-specific) - Modify Jupyter notebook cells
• WebFetch (Claude-specific) - Fetch content from a URL
• WebSearch (Claude-specific) - Perform web searches (ensure enabled)
• Skill (Claude-specific) - Execute a skill within the main conversation
• LSP (Claude-specific) - Language Server Protocol operations

MCP Tools

MCP tools from configured MCP servers can also be specified. Format: mcp__server__tool

Black Box Usage Principle

Skills should be treated as black boxes by default.

What This Means

When Claude invokes a skill via the Skill tool:

• The skill executes with its own context
• The main conversation does NOT see intermediate steps
• Only the final result is returned

Implications

1. Use Skill tool when: You want to delegate a task and get a result back
2. Use slash command when: You want explicit, visible invocation
3. Use subagent when: You need isolated context with different tool access

Warning: Integration Risks

⚠️ CRITICAL: Think carefully before linking skills to slash commands or subagents.

Risks of Over-Integration:

Integration Type	Risk	When Acceptable
Skill → Slash Command	Duplication, maintenance burden	Skill is complex, frequently used, needs explicit trigger
Skill → Subagent	Circular dependencies, context confusion	Subagent needs specialized tools different from main conversation
Skill → Skill	Circular dependency hell	Almost never - use reference files instead

Why Overengineering is Dangerous:

1. Circular Dependencies: Skill A calls Skill B, which calls Skill A
2. Context Confusion: Hard to debug which component did what
3. Maintenance Burden: Changes ripple through multiple components
4. Token Waste: Duplicate metadata loaded multiple times
5. Unpredictable Behavior: Complex call chains are hard to reason about

When Integration IS Appropriate:

• Slash Command: For frequently-used skills where explicit invocation is clearer than automatic discovery
• Subagent: Only when the subagent needs a DIFFERENT tool set than the main conversation (e.g., no web access, limited permissions)

Default Rule: Keep skills independent. Use references/ for shared knowledge, not cross-skill calls.

Meta Instructions

These are instructions for how the workflows in this skill should operate:

Context Rule

All workflows MUST start with an "Intake & Context" step that gathers:

1. What already exists:

   • Read existing agent/skill/command files before creating or modifying
   • Understand current state before making changes

2. What dependencies are involved:

   • Check imports, tools, permissions
   • Understand what other components might be affected

3. What patterns are in use:

   • Find similar agents/skills/commands in the codebase
   • Follow established conventions and patterns

4. Why this change is being made:

   • Understand user intent and use case
   • Clarify the goal before proceeding

Rationale: Without context intake, workflows make assumptions that lead to:

• Duplicating existing functionality
• Breaking established patterns
• Missing critical dependencies
• Creating inconsistent interfaces

Quality Standards & Evaluation Criteria

These are the criteria used to audit skills. Follow them to ensure your skill passes quality checks:

YAML Frontmatter Requirements

Required fields:

• name: Lowercase-with-hyphens, max 64 chars, matches directory name
• description: Max 1024 chars, third person, includes BOTH what it does AND when to use it

Strong language requirements:

• MUST USE: Creation/critical skills (manage-*, debug-like-expert)
• PROACTIVELY USE: Proactive usage (project-analysis, testing-strategy)
• CONSULT: Reference/expert guidance (api-design, architecture-patterns)

Structure Quality

Progressive disclosure:

• SKILL.md < 500 lines recommended
• Detailed content in references/ subdirectory
• One level deep references only (not nested)

Required sections:

• Objective or overview
• Quick start or equivalent
• Success criteria

Heading hierarchy:

• Proper markdown structure (# ## ###)
• Clear navigation with descriptive headings

Description quality:

• Third person: "Use this skill when..." not "I will help you..."
• Specific triggers: Concrete phrases that invoke the skill
• No vague terms: Avoid "helps with", "processes data"

Common Anti-Patterns

Pattern	Why It Matters	Fix
Missing objective	Unclear purpose	Add objective section
Wrong POV	Inconsistent	Use third person
Vague triggers	Won't invoke	Add specific trigger keywords
Bloat (>500 lines)	Hard to scan	Move details to references/
No success criteria	Can't verify completion	Add clear success criteria
Deep references	Hard to maintain	Flatten to one level
Generic role	No specialization	Specify domain and expertise
Missing constraints	Can go out of scope	Add MUST/NEVER boundaries

Contextual Judgment

Simple skills (<100 lines):

• Minimal requirements OK
• Don't flag missing optional sections

Complex skills:

• Missing conditional sections is critical
• Comprehensive coverage expected

Delegation skills:

• Success criteria can focus on invocation success

Success Criteria

A well-structured skill:

• Has valid YAML frontmatter
• Uses markdown headings for structure
• Has essential principles inline in SKILL.md
• Routes directly to appropriate workflows based on user intent
• Keeps SKILL.md under 500 lines
• Asks minimal clarifying questions only when truly needed
• Has been tested with real usage
• Workflows include context intake steps before creating or modifying content