npm - cc-dev-template - Versions diffs - 0.1.7 → 0.1.8 - Mend

cc-dev-template 0.1.7 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/skills/create-agent-skills/references/audit.md CHANGED Viewed

@@ -1,429 +1,93 @@
 # Audit Existing Skills
-This workflow discovers and reviews all installed skills against best practices. The most important check is whether the SKILL.md is written as a proper prompt, not as documentation.
+Read `references/principles.md` first.
-## Purpose
+## What To Do
-Systematically review skills to identify:
-- **Fundamental prompt problems** - Is this written as instructions TO Claude or documentation ABOUT the skill?
-- Content that belongs in references, not SKILL.md
-- Structural issues (missing files, wrong format)
-- Description problems (vague, wrong person, missing triggers)
-- Writing style violations
+1. **Discover skills** - Run `scripts/find-skills.js` to list available skills
+2. **Ask which to audit** - Get user's choice (all, user-level, project-level, or specific skill)
+3. **Read everything** - Read SKILL.md AND every file in references/, workflows/, scripts/
+4. **Evaluate each file** - Ask: Would Claude know what to DO after reading this?
+5. **Report findings** - Present issues with principle violated and suggested fix
-**Success looks like:** Actually reading each skill and evaluating whether it would work as a prompt. Surface fundamental problems, not just superficial style issues.
+## What Makes a Good Skill
-## Before Starting
+**Actionability**: Every file tells Claude what to DO, not what the skill is ABOUT.
-Read `references/principles.md` to understand what makes a good skill.
+**Progressive disclosure**: SKILL.md is lean (<150 lines). Heavy content lives in references/. Claude loads what it needs when it needs it.
-**Critical understanding:** A SKILL.md IS the prompt. When Claude activates a skill, it reads SKILL.md. If SKILL.md reads like documentation ("This skill does X", "Who this is for"), Claude won't know what to DO.
+**Routing coherence**: Multi-phase skills route to reference files. Each file hands off clearly to the next step or completes the flow.
-## Workflow
+**No dead ends**: At every point, Claude knows what to do next.
-<steps>
+## How to Audit
-<step name="Discover All Skills">
-Find skills at both user and project levels.
+### 1. Discover and Read Everything
-**Locations to scan:**
-```
-~/.claude/skills/          # User-level skills
-.claude/skills/            # Project-level skills (current project)
-src/skills/                # Source skills (if in dev-template)
-```
-**Run the discovery script:**
-```bash
-node ~/.claude/skills/create-agent-skills/scripts/find-skills.js
-```
-**For each skill found, record:**
-- Full path to SKILL.md
-- Skill name (directory name)
-- Location type (user/project/source)
-</step>
-<step name="Ask Audit Scope">
-Determine what to audit.
-Use `AskUserQuestion`:
-- **All skills** - Review everything discovered
-- **User-level only** - Just ~/.claude/skills/
-- **Project-level only** - Just .claude/skills/
-- **Specific skill** - Name the skill to audit
-If user selects "Specific skill," ask which one from the discovered list.
-</step>
-<step name="Audit Each Skill">
-For each skill in scope, **READ THE ENTIRE SKILL.MD FILE** and perform these checks in order. The first check is the most important.
----
-### CHECK 0: Is This Written as a Prompt? (CRITICAL)
-**This is the most important check.** Read the entire SKILL.md and evaluate:
-**Is it instructions TO Claude, or documentation ABOUT the skill?**
-A SKILL.md should tell Claude what to DO right now. It should NOT describe what the skill is, who it's for, or how it works abstractly.
-**Red flags that indicate documentation, not a prompt:**
-| Red Flag | Why It's Wrong |
-|----------|----------------|
-| "Who this is for: Developers..." | Meta-description. Claude doesn't need to know the audience. |
-| "Success looks like: Running X produces Y" | Meta-description. This describes outcomes, doesn't instruct. |
-| "This skill orchestrates..." | Describes what skill IS, not what to DO. |
-| "The purpose of this skill is..." | Documentation language, not instruction. |
-| Large inline schemas (YAML, JSON examples) | Should be in references/, loaded when needed. |
-| Explaining how phases work abstractly | Should just route to phase files with instructions. |
-**What a good SKILL.md looks like:**
-```markdown
-## What To Do Now
-<step name="Get Input">
-Ask the user which form to implement.
-</step>
-<step name="Check State">
-Look for existing workflow at `.claude/workflows/{formname}/workflow.yaml`
-If exists: Read it, determine current phase.
-If not: Initialize new workflow.
-</step>
-<step name="Route to Phase">
-Based on current phase, read the appropriate file:
-| Phase | File |
-|-------|------|
-| phase1 | `references/phase1.md` |
-| phase2 | `references/phase2.md` |
-</step>
-```
-**What a BAD SKILL.md looks like:**
-```markdown
-## Purpose
-This skill orchestrates the complete migration of Oracle Forms...
-**Who this is for**: Developers migrating Oracle Forms.
+Use `scripts/find-skills.js` to list available skills. After selecting a skill to audit:
-**Success looks like**: Running /implement-form progresses through all phases.
+- Read SKILL.md completely
+- Read every file in references/, workflows/, and any other subdirectories
+- Trace the execution path: if SKILL.md says "read references/phase1.md", read that file too
-## Phase Overview
+**You cannot audit a skill without reading all its files.**
-Phase 1 does X, Phase 2 does Y...
+### 2. Evaluate Each File
-## YAML Schema
+For each file, ask:
-```yaml
-# 50 lines of YAML schema inline
-```
-```
-**Evaluation questions:**
-1. If Claude reads this right now, does it know what to DO?
-2. Is there a clear "What To Do Now" section with concrete steps?
-3. Or does it just describe what the skill is and how it works?
+- After reading this, would Claude know what to DO next?
+- Does this tell Claude what to DO, or just describe what the skill is ABOUT?
+- Does this file hand off clearly to another file, or is there a dead end?
+- Are any referenced files missing?
-**Record severity:**
-- **CRITICAL** if SKILL.md reads like documentation
-- **CRITICAL** if large schemas/examples are inline instead of in references/
-- **CRITICAL** if no clear action instructions exist
+### 3. Note External Dependencies
-```
-PROMPT_QUALITY: [skill-name] - CRITICAL: Written as documentation, not instructions. Contains "Who this is for", "Success looks like" meta-descriptions.
-PROMPT_QUALITY: [skill-name] - CRITICAL: ~200 lines of YAML schemas inline. Move to references/.
-PROMPT_QUALITY: [skill-name] - CRITICAL: No "What To Do" section. Claude won't know what action to take.
-```
+If the skill references:
+- Sub-agents (e.g., "spawn adr-agent")
+- Commands (e.g., "run /create-adr")
+- Scripts outside the skill directory
----
+Flag these with their expected locations. They aren't audited here, but the user should know they exist.
-### CHECK 1: Content That Should Be in References
+### 4. Check Structural Basics
-**Read the SKILL.md and identify content that doesn't belong:**
+- SKILL.md has valid YAML frontmatter (name, description)
+- Name matches directory name
+- Description explains WHEN to use (trigger phrases), not just WHAT it does
+- Files referenced in SKILL.md actually exist
-| Content Type | Should Be In | Why |
-|--------------|--------------|-----|
-| YAML/JSON schemas | `references/schemas.md` | Loaded only when needed |
-| Detailed phase explanations | `references/phaseN.md` | Progressive disclosure |
-| Examples >10 lines | `references/examples.md` | Keep SKILL.md lean |
-| API documentation | `references/api.md` | Not needed upfront |
-| Historical context | `references/background.md` | Not actionable |
+## Red Flags
-**Count lines of inline content that should be moved:**
-- Code blocks >20 lines
-- Tables >10 rows
-- Schema definitions
-- Detailed explanations of internals
+**Documentation language**: "This skill orchestrates...", "Who this is for:", "Success looks like:" - these describe, they don't instruct.
-**Record issues:**
-```
-CONTENT: [skill-name] - ~150 lines of YAML schemas should be in references/
-CONTENT: [skill-name] - Phase explanations (lines 50-200) should be in separate phase files
-CONTENT: [skill-name] - "Key Design Principles" section is background, not instructions
-```
+**Inline heavy content**: Large YAML schemas, detailed examples, extensive phase explanations - these belong in references/.
----
+**No clear action**: After reading a file, Claude doesn't know what to do next.
-### CHECK 2: Router Pattern (for complex skills)
+**Missing routing**: Multi-phase skill but all content inline instead of routing to reference files.
-**If the skill has multiple workflows or phases:**
+## Report Format
-Does SKILL.md act as a lean router that:
-1. Asks/determines what to do
-2. Routes to the appropriate reference file
-3. Lets the reference file contain the detailed instructions
-**Good pattern:**
-```markdown
-<step name="Route to Phase">
-| currentPhase | Action |
-|--------------|--------|
-| phase1 | Read `references/phase1.md` |
-| phase2 | Read `references/phase2.md` |
-</step>
-```
-**Bad pattern:**
 ```markdown
-## Phase 1: Scaffolding
-[100 lines of phase 1 instructions]
-## Phase 2: Discovery
-[100 lines of phase 2 instructions]
-## Phase 3: Analysis
-[100 lines of phase 3 instructions]
-```
-**Record issues:**
-```
-ROUTER: [skill-name] - Has 12 phases but all instructions inline. Should route to reference files.
-ROUTER: [skill-name] - references/ directory exists but SKILL.md doesn't route to it.
-```
----
-### CHECK 3: Structure Validation
-**Verify:**
-- [ ] SKILL.md exists
-- [ ] SKILL.md has YAML frontmatter (starts with `---`)
-- [ ] Frontmatter has `name` field
-- [ ] Frontmatter has `description` field
-- [ ] `name` matches directory name
-- [ ] `name` is hyphen-case (lowercase, hyphens only)
-**Record issues:**
-```
-STRUCTURE: [skill-name] - [specific issue]
-```
----
-### CHECK 4: Description Quality
-**Read the description and verify:**
-- [ ] Under 1024 characters
-- [ ] Uses third person ("This skill should be used when...")
-- [ ] Contains specific trigger phrases users would say
-- [ ] Explains WHEN to use, not just WHAT it does
-**Record issues:**
-```
-DESCRIPTION: [skill-name] - [specific issue]
-```
+# Audit Report: [skill-name]
----
+## Summary
+- Files audited: [list all files read]
+- External dependencies: [list any sub-agents, commands, scripts referenced]
-### CHECK 5: Writing Style
+## Findings
-**Scan for second person:**
-- "you should", "you can", "you need", "you might", "your"
-**Scan for negative framing:**
-- "don't", "never", "avoid", "do not"
-**Record issues:**
-```
-STYLE: [skill-name] - Found [count] instances of second person
-STYLE: [skill-name] - Negative framing: "[example]"
-```
----
-### CHECK 6: Size Analysis
-**Measure:**
-- Word count of SKILL.md body
-- Line count
-**Thresholds:**
-| Metric | Good | Warning | Critical |
-|--------|------|---------|----------|
-| Words | <2,000 | 2,000-3,500 | >3,500 |
-| Lines | <300 | 300-500 | >500 |
-**Record issues:**
-```
-SIZE: [skill-name] - SKILL.md is [X] words ([Y] lines) - needs restructuring
-```
----
-### CHECK 7: Reference Integrity
-**For every path mentioned in SKILL.md:**
-- Verify file exists
-- Flag broken references
-**For every file in references/:**
-- Check if SKILL.md mentions it
-- Flag orphaned files
-**Record issues:**
-```
-BROKEN: [skill-name] - References `references/phase1.md` but file doesn't exist
-ORPHAN: [skill-name] - `references/old-workflow.md` exists but isn't referenced
-```
-</step>
-<step name="Generate Report">
-Compile findings, prioritizing CRITICAL issues first.
-**Report format:**
-```markdown
-# Skill Audit Report
-Generated: [timestamp]
-Skills audited: [count]
-## Critical Issues (Fix Immediately)
-### [skill-name]
-- PROMPT_QUALITY: Written as documentation, not instructions
-  - Contains "Who this is for:", "Success looks like:" meta-descriptions
-  - No clear "What To Do" section
-  - ~200 lines of inline YAML schemas
-  **This skill will not work properly.** Claude won't know what action to take.
-## Warnings
-### [skill-name]
-- SIZE: 2,800 words - consider moving content to references/
-- STYLE: 3 instances of negative framing
+### [Issue title]
+**File**: [path]
+**Problem**: [what's wrong]
+**Principle**: [which principle is violated - actionability, progressive disclosure, routing, etc.]
+**Suggested fix**: [specific rewrite or change]
 ## Passing
-- skill-name-1
-- skill-name-2
-## Recommendations
-1. **[skill-name]**: Complete rewrite needed. Current version is documentation, not a prompt.
-2. **[other-skill]**: Move YAML schemas to references/schemas.md
+[What works well about this skill]
 ```
