cc-dev-template 0.1.46 → 0.1.49

package/src/skills/creating-agent-skills/references/create-step-3-write.md

@@ -0,0 +1,177 @@
+# Step 3: Write the Skill
+
+Write the skill files based on the design from step 2. Everything in this file applies while writing.
+
+## The Fundamental Rule
+
+A skill IS a prompt. When Claude reads SKILL.md, it must know what to DO — not what the skill is about.
+
+**The test:** After writing each file, ask: "If Claude reads this right now, does it know what action to take?" If it would understand what the skill is about but not know what to do — rewrite it.
+
+## Writing Style
+
+### Instructions, Not Documentation
+
+Write as instructions. Imperative form.
+
+| Wrong | Right |
+|-------|-------|
+| "This skill parses PDF files" | "Parse the PDF file" |
+| "You should validate the input" | "Validate the input" |
+| "The next step involves formatting" | "Format the output" |
+
+Never describe what the skill IS. Tell Claude what to DO.
+
+### No Meta-Descriptions
+
+Remove any of these — they describe, they do not instruct:
+
+- "Who this is for:" — Claude does not need audience info
+- "Success looks like:" — describe outcomes through instructions, not meta-sections
+- "The purpose is..." — documentation language
+- "This skill orchestrates..." — describes what the skill IS
+- "Overview" or "Introduction" sections — get to the action
+
+### Positive Framing
+
+Tell Claude what TO do, not what NOT to do. Negatives require extra processing and can prime the unwanted behavior.
+
+| Negative | Positive |
+|----------|----------|
+| "Don't hallucinate facts" | "Only use information from the 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 validation" | "Always validate before proceeding" |
+
+### Explain WHY, Not Just WHAT
+
+Trust Claude's intelligence. Provide goals and constraints rather than exhaustive implementation details.
+
+Provide:
+- The goal or purpose of the task
+- Why this matters (business context, use case)
+- Constraints that exist (technical, business)
+- What success looks like
+
+Let Claude handle:
+- Edge cases it can reason about
+- Best practices for the domain
+- Reasonable implementation choices
+
+Only give step-by-step instructions when the task genuinely requires precision or the domain knowledge is non-obvious.
+
+### Public Knowledge vs Tribal Knowledge
+
+This is critical. If the agent writing this skill knows how to do something, the agent executing it will know too. Both are Claude.
+
+**Public knowledge — state WHAT to do, not HOW:**
+- Standard CLI tools (git, npm, yt-dlp, ffmpeg, curl): "Use yt-dlp to search YouTube" — not the full command with flags
+- Common libraries and frameworks: "Parse the JSON response" — not the exact API call
+- Standard programming patterns: "Validate the input" — not a code block showing validation
+
+**Tribal knowledge — include the specifics:**
+- Custom internal CLI tools the project built
+- Project-specific conventions or configurations that are non-obvious
+- Workarounds for known bugs or quirks in the codebase
+- Domain-specific sequences that only an expert would know
+- Exact file paths, schemas, or formats unique to this project
+
+The test: if you removed the specific details, would a fresh Claude instance still know how to do it? If yes, remove the details. If no, keep them — that is the skill's value.
+
+### Be Clear and Direct
+
+No hedging. State exactly what to do.
+
+| Vague | Clear |
+|-------|-------|
+| "Maybe consider adding..." | "Add..." |
+| "It might be nice to have..." | "Include..." |
+| "You could potentially..." | "Use..." |
+
+### Challenge Every Line
+
+The context window is a shared resource. For every piece of content, ask: does this justify its token cost?
+
+- If Claude already knows it (common programming knowledge, obvious best practices) — remove it.
+- If it is not needed for the current step — it belongs in a different step file or not at all.
+- Three similar examples are better than ten. Pick the best ones.
+
+## Structural Rules
+
+### Size Targets
+
+| Type | SKILL.md Target |
+|------|-----------------|
+| Router (procedural) | Under 150 lines |
+| Informational | Under 300 lines |
+
+If SKILL.md exceeds these, move content to `references/`.
+
+### For Procedural Skills: Chained Steps
+
+Each step file covers ONE phase of the workflow. Structure each file:
+
+1. A clear header naming the step
+2. Immediate actionable instructions — what to do NOW
+3. A chain link at the bottom: "Read `references/[next-step].md`" with an optional condition
+
+**Critical rules:**
+- No table of contents across steps
+- No "this is step 3 of 5"
+- No overview of the full workflow
+- Each file is self-contained for what the agent needs RIGHT NOW
+- The agent discovers future steps only by reaching them
+
+### For Informational Skills
+
+Single SKILL.md file. Use sections and tables to organize knowledge. No chaining needed.
+
+Optionally add `references/` for depth that is not always needed — the SKILL.md would say "for more detail on X, read `references/x-details.md`".
+
+### SKILL.md Structure for Router Skills
+
+```
+---
+name: skill-name
+description: [third person, trigger phrases, WHEN not HOW]
+---
+
+# Skill Title
+
+## What To Do Now
+
+[Immediate action — ask a question, route to a workflow]
+
+| Choice | Action |
+|--------|--------|
+| Option A | Read `references/step-1-a.md` |
+| Option B | Read `references/step-1-b.md` |
+```
+
+Keep it minimal. Only include context that is needed at EVERY activation.
+
+### MCP Tool References
+
+When a skill uses MCP tools, use fully qualified names:
+```
+Use the BigQuery:bigquery_schema tool to retrieve table schemas.
+```
+Without the server prefix, Claude may fail to locate the tool.
+
+## Anti-Patterns
+
+**Option menus instead of defaults:** Provide a recommended default, not a menu of choices. "Use pdfplumber for text extraction" not "You can use pypdf, pdfplumber, PyMuPDF, or pdf2image."
+
+**Windows-style paths:** Always use forward slashes: `references/guide.md`, not `references\guide.md`.
+
+**Deeply nested indirection:** Sequential chaining is fine (step 1 → step 2 → step 3) because each step is self-contained. What to avoid is layers of indirection where you must read through multiple files to reach the actual instructions: SKILL.md → overview.md → details.md → actual-info.md.
+
+## Write the Files
+
+With these principles applied, write all the skill files now:
+
+1. SKILL.md (router or informational, depending on the design)
+2. For procedural: each step file in `references/`
+3. Any `scripts/` or `templates/` files if the design calls for them
+
+Read `references/create-step-4-review.md` when all files are written.

