cc-dev-template 0.1.48 → 0.1.49

package/src/skills/creating-agent-skills/references/fix-step-3-validate.md

@@ -0,0 +1,52 @@
+# Step 3: Validate and Test
+
+## Public Knowledge Audit
+
+Go through every changed file. Find each code block, CLI command, API call, and implementation detail.
+
+For each one, ask: **"Would a fresh Claude instance know how to do this without being told?"**
+
+- If yes: delete it. Replace with a high-level instruction.
+- If no: keep it — this is tribal knowledge and belongs in the skill.
+
+## Self-Review
+
+Re-read every changed file. For each one, verify:
+
+- Would Claude know what to DO after reading this?
+- Are the specific issues from diagnosis resolved?
+- Did the fixes introduce any new problems?
+- Is the writing style correct? (imperative, positive, direct, no meta-descriptions)
+- For procedural skills: does each step chain correctly to the next?
+
+## Run Validation
+
+```bash
+node ~/.claude/skills/creating-agent-skills/scripts/validate-skill.js [skill-path]
+```
+
+Handle results:
+- **Errors:** Fix each one, re-run, repeat until passing
+- **Warnings:** Evaluate and fix most of them
+- **Info:** Review — may be acceptable (e.g., step files chained from other steps rather than SKILL.md)
+
+## Test
+
+If the fix affected behavior:
+
+1. Reinstall if the skill is deployed (copy updated files to install location)
+2. Start a new Claude Code session
+3. If description changed: test trigger phrases for activation
+4. If instructions changed: invoke the skill and verify it behaves correctly
+5. If structure changed: verify all file references work
+
+## If Issues Remain
+
+Go back to `references/fix-step-2-apply.md` and address them.
+
+## Completion
+
+Summarize what was fixed:
+- Which files changed
+- What was wrong and how it was resolved
+- Confirm with the user that the skill now behaves as expected

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