-**Present the report to the user.**
-</step>
-<step name="Offer Fixes">
-After presenting the report, offer to help fix issues.
-**For CRITICAL prompt quality issues:**
-Offer to help rewrite the skill properly. This requires:
-1. Understanding what the skill should DO
-2. Rewriting as instructions, not documentation
-3. Moving heavy content to references/
-4. Creating proper router pattern
-**For other issues:**
-- Second person → imperative conversion
-- Negative → positive framing
-- Content moves to references/
-Use `AskUserQuestion`:
-- **Help fix critical issues** - Work through rewriting problematic skills
-- **Fix style issues only** - Auto-fix second person, negative framing
-- **Just the report** - No fixes now
-If user wants to fix critical issues, transition to `references/modify.md`.
-</step>
-</steps>
-## Quick Audit Checklist
-### Critical (Must Fix)
-- [ ] SKILL.md is written as instructions, not documentation
-- [ ] No meta-descriptions ("Who this is for", "Success looks like")
-- [ ] Clear "What To Do" section with concrete steps
-- [ ] Heavy content (schemas, examples) in references/, not inline
-- [ ] Router pattern used for multi-phase skills
-### Important
-- [ ] Valid frontmatter with name and description
-- [ ] Description has trigger phrases
-- [ ] Under 2,000 words
-- [ ] All references exist
-### Style
-- [ ] No second person
-- [ ] Positive framing
-- [ ] Imperative form
-## Anti-Patterns to Catch
-### The Documentation Skill
-**Pattern:** Reads like a README explaining what the skill does.
-```markdown
-## Purpose
-This skill helps developers migrate forms...
-## Who This Is For
-Developers working on Oracle Forms migration.
-## How It Works
-The skill has 12 phases...
-```
-**Problem:** Claude reads this and thinks "interesting, but what should I DO?"
-**Fix:** Rewrite as instructions:
-```markdown
-## What To Do Now
-<step name="Get Form Name">
-Ask which form to implement.
-</step>
-<step name="Route to Current Phase">
-Read workflow.yaml, route to appropriate phase file.
-</step>
-```
-### The Kitchen Sink Skill
-**Pattern:** Everything inline, no progressive disclosure.
-**Problem:** 500+ lines, Claude gets lost in irrelevant details.
-**Fix:** Keep SKILL.md as router (<150 lines), move details to references/.
-### The Schema Dump
-**Pattern:** 100+ lines of YAML/JSON schemas inline.
-**Problem:** Schemas are reference material, not instructions.
+## After the Audit
-**Fix:** Move to `references/schemas.md`, reference when needed.
+Present findings to the user. If issues were found, offer to help fix them. For significant rewrites (documentation → instructions), transition to `references/modify.md`.