package/src/skills/creating-agent-skills/references/create-step-4-review.md

@@ -0,0 +1,63 @@
+# Step 4: Review
+
+Review every file you wrote before proceeding. Fix issues now — do not proceed with known problems.
+
+## Public Knowledge Audit
+
+Do this first. Go through every file in the skill and find each:
+- Code block (``` fenced blocks)
+- CLI command or flag sequence
+- API call or library usage example
+- Specific implementation detail
+
+For EACH one, ask: **"Would a fresh Claude instance — with no access to the user's original request — know how to do this?"**
+
+- If yes: **delete the code block or detail.** Replace with a high-level instruction. Example: replace `yt-dlp "ytsearch5:<query>" --print "%(title)s | %(channel)s | %(duration_string)s | %(webpage_url)s" --no-download` with "Use yt-dlp to search YouTube and display results."
+- If no: **keep it.** This is tribal knowledge — project-specific commands, internal tools, non-obvious configurations. This is the skill's value.
+
+The user's original request may have included specific commands and implementation details. That does not mean they belong in the skill. The user provided them for YOUR understanding. The skill is for a future Claude instance that already knows standard tools. Only encode what a fresh instance would NOT know.
+
+## Self-Review Checklist
+
+Go through each file and verify:
+
+### Actionability
+- After reading this file, would Claude know what action to take?
+- Is every section written as instructions, not documentation?
+- Are there any meta-descriptions? ("Who this is for", "Success looks like", "The purpose is...") Remove them.
+
+### Progressive Disclosure
+- For procedural skills: does each step file focus on ONE phase?
+- Does each step chain correctly to the next?
+- Is SKILL.md lean? Is heavy content in `references/`?
+- For informational skills: is it a single cohesive file without unnecessary splitting?
+
+### Writing Style
+- Imperative form throughout? ("Parse" not "You should parse")
+- Positive framing? ("Use X" not "Don't use Y")
+- No hedging? ("Add" not "Maybe consider adding")
+- Is every line worth its token cost? Remove what Claude already knows.
+
+### Structure
+- SKILL.md under size target? (150 lines for router, 300 for informational)
+- Valid YAML frontmatter with `name` and `description`?
+- Name matches the directory name?
+- Description uses third person with quoted trigger phrases?
+- All referenced files exist? (no broken links)
+
+## Run Validation
+
+```bash
+node ~/.claude/skills/creating-agent-skills/scripts/validate-skill.js [skill-path]
+```
+
+Handle results:
+- **Errors:** Fix each one, re-run validation, repeat until passing
+- **Warnings:** Evaluate each — most should be fixed
+- **Info:** Review but these may be acceptable (e.g., step files referenced from other steps rather than SKILL.md)
+
+Only proceed when validation passes and self-review is clean.
+
+If you found and fixed issues, re-run both the self-review and validation to confirm.
+
+Read `references/create-step-5-install.md` when review passes with no remaining issues.

package/src/skills/creating-agent-skills/references/create-step-5-install.md

@@ -0,0 +1,39 @@
+# Step 5: Install and Test
+
+## Choose Install Location
+
+Ask the user where to install:
+
+| Level | Path | When to Use |
+|-------|------|-------------|
+| User | `~/.claude/skills/[name]/` | Available across all projects |
+| Project | `.claude/skills/[name]/` | This project only |
+
+## Install
+
+Copy the skill directory to the target location. Ensure all files are in place — SKILL.md, `references/`, `scripts/`, `templates/` as applicable.
+
+## Test
+
+Guide the user through testing:
+
+1. Start a new Claude Code session (or restart the current one)
+2. Test explicit invocation: type `/skill-name`
+3. Test autonomous activation: say one of the trigger phrases from the description
+4. Verify the skill activates and behaves as expected
+
+## If Testing Reveals Issues
+
+Iterate. The job is not done until the skill works.
+
+- Instructions wrong? Go back to the write step.
+- Structure wrong? Go back to the design step.
+- Domain knowledge missing? Go back to the understand step.
+
+## Completion
+
+Summarize what was created:
+- Skill name
+- Install location
+- Trigger phrases
+- File structure (list all files)

package/src/skills/creating-agent-skills/references/fix-step-1-diagnose.md

@@ -0,0 +1,83 @@
+# Step 1: Diagnose
+
+Find the skill, read everything, and understand what is wrong.
+
+## Find the Skill
+
+If the user named a specific skill, locate it. Otherwise, discover available skills:
+
+```bash
+node ~/.claude/skills/creating-agent-skills/scripts/find-skills.js
+```
+
+Ask which skill to fix.
+
+## Read Everything
+
+Read the entire skill — every file:
+- SKILL.md
+- Every file in `references/`
+- Every file in `scripts/`
+- Every file in `templates/` or `assets/`
+
+Trace the execution path: if SKILL.md says "read `references/step-1.md`", read that file and follow its chain.
+
+Cannot diagnose a skill without reading all its files.
+
+## Understand What Is Wrong
+
+Ask the user:
+- "What is the skill supposed to do?"
+- "What does it actually do instead?"
+- "Can you show me an example of it failing or behaving incorrectly?"
+
+Get specific about expected behavior versus actual behavior.
+
+## Diagnose Against Principles
+
+Evaluate each file against these criteria:
+
+### Actionability
+- After reading this file, would Claude know what to DO?
+- Or does it just describe what the skill is about?
+- Any dead ends where Claude would not know what to do next?
+
+### Progressive Disclosure
+- Is SKILL.md lean (under 150 lines for routers, under 300 for informational)?
+- Is heavy content in `references/`, not inline?
+- For procedural skills: is each phase in its own step file, chained to the next?
+- Or is everything crammed into one file?
+
+### Routing and Chaining
+- For multi-step skills: does each file hand off clearly to the next?
+- Are there dead ends with no next action?
+- Is the chain condition clear (when to move on)?
+
+### Writing Style
+- Second person language? ("You should..." — should be imperative: "Parse...")
+- Negative framing? ("Don't skip..." — should be positive: "Always validate...")
+- Meta-descriptions? ("Who this is for", "Success looks like", "The purpose is...")
+- Hedging? ("Maybe consider..." — should be direct: "Add...")
+- Public knowledge spelled out? (exact CLI flags, standard API calls that Claude already knows — should state WHAT to do, not HOW, unless it is tribal/project-specific knowledge)
+
+### Description Quality
+- Third person? ("This skill should be used when...")
+- Quoted trigger phrases?
+- Focuses on WHEN to use, not HOW it works?
+- Under 1024 characters?
+
+### Structural
+- Valid YAML frontmatter with `name` and `description`?
+- Name matches directory name?
+- All referenced files exist?
+- Any unreferenced files in `references/` that should be connected?
+
+## Summarize Findings
+
+Present the diagnosis to the user:
+- List each issue found
+- Which file it is in
+- What principle it violates
+- What the fix would look like
+
+Read `references/fix-step-2-apply.md` when diagnosis is complete and findings are summarized.

package/src/skills/creating-agent-skills/references/fix-step-2-apply.md

@@ -0,0 +1,90 @@
+# Step 2: Apply Fixes
+
+Fix the issues identified in diagnosis. Plan the changes, confirm with the user, then apply.
+
+## Plan Changes First
+
+Before editing, state:
+- Which files will change and what specifically changes
+- Any new files needed (e.g., splitting a monolithic file into step files)
+- Any files to delete
+
+Confirm the plan with the user before making changes.
+
+## Writing Principles
+
+Apply these while making every change:
+
+### Instructions, Not Documentation
+
+Write as instructions. Imperative form.
+
+| Wrong | Right |
+|-------|-------|
+| "This skill parses PDF files" | "Parse the PDF file" |
+| "You should validate the input" | "Validate the input" |
+| "The next step involves formatting" | "Format the output" |
+
+### No Meta-Descriptions
+
+Remove any of these:
+- "Who this is for:" — Claude does not need audience info
+- "Success looks like:" — describe outcomes through instructions
+- "The purpose is..." — documentation language
+- "This skill orchestrates..." — describes what the skill IS
+- "Overview" or "Introduction" sections — get to the action
+
+### Positive Framing
+
+| Negative | Positive |
+|----------|----------|
+| "Don't hallucinate facts" | "Only use information from the provided documents" |
+| "Don't skip validation" | "Always validate before proceeding" |
+| "Avoid long paragraphs" | "Keep paragraphs to 3-4 sentences" |
+
+### Explain WHY, Not Just WHAT
+
+Provide goals and constraints. Trust Claude's intelligence. Only give step-by-step when the domain genuinely requires precision.
+
+### Public Knowledge vs Tribal Knowledge
+
+If the agent writing this skill knows how to do something, the agent executing it will know too. Both are Claude.
+
+- **Public knowledge** (standard CLI tools, common libraries, standard patterns): state WHAT to do, not HOW. "Use yt-dlp to search YouTube" — not the full command with flags.
+- **Tribal knowledge** (custom internal tools, project-specific conventions, workarounds, non-obvious domain sequences): include the specifics. That is the skill's value.
+
+The test: if you removed the specific details, would a fresh Claude instance still know how to do it? If yes, remove them.
+
+### Be Clear and Direct
+
+No hedging. "Add..." not "Maybe consider adding..."
+
+### Challenge Every Line
+
+Does this justify its token cost? If Claude already knows it — remove it. If it is not needed for the current step — move or remove it.
+
+**The test:** After rewriting each file, ask: "If Claude reads this right now, does it know what action to take?"
+
+## Common Fix Patterns
+
+**Documentation to instructions:** Rewrite "This skill does X" as "Do X".
+
+**Add trigger phrases:** Collect phrases from user, add to description in third person with quotes.
+
+**Move content to references:** Identify inline content that should be loaded on-demand. Create reference files, add pointers.
+
+**Fix second person:** "You should parse" becomes "Parse". "You can use" becomes "Use".
+
+**Fix negative framing:** "Don't skip validation" becomes "Always validate". "Never assume" becomes "Verify explicitly".
+
+**Fix progressive disclosure:** Split a monolithic SKILL.md into a lean router + step files in `references/`. Each step file covers one phase and chains to the next.
+
+**Fix dead ends:** Ensure every file either chains to the next step or completes the flow with a clear ending.
+
+**Fix description:** Rewrite to third person, add quoted trigger phrases, focus on WHEN not HOW.
+
+## Apply the Changes
+
+Make all planned modifications now.
+
+Read `references/fix-step-3-validate.md` when all fixes are applied.

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/hooks/bash-precheck-hook.json

@@ -1,15 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "$HOME/.claude/hooks/bash-precheck.sh"
-          }
-        ]
-      }
-    ]
-  }
-}

package/src/hooks/bash-precheck.sh

@@ -1,117 +0,0 @@
-#!/bin/bash
-# bash-precheck.sh - PreToolUse hook to wrap Bash commands with output limiting
-#
-# Intercepts Bash commands before execution and wraps them to:
-# 1. Capture output to temp file
-# 2. If output exceeds threshold, save and return truncated version
-#
-# This ACTUALLY prevents large outputs from consuming context.
-# Compatible with bash and zsh on macOS and Linux.
-
-set -e
-
-# Configuration
-MAX_CHARS=${BASH_OVERFLOW_MAX_CHARS:-20000}
-OVERFLOW_DIR="${HOME}/.claude/bash-overflow"
-
-# Read hook input from stdin
-input=$(cat)
-
-# Parse tool name and command
-tool_name=$(echo "$input" | jq -r '.tool_name // empty')
-
-# Only process Bash tool
-if [[ "$tool_name" != "Bash" ]]; then
-    exit 0
-fi
-
-# Get the original command
-original_cmd=$(echo "$input" | jq -r '.tool_input.command // empty')
-
-# Skip if empty
-if [[ -z "$original_cmd" ]]; then
-    exit 0
-fi
-
-# Skip commands that are already piped to head/tail or are simple commands
-if [[ "$original_cmd" =~ \|[[:space:]]*(head|tail|wc|grep.*-c) ]]; then
-    exit 0
-fi
-
-# Skip very short commands (likely simple operations)
-if [[ ${#original_cmd} -lt 10 ]]; then
-    exit 0
-fi
-
-# Create overflow directory
-mkdir -p "$OVERFLOW_DIR"
-
-# Generate unique filename
-timestamp=$(date +%Y%m%d_%H%M%S)
-rand_suffix=$RANDOM
-overflow_file="$OVERFLOW_DIR/bash_output_${timestamp}_${rand_suffix}.txt"
-temp_file="/tmp/claude_bash_${timestamp}_${rand_suffix}.tmp"
-
-# Escape the original command for embedding in the wrapper
-# Use base64 to safely embed arbitrary commands
-original_cmd_b64=$(echo "$original_cmd" | base64)
-
-# Create wrapper that uses temp file approach (more portable)
-read -r -d '' wrapped_cmd << 'WRAPPER_EOF' || true
-__cmd_b64="BASE64_CMD_HERE"
-__cmd=$(echo "$__cmd_b64" | base64 -d)
-__tmpfile="TEMP_FILE_HERE"
-__overflow="OVERFLOW_FILE_HERE"
-__max=MAX_CHARS_HERE
-
-# Run command and capture to temp file
-eval "$__cmd" > "$__tmpfile" 2>&1
-__exit_code=$?
-
-# Check size
-__size=$(wc -c < "$__tmpfile" | tr -d ' ')
-
-if [ "$__size" -gt "$__max" ]; then
-    # Save full output
-    cp "$__tmpfile" "$__overflow"
-    __lines=$(wc -l < "$__tmpfile" | tr -d ' ')
-    __tokens=$((__size / 4))
-
-    echo "=== OUTPUT TRUNCATED (${__lines} lines, ~${__tokens} tokens) ==="
-    echo ""
-    echo "--- First 5 lines ---"
-    head -n 5 "$__tmpfile"
-    echo ""
-    echo "--- Last 5 lines ---"
-    tail -n 5 "$__tmpfile"
-    echo ""
-    echo "=== Full output saved to: $__overflow ==="
-    echo "Use Grep(pattern, path) or Read(file_path, offset, limit) to explore"
-else
-    cat "$__tmpfile"
-fi
-
-rm -f "$__tmpfile"
-exit $__exit_code
-WRAPPER_EOF
-
-# Substitute placeholders
-wrapped_cmd="${wrapped_cmd//BASE64_CMD_HERE/$original_cmd_b64}"
-wrapped_cmd="${wrapped_cmd//TEMP_FILE_HERE/$temp_file}"
-wrapped_cmd="${wrapped_cmd//OVERFLOW_FILE_HERE/$overflow_file}"
-wrapped_cmd="${wrapped_cmd//MAX_CHARS_HERE/$MAX_CHARS}"
-
-# Return the modified command
-cat << EOF
-{
-  "hookSpecificOutput": {
-    "hookEventName": "PreToolUse",
-    "permissionDecision": "allow",
-    "updatedInput": {
-      "command": $(echo "$wrapped_cmd" | jq -Rs .)
-    }
-  }
-}
-EOF
-
-exit 0