@@ -1,121 +0,0 @@
-# Audit Existing Skills
-
-## Contents
-
-- [Audit Checklist](#audit-checklist)
-- [What To Do](#what-to-do)
-- [What Makes a Good Skill](#what-makes-a-good-skill)
-- [How to Audit](#how-to-audit)
-- [Red Flags](#red-flags)
-- [Report Format](#report-format)
-- [After the Audit](#after-the-audit)
-
----
-
-Read `references/principles.md` first.
-
-## Audit Checklist
-
-Copy and track progress:
-
-```
-- [ ] Discovered available skills
-- [ ] Selected skill(s) to audit
-- [ ] Read SKILL.md completely
-- [ ] Read all files in references/, workflows/, scripts/
-- [ ] Evaluated each file for actionability
-- [ ] Noted external dependencies
-- [ ] Checked structural basics
-- [ ] Compiled findings report
-- [ ] Presented to user
-```
-
-## What To Do
-
-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
-
-## What Makes a Good Skill
-
-**Actionability**: Every file tells Claude what to DO, not what the skill is ABOUT.
-
-**Progressive disclosure**: SKILL.md is lean (<150 lines). Heavy content lives in references/. Claude loads what it needs when it needs it.
-
-**Routing coherence**: Multi-phase skills route to reference files. Each file hands off clearly to the next step or completes the flow.
-
-**No dead ends**: At every point, Claude knows what to do next.
-
-## How to Audit
-
-### Step 1: Discover and Read Everything
-
-Use `scripts/find-skills.js` to list available skills. After selecting a skill to audit:
-
-- 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
-
-**You cannot audit a skill without reading all its files.**
-
-### Step 2: Evaluate Each File
-
-For each file, ask:
-
-- 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?
-
-### Step 3: Note External Dependencies
-
-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.
-
-### Step 4: Check Structural Basics
-
-- 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
-
-## Red Flags
-
-**Documentation language**: "This skill orchestrates...", "Who this is for:", "Success looks like:" - these describe, they don't instruct.
-
-**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.
-
-**Missing routing**: Multi-phase skill but all content inline instead of routing to reference files.
-
-## Report Format
-
-```markdown
-# Audit Report: [skill-name]
-
-## Summary
-- Files audited: [list all files read]
-- External dependencies: [list any sub-agents, commands, scripts referenced]
-
-## Findings
-
-### [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
-[What works well about this skill]
-```
-
-## After the Audit
-
-Present findings to the user. If issues were found, offer to help fix them. For significant rewrites (documentation to instructions), transition to `references/modify.md`.

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

@@ -1,157 +0,0 @@
-# Create a New Skill
-
-## Contents
-
-- [Creation Checklist](#creation-checklist)
-- [Step 1: Have a Conversation](#step-1-have-a-conversation)
-- [Step 2: Determine Scope and Structure](#step-2-determine-scope-and-structure)
-- [Step 3: Craft the Description](#step-3-craft-the-description)
-- [Step 4: Write the Skill](#step-4-write-the-skill)
-- [Step 5: Choose Install Location](#step-5-choose-install-location)
-- [Step 6: Validate](#step-6-validate-feedback-loop)
-- [Step 7: Test](#step-7-test)
-- [Key Principles](#key-principles)
-- [Quality Check](#quality-check)
-
----
-
-## Creation Checklist
-
-Copy and track progress:
-
-```
-- [ ] Had deep conversation about domain
-- [ ] Determined name, scope, structure
-- [ ] Crafted description with trigger phrases
-- [ ] Wrote skill as instructions (not docs)
-- [ ] Chose install location
-- [ ] Validated (loop until clean)
-- [ ] Tested activation
-```
-
-## Step 1: Have a Conversation
-
-Talk with the user to understand what they need. This is the most important step.
-
-**Goals of the conversation:**
-- Understand the task they want to standardize
-- Extract domain knowledge Claude doesn't naturally have
-- Learn terminology, patterns, edge cases, gotchas
-- Get concrete examples of the task done well
-
-**Good questions:**
-- "Walk me through how you do this today."
-- "What's the most important thing to get right?"
-- "What mistakes do people commonly make?"
-- "What would an expert know that a beginner wouldn't?"
-
-**Take time here.** The skill's quality depends entirely on understanding the domain deeply. Ask follow-up questions. Request examples. Understand WHY certain approaches work.
-
-This should feel like a conversation, not a form to fill out.
-
-## Step 2: Determine Scope and Structure
-
-Based on the conversation, decide:
-
-1. **Name**: What to call it (hyphen-case, prefer gerund form like `processing-pdfs`)
-2. **Scope**: One focused task or multiple related workflows?
-3. **Complexity**: Does it need references/? scripts/? Or just SKILL.md?
-
-**Principles:**
-- Focused is better than broad
-- If it has distinct workflows, use router pattern with references/
-- If it needs reliable code execution, add scripts/
-
-Confirm with user: "I'm thinking this should be called `[name]` and cover [scope]. Sound right?"
-
-## Step 3: Craft the Description
-
-The description determines when Claude activates the skill. This is critical.
-
-**Collect trigger phrases from user:**
-"When you need this skill, what would you say to Claude?"
-
-List 5-10 phrases they might use, then combine into a description that:
-- Uses third person ("This skill should be used when...")
-- Includes the actual trigger phrases
-- Stays under 1024 characters
-
-## Step 4: Write the Skill
-
-Create the skill files. Apply these principles:
-
-**The skill must be instructions, not documentation.**
-If Claude reads it, it should know what to DO, not just understand what the skill is about.
-
-**Use progressive disclosure.**
-SKILL.md should be lean (<150 lines for routers, <300 for simple skills). Heavy content goes in references/.
-
-**Apply prompting guidelines:**
-- Explain WHY, not just WHAT
-- Define what success looks like
-- Be clear and direct
-- Avoid micromanagement - give goals, not step-by-step unless truly needed
-
-**Writing style:**
-- Imperative form ("Parse the file", not "You should parse")
-- Positive framing ("Use X approach", not "Don't use Y")
-- No meta-descriptions ("Who this is for", "Success looks like" don't belong in SKILL.md)
-
-Read `references/principles.md` for the full guide on what makes a good skill.
-
-## Step 5: Choose Install Location
-
-Ask: "Should this be available everywhere (user level) or just this project (project level)?"
-
-| Level | Path |
-|-------|------|
-| User | `~/.claude/skills/[name]/` |
-| Project | `.claude/skills/[name]/` |
-
-## Step 6: Validate (Feedback Loop)
-
-Write the files, then validate:
-
-```bash
-node ~/.claude/skills/creating-agent-skills/scripts/validate-skill.js [skill-path]
-```
-
-**If errors found:**
-1. Fix the specific issue
-2. Run validation again
-3. Repeat until passing
-
-**Only proceed when validation passes.**
-
-Then manually verify:
-- Is this written as instructions, not documentation?
-- Would Claude know what to DO after reading this?
-- Is heavy content in references/, not inline?
-
-## Step 7: Test
-
-Guide the user:
-1. Restart Claude Code
-2. Say one of the trigger phrases or use `/skill-name` to invoke directly
-3. Verify the skill activates and behaves as expected
-
-If it doesn't work, iterate. The conversation isn't over until the skill works.
-
-## Key Principles
-
-**The conversation matters most.** A well-structured skill with shallow domain knowledge is worse than a rough skill with deep expertise captured.
-
-**Skills are prompts.** Every SKILL.md will be read by Claude. Write it as instructions, not as a README.
-
-**Trust Claude's intelligence.** Explain goals and principles. Don't micromanage with exact templates unless the task is genuinely complex or error-prone.
-
-**Progressive disclosure.** Load details only when needed. SKILL.md routes to references/, which contain the heavy content.
-
-## Quality Check
-
-Before finishing, verify:
-
-1. **Would Claude know what to DO?** Not just understand what the skill is about.
-2. **Is domain knowledge captured?** The user's expertise should be in the skill.
-3. **Is it lean?** Heavy content in references/, not SKILL.md.
-4. **Does the description have triggers?** Specific phrases the user would say.

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

@@ -1,131 +0,0 @@
-# Modify an Existing Skill
-
-## Contents
-
-- [Modification Checklist](#modification-checklist)
-- [Step 1: Find the Skill](#step-1-find-the-skill)
-- [Step 2: Read and Understand](#step-2-read-and-understand)
-- [Step 3: Understand What to Change](#step-3-understand-what-to-change)
-- [Step 4: Plan Changes](#step-4-plan-changes)
-- [Step 5: Apply Changes](#step-5-apply-changes)
-- [Step 6: Validate](#step-6-validate-feedback-loop)
-- [Step 7: Test](#step-7-test)
-- [Common Modifications](#common-modifications)
-
----
-
-## Modification Checklist
-
-Copy and track progress:
-
-```
-- [ ] Found the skill to modify
-- [ ] Read and understood current state
-- [ ] Clarified what to change
-- [ ] Planned specific changes
-- [ ] Applied changes
-- [ ] Validated (loop until clean)
-- [ ] Tested if behavior changed
-```
-
-## Step 1: Find the Skill
-
-Determine which skill to modify.
-
-If coming from audit, the path is known. Otherwise, ask the user or discover:
-
-```bash
-node ~/.claude/skills/creating-agent-skills/scripts/find-skills.js
-```
-
-Confirm the skill exists before proceeding.
-
-## Step 2: Read and Understand
-
-Read the entire skill - SKILL.md and all files in references/, scripts/, assets/.
-
-Summarize for the user:
-- Current structure
-- Line count
-- Any obvious issues (documentation-style writing, inline content that should be in references)
-
-## Step 3: Understand What to Change
-
-Ask what the user wants to change:
-- Fix issues from an audit?
-- Improve activation (better description/triggers)?
-- Add new capability?
-- Refactor structure?
-- Fix incorrect behavior?
-
-Get specific about what's wrong and what "fixed" looks like.
-
-## Step 4: Plan Changes
-
-Before editing, state what will change:
-- Which files
-- What specifically changes
-- Any new files needed
-
-Confirm with user before proceeding.
-
-## Step 5: Apply Changes
-
-Make the modifications. Key rules:
-
-**Keep it as instructions, not documentation.**
-If rewriting, ensure Claude would know what to DO after reading.
-
-**Maintain progressive disclosure.**
-If adding content, consider whether it belongs in references/ instead of SKILL.md.
-
-**Follow writing conventions.**
-Imperative form, positive framing, no second person.
-
-Read `references/principles.md` for full guidelines.
-
-## Step 6: Validate (Feedback Loop)
-
-Run validation:
-
-```bash
-node ~/.claude/skills/creating-agent-skills/scripts/validate-skill.js [skill-path]
-```
-
-**If errors found:**
-1. Fix the specific issue
-2. Run validation again
-3. Repeat until passing
-
-**Only proceed when validation passes.**
-
-Also manually verify:
-- Is this instructions, not documentation?
-- Would Claude know what to DO?
-- Is heavy content in references/?
-
-## Step 7: Test
-
-If the change affects behavior:
-1. Reinstall if needed
-2. Restart Claude Code
-3. Test that the skill works as expected
-
-## Common Modifications
-
-**Fix documentation-style writing:**
-Rewrite sections that describe the skill ("This skill does X") as instructions ("Do X").
-
-**Improve activation:**
-Collect trigger phrases from user, add to description in third person with quotes.
-
-**Move content to references:**
-Identify inline content (schemas, detailed explanations) that should be loaded on-demand. Create reference file, add pointer in SKILL.md.
-
-**Fix second person:**
-"You should parse" -> "Parse"
-"You can use" -> "Use"
-
-**Fix negative framing:**
-"Don't skip validation" -> "Always validate"
-"Never assume" -> "Verify explicitly"