package/src/skills/create-agent-skills/references/create.md CHANGED Viewed

@@ -1,7 +1,5 @@
 # Create a New Skill
-Guide the user through building a skill via interactive conversation. Extract their domain knowledge, then produce a properly structured skill.
 ## What To Do
 <steps>

package/src/skills/create-agent-skills/references/modify.md CHANGED Viewed

@@ -1,7 +1,5 @@
 # Modify an Existing Skill
-Fix issues, add capabilities, or refine behavior of an existing skill.
 ## What To Do
 <steps>

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

@@ -1,7 +1,5 @@
 # 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.**
@@ -34,16 +32,6 @@ This skill orchestrates the complete migration of Oracle Forms to React/Go.
 ## How It Works
 The skill has 12 phases. Phase 1 does scaffolding, Phase 2 does discovery...
-## YAML Schema
-```yaml
-form:
-  name: FORMNAME
-  prefix: xx
-status: in_progress
-# ... 50 more lines of schema
-```
 ```
 **Why this fails:** Claude reads this and thinks "interesting information, but what should I DO right now?" There are no actionable instructions.
@@ -93,45 +81,25 @@ After writing SKILL.md, ask: **"If Claude reads this right now, does it know wha
 If the answer is "it would understand what the skill is about" but not "it would know what to do," rewrite it.
-## Why Progressive Disclosure Matters
+## Progressive Disclosure
-### 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]
-```
+### The Problem Without It
-**Problems:**
-- Massive context consumption upfront (3,000+ lines)
+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—can't add new capabilities without bloating context
+- Scales poorly
 ### 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/
