cc-dev-template 0.1.72 → 0.1.74

package/package.json

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

package/src/scripts/statusline.js

@@ -21,6 +21,7 @@ const { homedir } = require('os');
 // Usage API cache
 const USAGE_CACHE_PATH = join(homedir(), '.claude', '.usage-cache.json');
 const USAGE_CACHE_TTL = 45000; // 45 seconds
+const USAGE_HISTORY_MAX = 20; // ~15 min of readings at 45s intervals
 
 // Background refresh mode: fetch usage data and write cache, then exit
 if (process.argv.includes('--refresh')) {
@@ -72,6 +73,50 @@ function getContextGreyscale(percentage) {
   return '\x1b[38;5;240m'; // Dark grey - safe
 }
 
+/**
+ * Compute burn rate (percent per minute) from usage history
+ * Returns null if insufficient data
+ */
+function getUsageBurnRate(history, key) {
+  if (!history || history.length < 2) return null;
+
+  const oldest = history[0];
+  const newest = history[history.length - 1];
+  const minutesElapsed = (newest.t - oldest.t) / 60000;
+
+  // Need at least 2 minutes of data for a stable reading
+  if (minutesElapsed < 2) return null;
+
+  const deltaUtilization = newest[key] - oldest[key];
+  return deltaUtilization / minutesElapsed;
+}
+
+/**
+ * Get color for usage bar based on current level and burn rate trend
+ * Returns red/yellow for danger, or greyscale for safe
+ */
+function getUsageColor(utilization, burnRate, windowType) {
+  const RED = '\x1b[38;5;196m';
+  const YELLOW = '\x1b[38;5;220m';
+
+  // Thresholds differ by window type
+  const redMinutes = windowType === '5h' ? 30 : 240;      // 30min / 4hr
+  const yellowMinutes = windowType === '5h' ? 90 : 720;    // 90min / 12hr
+
+  // Hard thresholds on current utilization
+  if (utilization >= 90) return RED;
+  if (utilization >= 75) return YELLOW;
+
+  // Trend-based: project time to hit 100%
+  if (burnRate && burnRate > 0) {
+    const minutesToLimit = (100 - utilization) / burnRate;
+    if (minutesToLimit <= redMinutes) return RED;
+    if (minutesToLimit <= yellowMinutes) return YELLOW;
+  }
+
+  return getContextGreyscale(utilization);
+}
+
 /**
  * Count files in a directory recursively
  */
@@ -279,9 +324,29 @@ function refreshUsageCache() {
     if (result.status === 0 && result.stdout) {
       const data = JSON.parse(result.stdout.trim());
       if (data.five_hour && data.seven_day) {
+        // Load existing history and append new reading
+        let history = [];
+        try {
+          const existing = JSON.parse(readFileSync(USAGE_CACHE_PATH, 'utf-8'));
+          if (Array.isArray(existing.history)) history = existing.history;
+        } catch {}
+
+        const now = Date.now();
+        history.push({
+          t: now,
+          five_hour: data.five_hour.utilization,
+          seven_day: data.seven_day.utilization,
+        });
+
+        // Keep only the last N readings
+        if (history.length > USAGE_HISTORY_MAX) {
+          history = history.slice(-USAGE_HISTORY_MAX);
+        }
+
         writeFileSync(USAGE_CACHE_PATH, JSON.stringify({
-          timestamp: Date.now(),
+          timestamp: now,
           data,
+          history,
         }));
       }
     }
@@ -295,12 +360,14 @@ function refreshUsageCache() {
  */
 function getUsageData() {
   let cacheData = null;
+  let cacheHistory = null;
   let cacheAge = Infinity;
 
   try {
     const raw = readFileSync(USAGE_CACHE_PATH, 'utf-8');
     const cache = JSON.parse(raw);
     cacheData = cache.data;
+    cacheHistory = cache.history || null;
     cacheAge = Date.now() - cache.timestamp;
   } catch {}
 
@@ -315,7 +382,7 @@ function getUsageData() {
     } catch {}
   }
 
-  return cacheData;
+  return { data: cacheData, history: cacheHistory };
 }
 
 /**
@@ -474,14 +541,19 @@ function main() {
 
     // Usage limits line (5-hour session + 7-day weekly)
     const usageLines = [];
-    const usageData = getUsageData();
-    if (usageData && usageData.five_hour && usageData.seven_day) {
-      const pct5h = Math.round(usageData.five_hour.utilization);
-      const pct7d = Math.round(usageData.seven_day.utilization);
+    const { data: usageApiData, history: usageHistory } = getUsageData();
+    if (usageApiData && usageApiData.five_hour && usageApiData.seven_day) {
+      const pct5h = Math.round(usageApiData.five_hour.utilization);
+      const pct7d = Math.round(usageApiData.seven_day.utilization);
       const bar5h = generateBar(pct5h, 12);
       const bar7d = generateBar(pct7d, 12);
-      const color5h = getContextGreyscale(pct5h);
-      const color7d = getContextGreyscale(pct7d);
+
+      // Compute burn rates from history for trend-based coloring
+      const rate5h = getUsageBurnRate(usageHistory, 'five_hour');
+      const rate7d = getUsageBurnRate(usageHistory, 'seven_day');
+      const color5h = getUsageColor(pct5h, rate5h, '5h');
+      const color7d = getUsageColor(pct7d, rate7d, '7d');
+
       const str5h = pct5h.toString().padStart(3, ' ');
       const str7d = pct7d.toString().padStart(3, ' ');
       const usageDisplay = `5HR: ${color5h}[${bar5h}]${str5h}%${DIM_GREY}  7D: ${color7d}[${bar7d}]${str7d}%${DIM_GREY}`;

package/src/skills/creating-agent-skills/references/create-step-1-understand.md

@@ -2,8 +2,17 @@
 
 The skill's quality depends entirely on understanding the domain. Start a conversation with the user.
 
+## Try It First
+
+Before building a skill, the best approach is to do the task in a live conversation first. Iterate until Claude succeeds at the task, then extract the winning approach into the skill. This grounds the skill in something that actually worked rather than theoretical instructions.
+
+Ask: "Have you already done this task successfully with Claude? Can you share that conversation or walk me through what worked?"
+
+If the user has a working conversation, use it as the primary source material. If not, consider running the workflow live together before designing the skill.
+
 ## What To Uncover
 
+- **2-3 concrete use cases** — specific scenarios where this skill would activate. What does the user want to accomplish?
 - **The task** they want to standardize — what do they do repeatedly that they want encoded?
 - **Domain knowledge** Claude does not naturally have — terminology, patterns, edge cases, gotchas
 - **Why certain approaches work** — not just what the steps are, but the reasoning behind them

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

@@ -8,6 +8,7 @@ Based on what you learned in the conversation, design the skill's structure befo
 - Prefer gerund form: `processing-pdfs`, `creating-reports`, `reviewing-code`
 - Must match the directory name
 - Max 64 characters
+- Reserved prefixes: names starting with "claude" or "anthropic" are not allowed
 
 ## Determine the Skill Type
 
@@ -79,6 +80,12 @@ Every skill has YAML frontmatter. Required and optional fields:
 | `context` | Set `fork` to run in an isolated sub-agent context |
 | `agent` | Sub-agent type when `context: fork` is set (`Explore`, `Plan`, `general-purpose`, or custom) |
 | `hooks` | Lifecycle hooks scoped to this skill |
+| `compatibility` | Environment requirements — intended product, required system packages, network access needs (1-500 chars) |
+
+### Security Restrictions
+
+- No XML angle brackets (`<` or `>`) in frontmatter — frontmatter appears in Claude's system prompt
+- Skill names starting with "claude" or "anthropic" are reserved
 
 ### String Substitutions Available in Skill Content
 
@@ -107,6 +114,8 @@ 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.
 
+**Negative triggers:** If the skill could over-trigger on related but wrong queries, add scope boundaries. Example: "Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration or visualization."
+
 ### For User-Invoked Only Skills
 
 The description just needs to tell the user what the skill does. Keep it minimal:
@@ -139,6 +148,8 @@ skill-name/
 
 **When to add `templates/`:** Boilerplate files that get copied or modified by the agent.
 
+**Do not add:** `README.md` inside the skill folder. All documentation goes in SKILL.md or `references/`.
+
 ## For Procedural Skills: Plan the Steps
 
 List out the steps. Each step becomes one markdown file in `references/`. For each step, determine:
@@ -158,6 +169,19 @@ Present the design:
 - File layout
 - For procedural: the step breakdown
 
+## Define Success Criteria
+
+Before writing, establish how the user will know the skill is working:
+
+- **Triggering**: Does it activate on relevant queries? (Aim for ~90% of intended triggers)
+- **Precision**: Does it stay silent on unrelated queries?
+- **Completeness**: Does the workflow complete without the user needing to redirect or clarify?
+- **Consistency**: Do repeated runs produce structurally similar, quality results?
+
+These are rough benchmarks, not precise thresholds. Ask the user: "What would a successful skill look like for you?"
+
+## Confirm With the User
+
 Ask: "Does this design look right?"
 
 ## Next Step

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

@@ -150,6 +150,15 @@ description: [third person, trigger phrases, WHEN not HOW]
 
 Keep it minimal. Only include context that is needed at EVERY activation.
 
+### Error Handling
+
+If the skill involves tool calls, external services, or operations that can fail, include error handling guidance:
+- Common failure modes and what to do about them
+- MCP connection failures: verify server is connected, check authentication, test independently
+- Validation failures: what to check, how to recover
+
+For critical validations, bundle a script rather than relying on language instructions. Code is deterministic; language interpretation is not.
+
 ### MCP Tool References
 
 When a skill uses MCP tools, use fully qualified names:

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

@@ -15,20 +15,44 @@ Copy the skill directory to the target location. Ensure all files are in place
 
 ## Test
 
-Guide the user through testing:
+Guide the user through structured testing:
+
+### 1. Triggering Tests
+
+Verify the skill loads at the right times.
+
+**Should trigger** — test 3-5 phrases that should activate the skill:
+- The obvious request (e.g., "help me plan this sprint")
+- A paraphrased version (e.g., "I need to set up sprint tasks")
+- A domain-specific variant (e.g., "create Linear tickets for Q4")
+
+**Should NOT trigger** — test 2-3 unrelated queries:
+- A clearly unrelated request
+- A request in a similar domain that a different skill should handle
+
+If the skill under-triggers: add more trigger phrases and keywords to the description.
+If the skill over-triggers: add negative scope boundaries or be more specific.
+
+### 2. Functional Tests
+
+Verify the skill produces correct output:
 
 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
+4. Run through the full workflow — does it complete without the user needing to redirect or clarify?
+5. For skills with tool calls: verify calls succeed and outputs are correct
 
-## If Testing Reveals Issues
+### 3. Iteration
 
-Iterate. The job is not done until the skill works.
+If testing reveals issues, iterate immediately:
 
-- Instructions wrong? Go back to the write step.
+- Instructions unclear or wrong? Go back to the write step.
 - Structure wrong? Go back to the design step.
 - Domain knowledge missing? Go back to the understand step.
+- Description under/over-triggers? Adjust the description and retest.
+
+The job is not done until the skill works.
 
 ## Completion
 

package/src/skills/creating-agent-skills/scripts/validate-skill.js

@@ -118,6 +118,12 @@ if (!frontmatter.valid) {
       addFinding('STRUCTURE', 'error',
         `Name exceeds 64 characters (${frontmatter.data.name.length})`);
     }
+
+    // Check reserved name prefixes
+    if (frontmatter.data.name.startsWith('claude') || frontmatter.data.name.startsWith('anthropic')) {
+      addFinding('STRUCTURE', 'error',
+        `Name "${frontmatter.data.name}" uses a reserved prefix ("claude" or "anthropic")`);
+    }
   }
 
   if (!frontmatter.data.description) {
@@ -153,6 +159,14 @@ if (!frontmatter.valid) {
         'Long description without trigger phrases may reduce activation reliability');
     }
   }
+
+  // Check for XML angle brackets in frontmatter
+  if (frontmatter.raw && /[<>]/.test(frontmatter.raw)) {
+    addFinding('STRUCTURE', 'error',
+      'Frontmatter contains XML angle brackets (< >) — these are forbidden as frontmatter appears in system prompt',
+      null,
+      'Remove all < and > characters from frontmatter values');
+  }
 }
 
 // Check 3: Second person violations
@@ -162,8 +176,7 @@ const secondPersonPatterns = [
   /\byou need\b/gi,
   /\byou might\b/gi,
   /\byou will\b/gi,
-  /\byou must\b/gi,
-  /\byour\b/gi
+  /\byou must\b/gi
 ];
 
 let secondPersonCount = 0;
@@ -229,26 +242,39 @@ if (negativeCount > 3) {
     'Use positive framing: "Don\'t do X" → "Do Y instead"');
 }
 
-// Check 5: Body size
+// Check 5: Forbidden files
+const readmePath = path.join(resolvedPath, 'README.md');
+if (fs.existsSync(readmePath)) {
+  addFinding('STRUCTURE', 'warning',
+    'Skill folder contains README.md — all documentation should be in SKILL.md or references/',
+    null,
+    'Move README.md content into SKILL.md or references/ and delete README.md');
+}
+
+// Check 6: Body size
 const wordCount = body.split(/\s+/).filter(w => w.length > 0).length;
 const lineCount = body.split('\n').length;
 
 if (wordCount > 5000) {
   addFinding('SIZE', 'error',
-    `SKILL.md body is ${wordCount} words - strongly exceeds 2,000 word recommendation`,
+    `SKILL.md body is ${wordCount} words - exceeds 5,000 word limit`,
     null,
     'Move detailed content to references/ directory');
-} else if (wordCount > 3500) {
+} else if (wordCount > 2000) {
   addFinding('SIZE', 'warning',
-    `SKILL.md body is ${wordCount} words - exceeds 2,000 word recommendation`,
+    `SKILL.md body is ${wordCount} words - consider moving content to references/`,
     null,
-    'Consider moving detailed content to references/ directory');
-} else if (wordCount > 2000) {
-  addFinding('SIZE', 'info',
-    `SKILL.md body is ${wordCount} words - at upper limit of recommendation`);
+    'Keep SKILL.md focused; move detailed content to references/ directory');
+}
+
+if (lineCount > 300) {
+  addFinding('SIZE', 'warning',
+    `SKILL.md body is ${lineCount} lines - exceeds 300 line target for informational skills (150 for routers)`,
+    null,
+    'Move content to references/ to stay within size targets');
 }
 
-// Check 6: Progressive disclosure
+// Check 7: Progressive disclosure
 const hasReferences = fs.existsSync(path.join(resolvedPath, 'references'));
 const hasScripts = fs.existsSync(path.join(resolvedPath, 'scripts'));
 
@@ -259,7 +285,7 @@ if (wordCount > 2000 && !hasReferences) {
     'Create references/ and move detailed content there');
 }
 
-// Check 7: Reference integrity
+// Check 8: Reference integrity
 const referencePaths = body.match(/`references\/[^`]+`|references\/[\w.-]+/g) || [];
 const scriptPaths = body.match(/`scripts\/[^`]+`|scripts\/[\w.-]+/g) || [];
 
@@ -283,7 +309,7 @@ for (const ref of scriptPaths) {
   }
 }
 
-// Check 8: Unreferenced resources
+// Check 9: Unreferenced resources
 if (hasReferences) {
   const refDir = path.join(resolvedPath, 'references');
   const refFiles = fs.readdirSync(refDir);

package/src/skills/creating-agent-skills/templates/router-skill.md

@@ -7,55 +7,10 @@ description: {{What it does}} Use when {{trigger conditions}}.
 
 ## What To Do Now
 
-**Ask the user:**
+Ask the user what they need.
 
-What would you like to do?
-1. {{First option}}
-2. {{Second option}}
-3. {{Third option}}
-
-**Wait for response before proceeding.**
-
-## Route to Workflow
-
-| Response | Action |
-|----------|--------|
-| 1, "{{keywords}}" | Read `references/{{first-workflow}}.md` |
-| 2, "{{keywords}}" | Read `references/{{second-workflow}}.md` |
-| 3, "{{keywords}}" | Read `references/{{third-workflow}}.md` |
-
-After reading the workflow, follow it exactly.
-
-## Essential Principles
-
-{{Principles that ALWAYS apply, regardless of which workflow runs}}
-
-### 1. {{First principle}}
-
-{{Explanation}}
-
-### 2. {{Second principle}}
-
-{{Explanation}}
-
-### 3. {{Third principle}}
-
-{{Explanation}}
-
-## Quick Reference
-
-{{Brief reference information always useful to have visible}}
-
-## Resources
-
-**References** (in `references/`):
-- {{reference-1.md}} - {{purpose}}
-- {{reference-2.md}} - {{purpose}}
-
-**Workflows** (in `references/`):
-
-| Workflow | Purpose |
-|----------|---------|
-| {{first-workflow}}.md | {{purpose}} |
-| {{second-workflow}}.md | {{purpose}} |
-| {{third-workflow}}.md | {{purpose}} |
+| Intent | Action |
+|--------|--------|
+| {{First option}} | Read `references/{{first-workflow}}.md` |
+| {{Second option}} | Read `references/{{second-workflow}}.md` |
+| {{Third option}} | Read `references/{{third-workflow}}.md` |

package/src/skills/creating-agent-skills/templates/simple-skill.md

@@ -22,13 +22,3 @@ description: {{What it does}} Use when {{trigger conditions}}.
 ### Step 3: {{Third action}}
 
 {{Instructions for step 3}}
-
-## Completion Checklist
-
-{{Skill name}} is complete when:
-
-```
-- [ ] {{First success criterion}}
-- [ ] {{Second success criterion}}
-- [ ] {{Third success criterion}}
-```