skill-architect

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.

---

✅ 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

---

For existing skills, apply these in order:

1. Add NOT clause → Prevent false activation
2. Check line count → SKILL.md should be <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

python scripts/check_self_contained.py

```

---

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

---

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 | <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.

---

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.

---

```markdown

---

name: your-skill-name

description: [What] [When] [Triggers]. NOT for [Exclusions].

allowed-tools: Read,Write # Minimal only

---

# Skill Name

[One sentence purpose]

✅ Use for: [A, B, C with specific keywords]

❌ NOT for: [D, E, F - be explicit]

[Step-by-step decision trees, not templates]

[Pattern Name]

Novice thinking: [Wrong assumption]

Reality: [Why it's wrong]

Correct approach: [Better way]

Timeline: [When this changed]

• /references/deep-dive.md - [When to consult]

```

---

[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."

---

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.

---

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 --path

```

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

# Check self-contained tool completeness

python scripts/check_self_contained.py

# Package for distribution (validates first)

python scripts/package_skill.py

```

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.

---

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

1. 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)

1. Tool Architecture

- When to use MCP vs Scripts vs Subagents

- Premature abstraction anti-pattern

- Self-contained tool benefits

---

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

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]} ")

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

---

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

Improve Existing Skill

1. Run python scripts/validate_skill.py
2. Run python scripts/check_self_contained.py
3. Address ERRORS → WARNINGS → SUGGESTIONS
4. Add missing shibboleths and anti-patterns
5. Ensure <500 lines in SKILL.md
6. Re-validate until clean
7. Update CHANGELOG.md

---

Guidelines:

• Read-only: Read,Grep,Glob
• File modifier: Read,Write,Edit
• Build integration: Read,Write,Bash(npm:,git:)
• ⚠️ Never: Unrestricted Bash for untrusted skills

Principle: Least privilege - only grant what's needed.

---

When to Create a NEW Skill?

✅ Create when:

• Domain expertise not in existing skills
• Pattern repeats across 3+ projects
• Anti-patterns you want to prevent
• Shibboleths to encode

❌ Don't create when:

• One-time task → Just do it directly
• Existing skill could be extended → Improve that one
• No real expertise to encode → Not worth it

Skill vs Subagent vs MCP vs Script?

| Type | Purpose | State | Auth | Example |

|------|---------|-------|------|---------|

| Skill | Domain expertise, decision trees | None | None | react-server-components |

| Script | Repeatable operations | None | None | validate_skill.py |

| Subagent | Multi-step workflows | Session | Inherited | research-coordinator |

| MCP | External APIs, auth | Persistent | Required | github-mcp-server |

---

1. Skill as Documentation Dump

❌ Wrong: 50-page tutorial in SKILL.md

✅ Right: Decision trees + anti-patterns in SKILL.md, details in /references

2. Missing "When NOT to Use"

❌ Wrong: description: "Processes images using computer vision"

✅ Right: description: "CLIP semantic search. NOT for generation, editing, OCR, counting."

3. Phantom Tools

❌ Wrong: SKILL.md references scripts/analyze.py that doesn't exist

✅ Right: Only reference tools that exist and work

4. Template Soup

❌ Wrong: Scripts with # TODO: implement comments

✅ Right: Ship working code or don't ship at all

5. No Validation Script

❌ Wrong: Instructions with no way to check correctness

✅ Right: Include scripts/validate.py for pre-flight checks

6. Overly Permissive Tools

❌ Wrong: allowed-tools: Bash

✅ Right: allowed-tools: Bash(git:*,npm:run),Read,Write

7. Ignoring Temporal Knowledge

❌ Wrong: "Use useEffect for componentDidMount"

✅ Right: "Pre-React 18: useEffect=didMount. React 18+: runs TWICE in dev. Use refs for run-once."

---

| Metric | Target | How to Measure |

|--------|--------|----------------|

| Correct activation | >90% | Test queries that should trigger |

| False positive rate | <5% | Test queries that shouldn't trigger |

| Token usage | <5k | SKILL.md size + typical reference loads |

| Time to productive | <5 min | User can start working immediately |

| Anti-pattern prevention | >80% | Users avoid documented mistakes |

---

Before packaging a skill:

```

□ SKILL.md exists and is <500 lines

□ Frontmatter has name, description, allowed-tools

□ Description includes specific keywords

□ Description includes NOT clause for exclusions

□ At least 1 anti-pattern documented

□ All referenced scripts/tools actually exist

□ Scripts have clear installation instructions

□ Scripts handle errors gracefully

□ If MCP needed, server is complete and tested

□ If subagents needed, prompts are defined

□ CHANGELOG.md exists with version history

□ Validation scripts pass without errors

```

---

For deep dives on specific topics:

| File | Contents |

|------|----------|

| references/antipatterns.md | Shibboleths and case studies |

| references/self-contained-tools.md | Scripts, MCP, subagent patterns |

| references/validation-checklist.md | Complete review guide |

| references/scoring-rubric.md | Quantitative evaluation (0-10) |

| references/mcp-template.md | Minimal MCP server starter |

| references/subagent-template.md | Agent definition format |

---

Case Study 1: Photo Expert Explosion

Problem: Single skill for ALL photo operations (800+ lines)

Symptoms: Activated on "photo" anywhere, wrong advice given

Root cause: "Everything Skill" anti-pattern

Resolution: Split into 5 focused skills (CLIP, composition, color theory, collage, event detection)

Lesson: One domain ≠ one skill. Split by expertise type.

Case Study 2: The Phantom MCP

Problem: SKILL.md referenced non-existent MCP server

Symptoms: Users ran commands that didn't exist

Root cause: Reference Illusion anti-pattern

Resolution: Added check_self_contained.py to CI

Lesson: Don't promise tools you don't deliver.

Case Study 3: The Time Bomb

Problem: Temporal knowledge became stale (React hooks advice from 2023)

Symptoms: Skill became actively harmful in 2024

Root cause: Missing temporal markers

Resolution: Added "Pre-React 18 vs React 18+" sections

Lesson: Date your knowledge. Update quarterly.

---

• ✅ Skill creation from expertise
• ✅ Skill auditing and improvement
• ✅ Anti-pattern detection and prevention
• ✅ Progressive disclosure design
• ✅ Domain expertise encoding (shibboleths)
• ✅ Self-contained tool implementation
• ✅ Activation debugging and optimization
• ✅ Validation and packaging workflows

Use this skill to create skills that make users immediately productive.