+| **2. SKILL.md body** | Full instructions | When skill triggers | <2,000 words |
+| **3. Bundled resources** | references/, scripts/ | Only when Claude needs them | Unlimited |
-### Progressive Disclosure in Practice
+### In Practice
 ```
 SKILL.md (small router):
@@ -141,13 +109,9 @@ SKILL.md (small router):
 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.
+If the user stops after planning, drafting instructions are never loaded.
 ## Frontmatter Requirements
@@ -174,124 +138,35 @@ description: What this skill does and when to use it
 The description is the most important part of a skill. Claude uses it to decide whether to activate.
-**Third-person format with trigger phrases:**
+**Good (specific triggers, third person):**
 ```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.
+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).
 ```
-**Common mistakes:**
+**Bad:**
 ```yaml
-# BAD - wrong person
+# Wrong person
 description: Use this skill when working with hooks.
-# BAD - vague, no triggers
+# 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...
+# 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 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 |
+**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
+### Minimal
 ```
 skill-name/
 └── SKILL.md
 ```
 Good for: Simple knowledge, no complex workflows
-### Standard Skill (Recommended)
+### Standard (Recommended)
 ```
 skill-name/
 ├── SKILL.md
@@ -300,64 +175,34 @@ skill-name/
 └── 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:
+**references/** - Content Claude reads 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/.
+- **SKILL.md target**: <2,000 words
+- **SKILL.md maximum**: 5,000 words (strongly discouraged)
-### Why Size Matters
+If SKILL.md exceeds limits, move content to references/.
-> "The context window is a public good—your skill shares it with everything else. Once loaded, every token competes with conversation history."
-> — Anthropic Engineering
+> "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 (general programming knowledge, common patterns), remove it.
+Challenge every piece of content: Does it justify its token cost? If Claude already knows it, remove it.
 ## Activation Patterns
@@ -365,250 +210,41 @@ Challenge every piece of content: Does it justify its token cost? If Claude alre
 **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)
+- Less reliable (~50-84% success rate)
 - Works better with specific trigger phrases
-- Can fail if description is too detailed (Claude thinks it knows enough)
+- Fails if description is too detailed
 **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
+Most reliable method.
 **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.
-```
+Writing about the skill instead of instructions for Claude.
 ### 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)
