cc-dev-template 0.1.4 → 0.1.6

package/bin/install.js

@@ -2,11 +2,21 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const { execSync } = require('child_process');
 
+// Parse command line arguments
+const args = process.argv.slice(2);
+const isProjectLevel = args.includes('--project');
+
 const SRC_DIR = path.join(__dirname, '..', 'src');
-const CLAUDE_DIR = path.join(process.env.HOME, '.claude');
+const CLAUDE_DIR = isProjectLevel
+  ? path.join(process.cwd(), '.claude')
+  : path.join(os.homedir(), '.claude');
 
+const installMode = isProjectLevel ? 'project-level' : 'user-level';
+console.log(`\nCC Dev Template - ${installMode} installation`);
+console.log('='.repeat(50));
 console.log(`Installing to ${CLAUDE_DIR}...`);
 
 // Create directories
@@ -78,20 +88,6 @@ if (fs.existsSync(skillsDir)) {
   });
   console.log(`✓ ${skills.length} skills installed`);
 
-  // Copy skill-specific scripts to global scripts directory
-  const orchScriptsDir = path.join(skillsDir, 'orchestration', 'scripts');
-  if (fs.existsSync(orchScriptsDir)) {
-    const orchScripts = fs.readdirSync(orchScriptsDir).filter(f => f.endsWith('.js'));
-    orchScripts.forEach(file => {
-      fs.copyFileSync(
-        path.join(orchScriptsDir, file),
-        path.join(CLAUDE_DIR, 'scripts', file)
-      );
-    });
-    if (orchScripts.length) {
-      console.log(`✓ Orchestration skill scripts copied to scripts/`);
-    }
-  }
 } else {
   console.log('  No skills to install');
 }
@@ -160,6 +156,17 @@ Installed to:
   Scripts:  ${CLAUDE_DIR}/scripts/
   Skills:   ${CLAUDE_DIR}/skills/
   Settings: ${CLAUDE_DIR}/settings.json
