cc-dev-template 0.1.52 → 0.1.53

package/package.json

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

package/src/skills/creating-agent-skills/references/create-step-2-design.md

@@ -19,6 +19,43 @@ There are two types. Pick one:
 
 **How to decide:** If the skill describes a process with distinct sequential phases, it is procedural. If it captures principles or knowledge applied whenever relevant, it is informational.
 
+## Determine Invocation Mode
+
+Ask the user: "Should Claude be able to auto-activate this skill, or is it user-invoked only (via `/skill-name`)?"
+
+**User-invoked only** — The user explicitly triggers with `/skill-name`. Use for:
+- Actions with side effects (deploy, commit, publish)
+- Workflows the user wants full control over
+- Tasks that should never run unexpectedly
+
+Configuration: `disable-model-invocation: true` + minimal description (just states what it does, no trigger phrases needed)
+
+**Agent-invocable** — Claude detects when to activate based on conversation. Use for:
+- Knowledge and guidance skills
+- Workflows triggered by natural language patterns
+- Skills where "just knowing when" is valuable
+
+Configuration: No special flag + rich description with trigger phrases
+
+## Determine Execution Context
+
+Ask the user: "Should this skill run inline (in the main conversation) or as a sub-agent (isolated context)?"
+
+**Inline** — Skill runs in the main conversation. The agent sees all prior context and can continue the conversation naturally after the skill completes. Use for:
+- Most skills
+- Skills that need conversation history
+- Skills where follow-up interaction is expected
+
+Configuration: No special setting needed
+
+**Sub-agent (fork)** — Skill runs in an isolated context. The sub-agent cannot see prior conversation and returns a single result. Use for:
+- Heavy research or exploration tasks
+- Parallel execution of independent work
+- Skills that should not pollute the main context
+- Long-running tasks that benefit from isolation
+
+Configuration: `context: fork` (optionally add `agent: Explore` or `agent: Plan` for specialized behavior)
+
 ## Design the Frontmatter
 
 Every skill has YAML frontmatter. Required and optional fields:
@@ -54,6 +91,10 @@ Every skill has YAML frontmatter. Required and optional fields:
 
 ## Craft the Description
 
+The description's purpose depends on the invocation mode:
+
+### For Agent-Invocable Skills
+
 The description determines when Claude activates the skill. This is the most important piece of metadata.
 
 Collect 5-10 trigger phrases from the user: "When you need this skill, what would you say to Claude?"
@@ -66,7 +107,14 @@ Combine into a description that:
 
 **Key insight:** If the description explains too much about WHAT the skill does, Claude believes it already knows enough and will not activate. Keep it about WHEN.
 
-**Context budget note:** Skill descriptions load at startup and share a character budget (default 15,000 chars across all skills). Keep descriptions tight — they cost tokens every session.
+### For User-Invoked Only Skills
+
+The description just needs to tell the user what the skill does. Keep it minimal:
+- One sentence stating the action
+- No trigger phrases needed (Claude will not use them)
+- Example: "Deploy the application to production"
+
+**Context budget note:** Skill descriptions load at startup and share a character budget (default 15,000 chars across all skills). Keep descriptions tight — they cost tokens every session. User-invoked skills with `disable-model-invocation: true` should have especially minimal descriptions since Claude does not need activation cues.
 
 ## Plan the File Layout
 
@@ -103,6 +151,8 @@ List out the steps. Each step becomes one markdown file in `references/`. For ea
 Present the design:
 - Name
 - Type (informational or procedural)
+- Invocation mode (agent-invocable or user-invoked only)
+- Execution context (inline or sub-agent)
 - Frontmatter configuration
 - Description text
 - File layout
@@ -110,4 +160,9 @@ Present the design:
 
 Ask: "Does this design look right?"
 
-Read `references/create-step-3-write.md` when the design is confirmed.
+## Next Step
+
+| Context | Action |
+|---------|--------|
+| Creating a new skill | Read `references/create-step-3-write.md` |
+| Fixing an existing skill (came from fix-step-1-diagnose) | Read `references/fix-step-2-apply.md` to apply the structural changes |

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

@@ -80,4 +80,31 @@ Present the diagnosis to the user:
 - 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.
+## Classify the Fix Type
+
+Based on your diagnosis, determine which type of fix is needed:
+
+**Surface fixes** — wording, style, dead ends, missing chain links, description tweaks:
+- Fixing second person to imperative
+- Adding positive framing
+- Removing meta-descriptions
+- Fixing broken file references
+- Small description improvements
+
+**Structural changes** — anything that changes the skill's architecture:
+- Converting between informational and procedural types
+- Adding or removing step files
+- Adding new workflow branches
+- Redesigning the file layout
+- Adding scripts/ or templates/ directories
+- Significantly rewriting the description and trigger phrases
+- Changing frontmatter configuration (allowed-tools, context, agent, etc.)
+
+Tell the user which type of fix is needed.
+
+## Next Step
+
+| Fix Type | Action |
+|----------|--------|
+| Surface fixes only | Read `references/fix-step-2-apply.md` |
+| Structural changes needed | Read `references/create-step-2-design.md` first to design the new structure, then read `references/fix-step-2-apply.md` to apply |

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

@@ -2,6 +2,17 @@
 
 Fix the issues identified in diagnosis. Plan the changes, confirm with the user, then apply.
 
+## If Coming From Design Step
+
+If you just read `create-step-2-design.md` for structural changes, you now have:
+- The skill type decision (informational vs procedural)
+- The frontmatter configuration
+- The crafted description with trigger phrases
+- The file layout plan
+- For procedural: the step breakdown
+
+Use that design as the blueprint for your changes. The writing principles below still apply to all content you write.
+
 ## Plan Changes First
 
 Before editing, state:
@@ -87,4 +98,6 @@ Does this justify its token cost? If Claude already knows it — remove it. If i
 
 Make all planned modifications now.
 
+For structural changes that involve writing new files (new step files, new SKILL.md sections, new scripts), reference `references/create-step-3-write.md` for the complete writing guidance — it covers size targets, step file structure, MCP tool references, and anti-patterns in more depth than the principles above.
+
 Read `references/fix-step-3-validate.md` when all fixes are applied.

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

@@ -1,5 +1,7 @@
 # Step 3: Validate and Test
 
+For structural changes, use the full review checklist from `references/create-step-4-review.md` — it covers additional criteria like size targets, frontmatter validation, and description quality that matter when you've changed the skill's architecture.
+
 ## Public Knowledge Audit
 
 Go through every changed file. Find each code block, CLI command, API call, and implementation detail.