-```
+Putting all content in SKILL.md instead of using references/.
 ### Mistake 3: Vague Descriptions
+No trigger phrases, unclear when to use.
-**Problem:** No trigger phrases, unclear when to use
+### Mistake 4: Missing Resource References
+References exist but SKILL.md doesn't mention them.
-```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.
-```
+## Validation
-### Mistake 4: Second Person Writing
+Run: `node ~/.claude/skills/create-agent-skills/scripts/validate-skill.js [skill-path]`
-**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
+Manual checks:
+- Is this instructions, not documentation?
+- Would Claude know what to DO?
+- Is heavy content in references/?
+- Does the description have trigger phrases?

package/src/skills/create-agent-skills/templates/router-skill.md ADDED Viewed

@@ -0,0 +1,73 @@
+---
+name: {{SKILL_NAME}}
+description: {{What it does}} Use when {{trigger conditions}}.
+---
+<essential_principles>
+## {{Core Concept}}
+{{Principles that ALWAYS apply, regardless of which workflow runs}}
+### 1. {{First principle}}
+{{Explanation}}
+### 2. {{Second principle}}
+{{Explanation}}
+### 3. {{Third principle}}
+{{Explanation}}
+</essential_principles>
+<intake>
+**Ask the user:**
+What would you like to do?
+1. {{First option}}
+2. {{Second option}}
+3. {{Third option}}
+**Wait for response before proceeding.**
+</intake>
+<routing>
+| Response | Workflow |
+|----------|----------|
+| 1, "{{keywords}}" | `workflows/{{first-workflow}}.md` |
+| 2, "{{keywords}}" | `workflows/{{second-workflow}}.md` |
+| 3, "{{keywords}}" | `workflows/{{third-workflow}}.md` |
+**After reading the workflow, follow it exactly.**
+</routing>
+<quick_reference>
+## {{Skill Name}} Quick Reference
+{{Brief reference information always useful to have visible}}
+</quick_reference>
+<reference_index>
+## Domain Knowledge
+All in `references/`:
+- {{reference-1.md}} - {{purpose}}
+- {{reference-2.md}} - {{purpose}}
+</reference_index>
+<workflows_index>
+## Workflows
+All in `workflows/`:
+| Workflow | Purpose |
+|----------|---------|
+| {{first-workflow}}.md | {{purpose}} |
+| {{second-workflow}}.md | {{purpose}} |
+| {{third-workflow}}.md | {{purpose}} |
+</workflows_index>
+<success_criteria>
+A well-executed {{skill name}}:
+- {{First criterion}}
+- {{Second criterion}}
+- {{Third criterion}}
+</success_criteria>

package/src/skills/create-agent-skills/templates/simple-skill.md ADDED Viewed

@@ -0,0 +1,33 @@
+---
+name: {{SKILL_NAME}}
+description: {{What it does}} Use when {{trigger conditions}}.
+---
+<objective>
+{{Clear statement of what this skill accomplishes}}
+</objective>
+<quick_start>
+{{Immediate actionable guidance - what Claude should do first}}
+</quick_start>
+<process>
+## Step 1: {{First action}}
+{{Instructions for step 1}}
+## Step 2: {{Second action}}
+{{Instructions for step 2}}
+## Step 3: {{Third action}}
+{{Instructions for step 3}}
+</process>
+<success_criteria>
+{{Skill name}} is complete when:
+- [ ] {{First success criterion}}
+- [ ] {{Second success criterion}}
+- [ ] {{Third success criterion}}
+</success_criteria>

package/src/skills/create-agent-skills/workflows/audit-skill.md ADDED Viewed

@@ -0,0 +1,3 @@
+# Workflow: Audit a Skill
+Read `references/audit.md` for the complete audit workflow.