cc-dev-template 0.1.48 → 0.1.49

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

@@ -1,345 +0,0 @@
-# Skill Development Principles
-
-## Contents
-
-- [The Fundamental Truth](#the-fundamental-truth)
-- [Documentation vs Instructions](#the-most-common-mistake-documentation-vs-instructions)
-- [Progressive Disclosure](#progressive-disclosure)
-- [Frontmatter Requirements](#frontmatter-requirements)
-- [Skill Structure](#skill-structure)
-- [Size Guidelines](#size-guidelines)
-- [Activation Patterns](#activation-patterns)
-- [Iterative Development](#iterative-development)
-- [Anti-patterns](#anti-patterns)
-- [MCP Tool References](#mcp-tool-references)
-- [Common Mistakes](#common-mistakes)
-- [Validation](#validation)
-
----
-
-## 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.
-
-## The Most Common Mistake: Documentation vs Instructions
-
-**This is the #1 reason skills fail.** People write SKILL.md as if it's a README explaining what the skill does. But SKILL.md IS the prompt—it must tell Claude what to DO.
-
-### Documentation (WRONG)
-
-```markdown
-## Purpose
-
-This skill orchestrates the complete migration of Oracle Forms to React/Go.
-
-**Who this is for**: Developers migrating Oracle Forms.
-
-**Success looks like**: Running /implement-form progresses through all phases.
-
-## How It Works
-
-The skill has 12 phases. Phase 1 does scaffolding, Phase 2 does discovery...
-```
-
-**Why this fails:** Claude reads this and thinks "interesting information, but what should I DO right now?" There are no actionable instructions.
-
-### Instructions (CORRECT)
-
-```markdown
-## What To Do Now
-
-Ask which form to implement. Store the form name.
-
-Then check workflow state:
-Look for `.claude/workflows/{formname}/workflow.yaml`
-
-If exists: Read it, determine current phase.
-If not: Create new workflow, start at phase 1.
-
-Based on `currentPhase`, read the appropriate file:
-
-| Phase | File |
-|-------|------|
-| phase1 | `references/phase1.md` |
-| phase2 | `references/phase2.md` |
-```
-
-**Why this works:** Claude knows exactly what to do. Each step is an action. Heavy content (schemas, phase details) lives in references/.
-
-### Red Flags in SKILL.md
-
-| Red Flag | Problem |
-|----------|---------|
-| "Who this is for:" | Meta-description. Claude doesn't need audience info. |
-| "Success looks like:" | Describes outcomes, doesn't instruct. |
-| "This skill orchestrates..." | Describes what skill IS, not what to DO. |
-| "The purpose is..." | Documentation language. |
-| Large inline schemas | Reference material, not instructions. |
-| Phase explanations | Should route to phase files, not explain inline. |
-
-### The Test
-
-After writing SKILL.md, ask: **"If Claude reads this right now, does it know what action to take?"**
-
-If the answer is "it would understand what the skill is about" but not "it would know what to do," rewrite it.
-
-### Agent Prompts Are Different
-
-The red flags above apply to SKILL.md files, not agent prompts. Agent prompts and skills have different characteristics:
-
-| Aspect | Agent Prompt | SKILL.md |
-|--------|--------------|----------|
-| When read | Once per spawn | Repeatedly during session |
-| Purpose | Provide context for focused task | Route to workflows |
-| WHY/WHO/SUCCESS | Appropriate—crucial context | Red flag—wastes tokens |
-| Lifespan | Single invocation | Entire user session |
-
-Agent prompts benefit from a Purpose section with WHY/WHO/SUCCESS because:
-- Agents spawn for a single focused task and need full context upfront
-- The context is read once, not repeatedly
-- Understanding purpose helps agents make better decisions
-
-Skills should route to actions immediately because:
-- Users interact with skills throughout a session
-- Meta-descriptions consume tokens on every activation
-- Instructions are more valuable than context in repeated interactions
-
-## Progressive Disclosure
-
-### The Problem Without It
-
-To handle a complex workflow, all instructions must be in one giant prompt (3,000+ lines). Problems:
-- Massive context consumption upfront
-- Claude may get confused by irrelevant instructions
-- Hard to maintain and update
-- Scales poorly
-
-### The Solution: Three-Level Loading
-
-| Level | What Loads | When | Size Target |
-|-------|------------|------|-------------|
-| **1. Metadata** | `name` + `description` | Always (at startup) | ~100 words |
-| **2. SKILL.md body** | Full instructions | When skill triggers | <150 lines |
-| **3. Bundled resources** | references/, scripts/ | Only when Claude needs them | Unlimited |
-
-### 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"
-```
-
-If the user stops after planning, drafting 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)
-- Prefer gerund form (e.g., `processing-pdfs`, `creating-reports`)
-- 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.
-
-**Good (specific triggers, third person):**
-```yaml
-description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", or mentions hook events (PreToolUse, PostToolUse, Stop).
-```
-
-**Bad:**
-```yaml
-# Wrong person
-description: Use this skill when working with hooks.
-
-# Vague, no triggers
-description: Provides hook guidance.
-
-# Too detailed (Claude thinks it knows enough and won't activate)
-description: This skill parses PDF files using PyPDF2, extracts text with OCR fallback...
-```
-
-**Key insight:** If the description explains too much about WHAT, Claude believes it already knows enough and won't activate. Focus on WHEN to use, not HOW it works.
-
-## Skill Structure
-
-### Minimal
-```
-skill-name/
-└── SKILL.md
-```
-Good for: Simple knowledge, no complex workflows
-
-### Standard (Recommended)
-```
-skill-name/
-├── SKILL.md
-├── references/
-│   └── detailed-guide.md
-└── scripts/
-    └── helper.py
-```
-Good for: Most skills with detailed documentation or utilities
-
-### When to Use Each Directory
-
-**references/** - Content Claude reads into context:
-- Detailed workflow instructions
-- Domain knowledge and patterns
-- Schemas and specifications
-
-**scripts/** - Executable code for deterministic operations:
-- Validation utilities
-- Code generation
-- File operations that need reliability
-
-**assets/** - Files used in output but never read:
-- Templates Claude copies/modifies
-- Boilerplate code
-
-## Size Guidelines
-
-- **SKILL.md target**: <150 lines (routers), <300 lines (simple skills)
-- **SKILL.md maximum**: 500 lines (strongly discouraged)
-- **Reference files >100 lines**: Add a table of contents
-
-If SKILL.md exceeds limits, move content to references/.
-
-> "The context window is a public good—your skill shares it with everything else."
-
-Challenge every piece of content: Does it justify its token cost? If Claude already knows it, 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)
-- Works better with specific trigger phrases
-- Fails if description is too detailed
-
-**2. Explicit (Slash Command)**
-Every skill automatically works as a slash command using `/skill-name`. This is the most reliable activation method.
-
-**3. Hybrid (Recommended)**
-Use `/skill-name` for explicit invocation when needed, while a good description enables autonomous discovery for natural conversations.
-
-## Iterative Development
-
-The most effective skill development involves Claude itself. Work with one instance ("Claude A") to create a skill used by other instances ("Claude B").
-
-### The Pattern
-
-1. **Complete a task without a skill**: Work through a problem naturally. Notice what context you repeatedly provide.
-
-2. **Identify the reusable pattern**: After completing the task, identify what context would be useful for similar future tasks.
-
-3. **Ask Claude A to create a skill**: "Create a skill that captures this pattern we just used."
-
-4. **Review for conciseness**: Check that Claude A hasn't added unnecessary explanations. Remove what Claude already knows.
-
-5. **Test with Claude B**: Use the skill with a fresh instance on related use cases.
-
-6. **Iterate based on observation**: If Claude B struggles, return to Claude A with specifics: "When Claude used this skill, it forgot X. Should we make that more prominent?"
-
-### Why This Works
-
-- Claude A understands agent needs
-- You provide domain expertise
-- Claude B reveals gaps through real usage
-- Iterative refinement improves skills based on observed behavior rather than assumptions
-
-## Anti-patterns
-
-### Windows-Style Paths
-Always use forward slashes, even on Windows:
-- Good: `scripts/helper.py`, `reference/guide.md`
-- Bad: `scripts\helper.py`, `reference\guide.md`
-
-### Too Many Options
-Don't present multiple approaches unless necessary:
-
-**Bad:**
-"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."
-
-**Good:**
-"Use pdfplumber for text extraction. For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."
-
-Provide a default, not a menu.
-
-### Deeply Nested References
-Keep references one level deep from SKILL.md. Avoid:
-```
-SKILL.md → advanced.md → details.md → actual-info.md
-```
-
-Claude may only partially read deeply nested files.
-
-## MCP Tool References
-
-If your skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names.
-
-**Format**: `ServerName:tool_name`
-
-**Example:**
-```markdown
-Use the BigQuery:bigquery_schema tool to retrieve table schemas.
-Use the GitHub:create_issue tool to create issues.
-```
-
-Without the server prefix, Claude may fail to locate the tool when multiple MCP servers are available.
-
-## Common Mistakes
-
-### Mistake 1: Treating SKILL.md as Documentation
-Writing about the skill instead of instructions for Claude.
-
-### Mistake 2: Everything in One File
-Putting all content in SKILL.md instead of using references/.
-
-### Mistake 3: Vague Descriptions
-No trigger phrases, unclear when to use.
-
-### Mistake 4: Missing Resource References
-References exist but SKILL.md doesn't mention them.
-
-## Validation
-
-Run: `node ~/.claude/skills/creating-agent-skills/scripts/validate-skill.js [skill-path]`
-
-Manual checks:
-- Is this instructions, not documentation?
-- Would Claude know what to DO?
-- Is heavy content in references/?
-- Does the description have trigger phrases?