+`);
 
-Restart Claude Code to pick up changes.
+if (isProjectLevel) {
+  console.log(`Project-level installation complete.
+You can commit .claude/ to version control to share with your team.
+Claude Code will use project-level settings with user-level as fallback.
 `);
+} else {
+  console.log(`User-level installation complete.
+These settings are available globally across all your projects.
+`);
+}
+
+console.log('Restart Claude Code to pick up changes.');

package/package.json

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

package/src/skills/create-agent-skills/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: create-agent-skills
+description: Expert guidance for creating, modifying, and auditing Claude Code skills. This skill should be used when the user asks to "create a skill", "build a new skill", "audit skills", "review my skills", "update a skill", "modify a skill", "improve a skill", or mentions skill development, SKILL.md files, or progressive disclosure.
+---
+
+# Create Agent Skills
+
+Expert guidance for building Claude Code skills correctly. Skills are prompts with progressive disclosure—they teach Claude how to perform specific tasks repeatedly and reliably.
+
+## Why Skills Exist
+
+Skills solve one problem: **context window efficiency through progressive disclosure**.
+
+Without skills, complex workflows require loading thousands of lines of instructions upfront. With skills:
+- **Level 1**: Metadata (~100 words) loads at startup for all skills
+- **Level 2**: SKILL.md body (1,500-2,000 words) loads only when triggered
+- **Level 3**: references/, scripts/, assets/ load only when needed
+
+This means Claude can have access to unlimited specialized knowledge without paying the context cost until actually needed.
+
+## What To Do Now
+
+Determine what the user wants to accomplish with skills.
+
+<step name="Understand Intent">
+Ask the user what they want to do:
+
+Use `AskUserQuestion` with these options:
+- **Create a new skill** - Build a skill from scratch through guided conversation
+- **Audit existing skills** - Review all skills for best practices compliance
+- **Modify a skill** - Update or improve an existing skill
+- **Something else** - Free-form request for other needs
+</step>
+
+<step name="Route to Workflow">
+Based on the user's choice:
+
+| Choice | Action |
+|--------|--------|
+| Create a new skill | Read `references/create.md` |
+| Audit existing skills | Read `references/audit.md` |
+| Modify a skill | Read `references/modify.md` |
+| Something else | Help them find the right workflow |
+
+Reading the workflow file is mandatory—it contains the detailed instructions for that workflow.
+</step>
+
+## Core Skill Principles (Quick Reference)
+
+Before routing, understand these fundamentals that apply to ALL skill work:
+
+### A Skill IS a Prompt
+SKILL.md is not documentation about the skill—it IS what Claude reads when the skill activates. Write it as instructions TO Claude, using imperative form.
+
+### Description = Discovery
+The frontmatter `description` field determines when Claude triggers the skill. Include:
+- Third-person phrasing: "This skill should be used when..."
+- Specific trigger phrases users would say
+- Max 1024 characters
+
+### Structure Matters
+```
+skill-name/
+├── SKILL.md           # Required: lean router (1,500-2,000 words max)
+├── references/        # Detailed docs loaded as needed
+├── scripts/           # Executable utilities (token-efficient)
+└── assets/            # Files used in output, never read into context
+```
+
+### Writing Style
+- **Imperative form**: "Parse the file", "Validate the input"
+- **Never second person**: Avoid phrases like "should parse" or "can validate" with pronouns
+- **Objective instructional tone**: Facts and directives, not suggestions
+
+For complete principles, each workflow will load `references/principles.md` as needed.
+
+## Skill Locations
+
+Skills can exist at two levels:
+
+| Level | Path | Scope |
+|-------|------|-------|
+| User | `~/.claude/skills/` | Available in all projects |
+| Project | `.claude/skills/` | Shared with team via git |
+
+The audit workflow discovers skills at both levels automatically.
+
+## Bundled Scripts
+
+This skill includes utility scripts for validation and discovery:
+
+- **`scripts/find-skills.js`** - Discovers all skills at user/project levels
+- **`scripts/validate-skill.js`** - Validates a skill against best practices
+
+Run scripts via: `node ~/.claude/skills/create-agent-skills/scripts/[script-name].js`

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

@@ -0,0 +1,334 @@
+# Audit Existing Skills
+
+This workflow discovers and reviews all installed skills against best practices. Use it to identify skills that need improvement and ensure consistency across skill libraries.
+
+## Purpose
+
+Systematically review skills to identify:
+- Structural issues (missing files, wrong format)
+- Description problems (vague, wrong person, missing triggers)
+- Writing style violations (second person, negative framing)
+- Progressive disclosure failures (oversized SKILL.md, unreferenced resources)
+- Missing or broken references
+
+**Success looks like:** A comprehensive report of all skills with specific, actionable findings for any that need improvement.
+
+## Before Starting
+
+Read `references/principles.md` if not already familiar with skill standards.
+
+## Workflow
+
+<steps>
+
+<step name="Discover All Skills">
+Find skills at both user and project levels.
+
+**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
+```
+
+Or manually scan:
+```bash
+# User-level
+ls -la ~/.claude/skills/*/SKILL.md 2>/dev/null
+
+# Project-level
+ls -la .claude/skills/*/SKILL.md 2>/dev/null
+
+# Source (dev-template)
+ls -la src/skills/*/SKILL.md 2>/dev/null
+```
+
+**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, perform these checks:
+
+### Check 1: 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:**
+```
+STRUCTURAL: [skill-name] - [specific issue]
+```
+
+### Check 2: Description Quality
+
+**Read the description and verify:**
+- [ ] Under 1024 characters
+- [ ] Uses third person ("This skill should be used when...")
+- [ ] Contains specific trigger phrases (quoted examples of what users say)
+- [ ] Explains WHEN to use, not just WHAT it does
+- [ ] Not overly detailed about implementation
+
+**Red flags:**
+- Starts with "Use this skill" (wrong person)
+- No quoted trigger phrases
+- Only describes functionality, not activation scenarios
+- Over 1024 characters
+
+**Record issues:**
+```
+DESCRIPTION: [skill-name] - [specific issue]
+```
+
+### Check 3: Writing Style
+
+**Scan SKILL.md body for:**
+
+**Second person violations:**
+- "you should"
+- "you can"
+- "you need"
+- "you might"
+- "you will"
+- "your"
+
+**Passive voice (less critical but note):**
+- "should be"
+- "can be"
+- "is done"
+
+**Negative framing:**
+- "don't"
+- "never"
+- "avoid"
+- "do not"
+
+**Record issues:**
+```
+STYLE: [skill-name] - Found [count] instances of second person ("you should", etc.)
+STYLE: [skill-name] - Found negative framing: "[example]"
+```
+
+### Check 4: Size Analysis
+
+**Measure:**
+- Word count of SKILL.md body (excluding frontmatter)
+- Line count of SKILL.md
+
+**Thresholds:**
+| Metric | Good | Warning | Problem |
+|--------|------|---------|---------|
+| Words | <2,000 | 2,000-3,500 | >3,500 |
+| Lines | <300 | 300-500 | >500 |
+
+**If oversized:**
+- Check if references/ directory exists
+- If no references/, skill needs restructuring
+
+**Record issues:**
+```
+SIZE: [skill-name] - SKILL.md is [X] words ([Y] lines) - consider moving content to references/
+```
+
+### Check 5: Progressive Disclosure
+
+**Check structure:**
+- Does skill have references/ directory?
+- Does skill have scripts/ directory?
+- Does SKILL.md reference these resources?
+
+**Verify references are used:**
+- For each file in references/, check if SKILL.md mentions it
+- For each file in scripts/, check if SKILL.md mentions it
+- Flag unreferenced resources
+
+**Record issues:**
+```
+DISCLOSURE: [skill-name] - references/patterns.md exists but is never referenced in SKILL.md
+DISCLOSURE: [skill-name] - Large SKILL.md with no references/ directory
+```
+
+### Check 6: Reference Integrity
+
+**For every path mentioned in SKILL.md:**
+- `references/*.md` files exist
+- `scripts/*.js` or `scripts/*.py` files exist
+- `assets/*` files exist
+
+**Record issues:**
+```
+BROKEN: [skill-name] - References `references/workflow.md` but file doesn't exist
+```
+</step>
+
+<step name="Generate Report">
+Compile findings into a structured report.
+
+**Report format:**
+
+```markdown
+# Skill Audit Report
+
+Generated: [timestamp]
+Skills audited: [count]
+Location(s): [user/project/source]
+
+## Summary
+
+| Status | Count |
+|--------|-------|
+| Passing | [X] |
+| Warnings | [Y] |
+| Failing | [Z] |
+
+## Skills Passing All Checks
+
+- skill-name-1
+- skill-name-2
+
+## Skills with Warnings
+
+### [skill-name]
+- SIZE: SKILL.md is 2,500 words - consider refactoring
+
+## Skills with Failures
+
+### [skill-name]
+- STRUCTURAL: Missing `description` in frontmatter
+- STYLE: Found 15 instances of second person
+- BROKEN: References `scripts/validate.py` but file missing
+
+## Recommendations
+
+[Prioritized list of what to fix first]
+```
+
+**Present the report to the user.**
+</step>
+
+<step name="Offer Fixes">
+After presenting the report, offer to fix issues.
+
+Use `AskUserQuestion`:
+- **Fix all auto-fixable issues** - Apply safe fixes automatically
+- **Fix specific skill** - Work on one skill at a time
+- **Just the report** - No fixes, user will handle manually
+- **Create modification tasks** - Add to todo list for later
+
+**Auto-fixable issues:**
+- Second person → imperative form conversion
+- Negative framing → positive framing conversion
+- Missing frontmatter fields (can prompt for values)
+
+**Manual-fix-required issues:**
+- Oversized SKILL.md (needs content decisions)
+- Missing referenced files (needs content creation)
+- Vague descriptions (needs user input on triggers)
+
+If user wants fixes, transition to `references/modify.md` for each skill that needs work.
+</step>
+
+</steps>
+
+## Audit Checklist (Quick Reference)
+
+For quick manual audits, use this checklist:
+
+### Must Pass
+- [ ] SKILL.md exists with valid YAML frontmatter
+- [ ] `name` and `description` fields present
+- [ ] `name` matches directory name (hyphen-case)
+- [ ] `description` under 1024 characters
+- [ ] `description` uses third person
+- [ ] `description` has trigger phrases
+- [ ] No second person in body
+- [ ] All referenced files exist
+
+### Should Pass
+- [ ] SKILL.md under 2,000 words
+- [ ] Uses imperative form throughout
+- [ ] Positive framing (no "don't", "never")
+- [ ] references/ used for heavy content
+- [ ] All resources in skill directory are referenced
+
+### Nice to Have
+- [ ] Examples included
+- [ ] Clear section structure
+- [ ] Scripts for deterministic operations
+
+## Common Audit Findings
+
+### Finding: Many Skills Use Second Person
+
+**Pattern:** "You should...", "You can...", "You need..."
+
+**Fix approach:**
+```
+Before: "You should parse the config file first."
+After:  "Parse the config file first."
+
+Before: "You can use grep to search."
+After:  "Use grep to search."
+
+Before: "If you need to validate, you should run the tests."
+After:  "To validate, run the tests."
+```
+
+### Finding: Descriptions Are Vague
+
+**Pattern:** "Helps with X" or "Provides Y guidance"
+
+**Fix approach:**
+1. Ask user what they say when they need this skill
+2. Collect 5-10 trigger phrases
+3. Rewrite in third person with phrases
+
+### Finding: SKILL.md Is Too Large
+
+**Pattern:** >3,000 words with no references/
+
+**Fix approach:**
+1. Identify logical sections
+2. Move detailed content to references/
+3. Keep routing and essential knowledge in SKILL.md
+4. Add explicit references: "For detailed patterns, read `references/patterns.md`"
+
+### Finding: Unreferenced Resources
+
+**Pattern:** Files exist in references/ or scripts/ but SKILL.md doesn't mention them
+
+**Fix approach:**
+1. Determine if resource is needed
+2. If needed, add reference in SKILL.md
+3. If not needed, consider removing
+
+## Output
+
+The audit produces:
+1. **Report** - Comprehensive findings for all audited skills
+2. **Recommendations** - Prioritized list of improvements
+3. **Optional fixes** - Automated corrections for simple issues