skill-architect

# Skill Architect: The Authoritative Meta-Skill The unified authority for creating expert-level Agent Skills. Combines systematic workflow from skill-creator with domain expertise encoding from skill-coach. ## Philosophy **Great skills are progressive disclosure machines** that encode real domain expertise (shibboleths), not just surface instructions. They activate precisely, teach efficiently, and make users productive immediately. --- ## When to Use This Skill ✅ **Use for**: - Creating new skills from scratch - Auditing/reviewing existing skills - Improving activation rates - Adding domain expertise - Debugging why skills don't activate - Encoding anti-patterns and shibboleths - Building self-contained tools (scripts, MCPs, subagents) ❌ **NOT for**: - General Claude Code features (slash commands, MCPs) - Non-skill coding advice - Debugging runtime errors (use domain-specific skills) - Template generation without domain expertise --- ## Quick Wins (Immediate Improvements) For existing skills, apply these in order: 1. **Add NOT clause** → Prevent false activation 2. **Check line count** → SKILL.md should be &lt;500 lines 3. **Add 1-2 anti-patterns** → Prevent common mistakes 4. **Remove dead files** → Delete unreferenced scripts/references 5. **Test activation** → Write queries that should/shouldn't trigger Run validation: ```bash python scripts/validate_skill.py <path> python scripts/check_self_contained.py <path> ``` --- ## What Makes a Great Skill Great skills have these 7 qualities: 1. **Activate precisely** - Specific keywords + NOT clause 2. **Encode shibboleths** - Expert knowledge that separates novice from expert 3. **Surface anti-patterns** - "If you see X, that's wrong because Y, use Z" 4. **Capture temporal knowledge** - "Pre-2024: X. 2024+: Y" 5. **Know their limits** - "Use for A, B, C. NOT for D, E, F" 6. **Provide decision trees** - Not templates, but "If X then A, if Y then B" 7. **Stay under 500 lines** - Core in SKILL.md, deep dives in `/references` --- ## Progressive Disclosure Principle Skills use a three-level loading system: | Level | Content | Size | When Loaded | |-------|---------|------|-------------| | 1. Metadata | `name` + `description` | ~100 tokens | Always in context | | 2. SKILL.md | Core instructions | &lt;5k tokens | When skill triggers | | 3. Resources | Scripts, references, assets | Unlimited | As Claude needs them | **Critical**: Keep SKILL.md under 500 lines. Move details to `/references`. --- ## Skill Structure ### Mandatory ``` your-skill/ └── SKILL.md # Core instructions (max 500 lines) ``` ### Strongly Recommended (Self-Contained Skills) ``` ├── scripts/ # Working code - NOT templates ├── mcp-server/ # Custom MCP if external APIs needed ├── agents/ # Subagent definitions for orchestration ├── references/ # Deep dives on domain knowledge └── CHANGELOG.md # Version history ``` **Philosophy**: Skills with working tools are immediately useful. --- ## SKILL.md Template ```markdown --- name: your-skill-name description: [What] [When] [Triggers]. NOT for [Exclusions]. allowed-tools: Read,Write # Minimal only --- # Skill Name [One sentence purpose] ## When to Use ✅ Use for: [A, B, C with specific keywords] ❌ NOT for: [D, E, F - be explicit] ## Core Instructions [Step-by-step decision trees, not templates] ## Common Anti-Patterns ### [Pattern Name] **Novice thinking**: [Wrong assumption] **Reality**: [Why it's wrong] **Correct approach**: [Better way] **Timeline**: [When this changed] ## References - `/references/deep-dive.md` - [When to consult] ``` --- ## Description Formula **[What] [When] [Keywords] NOT for [Exclusions]** **Examples**: ❌ **Bad**: "Helps with images" ⚠️ **Better**: "Image processing with CLIP" ✅ **Good**: "CLIP semantic search. Use for image-text matching, zero-shot classification. Activate on 'CLIP', 'embeddings', 'similarity'. NOT for counting objects, spatial reasoning, or fine-grained classification." --- ## Frontmatter Rules (CRITICAL) **Only these keys are allowed by Claude's skill marketplace:** | Key | Required | Purpose | |-----|----------|---------| | `name` | ✅ | Lowercase-hyphenated identifier | | `description` | ✅ | Activation keywords + NOT clause | | `allowed-tools` | ⚠️ | Comma-separated tool names | | `license` | ❌ | e.g., "MIT" | | `metadata` | ❌ | Custom key-value pairs | **Invalid keys that WILL FAIL upload**: ```yaml # ❌ WRONG - These break skill upload integrates_with: [...] triggers: [...] tools: Read,Write # Use 'allowed-tools' instead outputs: [...] coordinates_with: [...] python_dependencies: [...] ``` **Move custom info to body** under appropriate headings. --- ## The 6-Step Skill Creation Process ### Step 1: Understand with Concrete Examples Skip only if usage patterns are already clear. **Ask**: - "What functionality should this skill support?" - "Can you give examples of how it would be used?" - "What would trigger this skill?" **Example queries** (for an image-editor skill): - "Remove red-eye from this image" - "Rotate this photo 90 degrees" - "Adjust brightness and contrast" Conclude when you have 3-5 concrete examples. --- ### Step 2: Plan Reusable Contents For each example, analyze: 1. How to execute from scratch 2. What scripts/references/assets would help with repeated execution **Example analyses**: | Skill | Example | Needs | |-------|---------|-------| | pdf-editor | "Rotate this PDF" | `scripts/rotate_pdf.py` | | frontend-builder | "Build a todo app" | `assets/hello-world/` template | | big-query | "How many users logged in?" | `references/schema.md` | | photo-expert | "Improve composition" | `scripts/analyze_composition.py` | **Shibboleths to encode**: - Domain-specific algorithms - Common pitfalls and anti-patterns - Temporal knowledge (what changed when) - Framework evolution patterns --- ### Step 3: Initialize the Skill **For new skills**, run the init script: ```bash scripts/init_skill.py <skill-name> --path <output-directory> ``` This creates: - SKILL.md template with proper frontmatter - Example `scripts/`, `references/`, `assets/` directories - TODO placeholders to customize **For existing skills**, skip to Step 4. --- ### Step 4: Edit the Skill #### Write in Imperative/Infinitive Form Use objective, instructional language: - ✅ "To accomplish X, do Y" - ✅ "When Z occurs, execute A" - ❌ "You should do X" - ❌ "If you need to do Z" #### Start with Reusable Contents Implement in this order: 1. **Scripts** (`scripts/`) - Working code for repeatable operations 2. **References** (`references/`) - Domain knowledge, schemas, detailed guides 3. **Assets** (`assets/`) - Templates, boilerplate, files used in output **Delete example files** that aren't needed. #### Update SKILL.md Answer these questions: 1. **Purpose**: What is this skill for? (1-2 sentences) 2. **When to use**: Specific triggers and exclusions 3. **How to use**: Reference all bundled resources so Claude knows they exist 4. **Anti-patterns**: What mistakes do novices make? 5. **Temporal context**: What changed and when? --- ### Step 5: Validate and Package ```bash # Validate structure and content python scripts/validate_skill.py <path> # Check self-contained tool completeness python scripts/check_self_contained.py <path> # Package for distribution (validates first) python scripts/package_skill.py <path/to/skill-folder> ``` Fix all ERRORS, then WARNINGS, then SUGGESTIONS. --- ### Step 6: Iterate After real-world use: 1. Notice struggles or inefficiencies 2. Identify how SKILL.md or bundled resources should improve 3. Implement changes and test again 4. Update CHANGELOG.md **Recursive self-improvement**: Use this skill to improve skills. --- ## Encoding Shibboleths (Expert Knowledge) ### What Are Shibboleths? Knowledge that separates novices from experts - things LLMs get wrong because training data includes: - Outdated patterns - Oversimplified tutorials - Cargo-culted code ### Shibboleth Template ```markdown ### Anti-Pattern: [Name] **Novice thinking**: "[Wrong assumption]" **Reality**: [Fundamental reason it's wrong, with research/data] **Timeline**: - [Date range]: [Old approach] was common - [Date]: [Change event] - [Current]: [New approach] **What to use instead**: | Task | Tool | Why | |------|------|-----| | [Use case] | [Correct tool] | [Reason] | **LLM mistake**: [Why LLMs suggest old pattern] **How to detect**: [Validation rule] ``` ### Example Shibboleths to Encode 1. **Framework Evolution** - React: Class components → Hooks → Server Components - Next.js: Pages Router → App Router - State management: Redux → Zustand/Jotai/React Query 2. **Model Selection** - CLIP limitations (can't count, can't do spatial reasoning) - Embedding model specialization (text vs code vs multi-lingual) - Model versioning (ada-002 vs text-embedding-3-large) 3. **Tool Architecture** - When to use MCP vs Scripts vs Subagents - Premature abstraction anti-pattern - Self-contained tool benefits --- ## Self-Contained Tools ### Decision Matrix | Need | Use | |------|-----| | External API + auth | MCP Server | | Multi-step workflow | Subagents | | Repeatable operation | Scripts | | Domain validation | Scripts | | Templates/boilerplate | Assets | | Deep reference docs | References | ### Scripts **Requirements**: 1. Actually work (not templates or pseudocode) 2. Minimal dependencies (prefer stdlib) 3. Clear interface (CLI args or stdin/stdout) 4. Error handling (graceful failures) 5. README (how to install and run) **Example**: ```python #!/usr/bin/env python3 """ Domain Analyzer Usage: python analyze.py <input> Dependencies: pip install numpy """ import sys def analyze(input_path): # Import here for helpful error try: import numpy as np except ImportError: print("Install: pip install numpy") sys.exit(1) # Actual implementation result = {"score": 0.85} return result if __name__ == "__main__": if len(sys.argv) != 2: print(f"Usage: {sys.argv[0]} <input>") sys.exit(1) result = analyze(sys.argv[1]) for k, v in result.items(): print(f"{k}: {v}") ``` ### MCP Servers **When to build**: - External API with authentication - Stateful connections (WebSocket, database) - Real-time data streams - Security boundaries (credentials, OAuth) **Structure**: ``` mcp-server/ ├── src/index.ts # Server implementation ├── package.json # Dependencies ├── tsconfig.json # Config └── README.md # Setup instructions ``` **Minimal MCP template**: See `/references/mcp-template.md` ### Subagents **When to define**: - Multi-step workflows - Different phases need different tool access - Orchestration logic is complex **Definition format**: See `/references/subagent-template.md` --- ## Common Workflows ### Create Skill from Expertise 1. Define scope: What expertise? Keywords? Exclusions? 2. Write description with keywords and NOT clause 3. Encode anti-patterns and shibboleths 4. Add decision trees (not just instructions) 5. Build working tools (scripts/MCP/subagents) 6. Test activation thoroughly ### Debug Activation Issues **Flowchart**: ``` Skill not activating? ├── Check description has specific keywords │ ├── NO → Add "Activate on: keyword1, keyword2" │ └── YES → Query contains those keywords? │ ├── NO → Add missing variations │ └── YES → Conflicting NOT clause? │ ├── YES → Narrow exclusions │ └── NO → Check file structure │ └── Wrong location → Move to .claude/skills/ Skill activating when it shouldn't? ├── Missing NOT clause? │ ├── YES → Add "NOT for: exclusion1, exclusion2" │ └── NO → NOT clause too narrow │ └── Expand based on false positives ``` Run: `python scripts/test_activation.py <path>` ### Improve Existing Skill