cc-dev-template 0.1.5 → 0.1.6

package/src/skills/create-agent-skills/references/principles.md

@@ -0,0 +1,537 @@
+# Skill Development Principles
+
+This document contains the deep knowledge required to create, audit, and modify Claude Code skills correctly. Read this before any skill work.
+
+## The Fundamental Truth
+
+**A skill is just a prompt with progressive disclosure.**
+
+| Misconception | Reality |
+|---------------|---------|
+| Skills are a special runtime | Skills are markdown files |
+| Skills have special syntax | Skills use natural language |
+| Skills execute code | Skills prompt Claude to do things |
+| Skills have state | Skills tell Claude to read/write files for state |
+| SKILL.md is documentation | SKILL.md IS the prompt Claude reads |
+
+When a skill "activates," Claude simply reads the SKILL.md file. The file contains natural language instructions telling Claude what to do.
+
+## Why Progressive Disclosure Matters
+
+### The Problem Without Skills
+
+To handle a complex workflow, all instructions must be in one giant prompt:
+
+```
+Here's how to plan a feature:
+1. First gather requirements...     [500 lines]
+2. Then explore the codebase...     [500 lines]
+3. Then check ADRs...               [500 lines]
+4. Then draft the plan...           [500 lines]
+5. Then validate...                 [500 lines]
+6. Then finalize...                 [500 lines]
+```
+
+**Problems:**
+- Massive context consumption upfront (3,000+ lines)
+- Claude may get confused by irrelevant instructions
+- Hard to maintain and update
+- Scales poorly—can't add new capabilities without bloating context
+
+### The Solution: Three-Level Loading
+
+Skills use progressive disclosure to load information just-in-time:
+
+| Level | What Loads | When | Size Target |
+|-------|------------|------|-------------|
+| **1. Metadata** | `name` + `description` | Always (at startup) | ~100 words |
+| **2. SKILL.md body** | Full instructions | When skill triggers | 1,500-2,000 words |
+| **3. Bundled resources** | references/, scripts/, assets/ | Only when Claude needs them | Unlimited |
+
+**Benefits:**
+- Small initial context footprint
+- Claude only sees relevant instructions for current phase
+- Easy to add/modify individual phases
+- Scales infinitely—heavy content lives in references/
+
+### Progressive Disclosure in Practice
+
+```
+SKILL.md (small router):
+  "Ask what user wants.
+   If planning → read references/planning.md"
+
+references/planning.md:
+  "Gather requirements.
+   When done → read references/drafting.md"
+
+references/drafting.md:
+  "Create the plan artifact.
+   When done → read references/validation.md"
+```
+
+If the user stops after planning, drafting and validation instructions are never loaded.
+
+## Frontmatter Requirements
+
+### Required Fields
+
+```yaml
+---
+name: skill-name
+description: What this skill does and when to use it
+---
+```
+
+**name:**
+- Hyphen-case format (lowercase + hyphens only)
+- Must match the directory name
+- Max 64 characters
+
+**description:**
+- Max 1024 characters
+- CRITICAL for discovery—this determines when Claude triggers the skill
+- Must explain WHAT and WHEN
+
+### Description Quality
+
+The description is the most important part of a skill. Claude uses it to decide whether to activate.
+
+**Third-person format with trigger phrases:**
+
+```yaml
+# GOOD - specific triggers, third person
+description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events (PreToolUse, PostToolUse, Stop).
+
+# GOOD - clear scenarios
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+**Common mistakes:**
+
+```yaml
+# BAD - wrong person
+description: Use this skill when working with hooks.
+
+# BAD - vague, no triggers
+description: Provides hook guidance.
+
+# BAD - no "when to use"
+description: A skill for managing PDFs.
+
+# BAD - too much detail (makes Claude think it can wing it)
+description: This skill parses PDF files using PyPDF2, extracts text with OCR fallback, handles encrypted files with password prompts, and outputs to markdown format with table preservation...
+```
+
+**Key insight from community testing:** If the description explains too much about WHAT the skill does, Claude believes it already knows enough and won't activate the skill. Keep descriptions focused on WHEN to use, not HOW it works internally.
+
+### Optional Fields
+
+```yaml
+---
+name: skill-name
+description: ...
+license: Apache-2.0
+allowed-tools: Read, Grep, Glob, Write
+metadata:
+  version: 1.0.0
+  author: team-name
+---
+```
+
+- `allowed-tools`: Restricts which tools Claude can use (security/safety)
+- `license`: For distributed skills
+- `metadata`: Custom key-value pairs
+
+## Writing Style Requirements
+
+### Imperative/Infinitive Form (Mandatory)
+
+Write instructions as directives, not suggestions or descriptions.
+
+**Correct (imperative):**
+```markdown
+Parse the configuration file.
+Extract the relevant fields.
+Validate input before processing.
+Run the test suite to verify changes.
+```
+
+**Incorrect (second person):**
+```markdown
+You should parse the configuration file.
+You can extract the relevant fields.
+You need to validate input before processing.
+You might want to run the test suite.
+```
+
+**Incorrect (passive/descriptive):**
+```markdown
+The configuration file should be parsed.
+Fields are extracted from the response.
+Input validation is performed.
+```
+
+### Objective Instructional Tone
+
+Focus on WHAT to do, not WHO should do it:
+
+**Correct:**
+```markdown
+To accomplish X, do Y.
+For validation, check the following criteria.
+When errors occur, retry with exponential backoff.
+```
+
+**Incorrect:**
+```markdown
+You can accomplish X by doing Y.
+Claude should check the following criteria.
+If you encounter errors, you might retry.
+```
+
+### Positive Framing
+
+Tell Claude what TO do, not what NOT to do:
+
+| Negative (avoid) | Positive (correct) |
+|------------------|-------------------|
+| Don't hallucinate facts | Only use information from provided documents |
+| Don't be too formal | Write in a conversational, friendly tone |
+| Avoid long paragraphs | Keep paragraphs to 3-4 sentences |
+| Don't skip error handling | Include comprehensive error handling |
+| Never make assumptions | Base responses on provided data |
+
+## Skill Structure
+
+### Minimal Skill
+
+```
+skill-name/
+└── SKILL.md
+```
+
+Good for: Simple knowledge, no complex workflows
+
+### Standard Skill (Recommended)
+
+```
+skill-name/
+├── SKILL.md
+├── references/
+│   └── detailed-guide.md
+└── scripts/
+    └── helper.py
+```
+
+Good for: Most skills with detailed documentation or utilities
+
+### Complete Skill
+
+```
+skill-name/
+├── SKILL.md              # Lean router
+├── references/           # Docs loaded as needed
+│   ├── workflow-1.md
+│   ├── workflow-2.md
+│   └── patterns.md
+├── scripts/              # Executable utilities
+│   ├── validate.py
+│   └── generate.sh
+└── assets/               # Files for output (templates, etc.)
+    └── template.yaml
+```
+
+Good for: Complex multi-workflow skills
+
+### When to Use Each Directory
+
+**references/** - Documentation that Claude should read into context:
+- Detailed workflow instructions
+- Domain knowledge and patterns
+- API documentation
+- Schemas and specifications
+
+**scripts/** - Executable code for deterministic operations:
+- Validation utilities
+- Code generation
+- Data transformation
+- File operations that need reliability
+
+**Benefits of scripts:** Execute without loading into context (token-efficient), deterministic reliability, can be tested independently
+
+**assets/** - Files used in output but never read:
+- Templates Claude copies/modifies
+- Boilerplate code
+- Images, icons, fonts
+- Sample documents
+
+## Size Guidelines
+
+### SKILL.md Body
+- **Target**: 1,500-2,000 words
+- **Maximum**: 5,000 words (strongly discouraged)
+- **Anthropic guidance**: Under 500 lines
+
+If SKILL.md exceeds these limits, move content to references/.
+
+### Why Size Matters
+
+> "The context window is a public good—your skill shares it with everything else. Once loaded, every token competes with conversation history."
+> — Anthropic Engineering
+
+Challenge every piece of content: Does it justify its token cost? If Claude already knows it (general programming knowledge, common patterns), remove it.
+
+## Activation Patterns
+
+### How Skills Activate
+
+**1. Autonomous (Description Match)**
+Claude reads skill descriptions and decides when to activate based on user request matching.
+
+- Less reliable (~50-84% success rate in community testing)
+- Works better with specific trigger phrases
+- Can fail if description is too detailed (Claude thinks it knows enough)
+
+**2. Explicit (Slash Command)**
+A slash command forces skill activation:
+
+```markdown
+# /create-skill command
+Activate the create-agent-skills skill to guide the user through skill creation.
+```
+
+- Most reliable method
+- Use for critical workflows
+- Don't rely solely on autonomous activation
+
+**3. Hybrid (Recommended)**
+Slash command for explicit invocation + good description for autonomous discovery.
+
+### Improving Activation Reliability
+
+1. **Specific trigger phrases** in description
+2. **Reference in CLAUDE.md** for project skills
+3. **Keep description focused on WHEN**, not detailed HOW
+
+## Common Mistakes
+
+### Mistake 1: Treating SKILL.md as Documentation
+
+**Problem:** Writing about the skill instead of instructions for Claude
+
+```markdown
+# BAD - describes the skill
+This skill helps users create PDF documents. It uses PyPDF2
+for parsing and supports various output formats...
+```
+
+```markdown
+# GOOD - instructs Claude
+Parse the input PDF using the bundled script.
+Extract text content, preserving table structure.
+Output as markdown with proper heading hierarchy.
+```
+
+### Mistake 2: Everything in One File
+
+**Problem:** Putting all content in SKILL.md
+
+```
+skill-name/
+└── SKILL.md  (8,000 words)
+```
+
+**Solution:** Use progressive disclosure
+
+```
+skill-name/
+├── SKILL.md  (1,800 words - router)
+└── references/
+    ├── workflow-a.md (2,500 words)
+    └── workflow-b.md (3,700 words)
+```
+
+### Mistake 3: Vague Descriptions
+
+**Problem:** No trigger phrases, unclear when to use
+
+```yaml
+description: Helps with code review.
+```
+
+**Solution:** Specific scenarios and phrases
+
+```yaml
+description: This skill should be used when the user asks to "review this PR", "check my code", "find bugs", or mentions code quality, security review, or performance analysis.
+```
+
+### Mistake 4: Second Person Writing
+
+**Problem:** Using "you" throughout
+
+```markdown
+You should first read the config file.
+Then you can parse the fields.
+You might want to validate the output.
+```
+
+**Solution:** Imperative form
+
+```markdown
+First read the config file.
+Parse the fields using the schema.
+Validate output against expected format.
+```
+
+### Mistake 5: Missing Resource References
+
+**Problem:** References exist but SKILL.md doesn't mention them
+
+```markdown
+# SKILL.md
+[Content with no mention of references/]
+```
+
+**Solution:** Explicit pointers to resources
+
+```markdown
+## Additional Resources
+
+For detailed patterns, read `references/patterns.md`.
+For validation, run `scripts/validate.py`.
+```
+
+## Prompting Principles for Skill Content
+
+Skills ARE prompts. The quality of a skill depends on applying good prompting principles when writing its content. These principles come from ADR-002 (Structured Prompting Practices) and the `prompting` skill.
+
+### Core Principle: Explain WHY, Not Just WHAT
+
+Provide purpose and context rather than exhaustive implementation details. Trust Claude's intelligence.
+
+**Mental Model**: Treat Claude like a brilliant senior colleague, not a junior who needs hand-holding.
+
+**Provide:**
+- The goal or purpose of the task
+- Why this matters (business context, use case)
+- Constraints that exist (technical, business, regulatory)
+- What success looks like
+
+**Avoid providing:**
+- Every possible edge case (Claude handles these intelligently)
+- Step-by-step implementation unless genuinely needed
+- Obvious best practices for the domain
+
+### Use Positive Framing
+
+Tell Claude what TO do, not what NOT to do. Negatives require extra processing and can prime unwanted behavior.
+
+| Negative Framing | Positive Framing |
+|------------------|------------------|
+| "Don't hallucinate facts" | "Only use information from the provided documents" |
+| "Don't be too verbose" | "Keep responses concise and focused" |
+| "Avoid making assumptions" | "Base responses on the provided data" |
+| "Never skip validation" | "Always validate input before processing" |
+
+### Be Clear and Direct
+
+Claude 4.x models are more literal than previous versions. State exactly what is needed without hedging.
+
+| Vague | Clear |
+|-------|-------|
+| "Maybe consider validating..." | "Validate input before processing" |
+| "It might be helpful to..." | "Include error handling for edge cases" |
+| "You could potentially..." | "Generate tests for all public functions" |
+
+### Provide Context
+
+Every skill instruction benefits from context. Answer:
+1. **Why does this matter?** (Purpose, goal)
+2. **Who is this for?** (Audience, user type)
+3. **What does success look like?** (Outcomes, criteria)
+4. **What constraints exist?** (Technical limits, requirements)
+
+### The Complete Prompt Checklist
+
+When writing skill content, verify each section answers:
+
+- [ ] **WHAT** is Claude being asked to do?
+- [ ] **WHY** does this matter? (Purpose, goal)
+- [ ] **WHO** is this for? (Audience, user type)
+- [ ] **SUCCESS** looks like what? (Outcomes, criteria)
+- [ ] Frame everything **POSITIVELY** (what TO do)
+
+### Quick Diagnostics
+
+If a skill produces problematic results:
+
+| Problem | Likely Cause | Fix |
+|---------|--------------|-----|
+| Too minimal/basic | Not explicit about expectations | Add "Create a fully-featured..." or specify depth |
+| Off-topic | Missing context about purpose | Explain WHY and what it's for |
+| Inconsistent | Vague instructions | Be more direct and specific |
+| Overly cautious | Negative framing | Reframe positively |
+| Missing key details | Didn't explain success criteria | Define concrete outcomes |
+
+### Common Antipatterns
+
+**The Micromanager**: Providing step-by-step implementation instead of goals.
+- Fix: Explain the goal, let Claude handle implementation.
+
+**The Negative Nancy**: String of "don't do X" instructions.
+- Fix: Reframe every negative as a positive instruction.
+
+**The Context-Free Zone**: Bare instruction with no purpose or audience.
+- Fix: Explain who uses it, why it exists, what success looks like.
+
+**The Vague Suggestion**: Hedged language like "maybe consider..."
+- Fix: Be direct and explicit about what is needed.
+
+### Reference
+
+For comprehensive prompting guidance, consult:
+- **ADR-002**: Structured Prompting Practices for Agents and Commands
+- **Prompting skill**: `~/.claude/skills/prompting/SKILL.md`
+
+These principles are mandatory for all skill content. Apply them when writing SKILL.md files and reference documents.
+
+## Validation Checklist
+
+Before finalizing any skill, verify:
+
+### Structure
+- [ ] SKILL.md exists with valid YAML frontmatter
+- [ ] `name` field matches directory name (hyphen-case)
+- [ ] `description` field present and under 1024 characters
+- [ ] All referenced files actually exist
+
+### Description Quality
+- [ ] Uses third person ("This skill should be used when...")
+- [ ] Includes specific trigger phrases
+- [ ] Lists concrete scenarios
+- [ ] Not overly detailed about implementation
+
+### Content Quality
+- [ ] Body uses imperative/infinitive form throughout
+- [ ] No second person ("you should", "you can")
+- [ ] Body under 2,000 words (or content moved to references/)
+- [ ] Positive framing (what TO do, not what NOT to do)
+
+### Prompting Quality
+- [ ] Explains WHY, not just WHAT (purpose and context provided)
+- [ ] Clear and direct language (no hedging or vague suggestions)
+- [ ] Success criteria defined (what does good output look like?)
+- [ ] Avoids micromanagement (goals over step-by-step instructions)
+- [ ] No antipatterns (Micromanager, Negative Nancy, Context-Free Zone, Vague Suggestion)
+
+### Progressive Disclosure
+- [ ] SKILL.md acts as router to heavier content
+- [ ] Detailed docs in references/
+- [ ] Deterministic operations in scripts/
+- [ ] References clearly pointed to from SKILL.md
+
+### Testing
+- [ ] Skill triggers on expected user queries
+- [ ] Content is helpful for intended tasks
+- [ ] No duplicated information across files