cc-dev-template 0.1.5 → 0.1.7

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.5",
+  "version": "0.1.7",
   "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,51 @@
+---
+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
+
+## What To Do Now
+
+<step name="Understand Intent">
+Ask what the user wants to do with skills.
+
+Use `AskUserQuestion`:
+- **Create a new skill** - Build a skill through guided conversation
+- **Audit existing skills** - Review skills for best practices compliance
+- **Modify a skill** - Update or improve an existing skill
+- **Something else** - Free-form request
+</step>
+
+<step name="Route to Workflow">
+Based on choice, read the appropriate workflow:
+
+| Choice | Action |
+|--------|--------|
+| Create | Read `references/create.md` |
+| Audit | Read `references/audit.md` |
+| Modify | Read `references/modify.md` |
+| Something else | Help find the right approach |
+</step>
+
+## Essential Knowledge
+
+**A skill IS a prompt.** When activated, Claude reads SKILL.md. It must contain instructions, not documentation about the skill.
+
+**Progressive disclosure.** SKILL.md should be lean (<150 lines). Heavy content goes in references/. This keeps context efficient.
+
+**The test:** After reading SKILL.md, would Claude know what to DO? If it only knows what the skill is about, it's written wrong.
+
+For complete principles, workflows load `references/principles.md` as needed.
+
+## Quick Reference
+
+**Skill locations:**
+| Level | Path |
+|-------|------|
+| User | `~/.claude/skills/` |
+| Project | `.claude/skills/` |
+
+**Bundled scripts:**
+- `scripts/find-skills.js` - Discover all installed skills
+- `scripts/validate-skill.js` - Validate a skill's structure

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

@@ -0,0 +1,429 @@
+# Audit Existing Skills
+
+This workflow discovers and reviews all installed skills against best practices. The most important check is whether the SKILL.md is written as a proper prompt, not as documentation.
+
+## Purpose
+
+Systematically review skills to identify:
+- **Fundamental prompt problems** - Is this written as instructions TO Claude or documentation ABOUT the skill?
+- Content that belongs in references, not SKILL.md
+- Structural issues (missing files, wrong format)
+- Description problems (vague, wrong person, missing triggers)
+- Writing style violations
+
+**Success looks like:** Actually reading each skill and evaluating whether it would work as a prompt. Surface fundamental problems, not just superficial style issues.
+
+## Before Starting
+
+Read `references/principles.md` to understand what makes a good skill.
+
+**Critical understanding:** A SKILL.md IS the prompt. When Claude activates a skill, it reads SKILL.md. If SKILL.md reads like documentation ("This skill does X", "Who this is for"), Claude won't know what to DO.
+
+## 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
+```
+
+**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, **READ THE ENTIRE SKILL.MD FILE** and perform these checks in order. The first check is the most important.
+
+---
+
+### CHECK 0: Is This Written as a Prompt? (CRITICAL)
+
+**This is the most important check.** Read the entire SKILL.md and evaluate:
+
+**Is it instructions TO Claude, or documentation ABOUT the skill?**
+
+A SKILL.md should tell Claude what to DO right now. It should NOT describe what the skill is, who it's for, or how it works abstractly.
+
+**Red flags that indicate documentation, not a prompt:**
+
+| Red Flag | Why It's Wrong |
+|----------|----------------|
+| "Who this is for: Developers..." | Meta-description. Claude doesn't need to know the audience. |
+| "Success looks like: Running X produces Y" | Meta-description. This describes outcomes, doesn't instruct. |
+| "This skill orchestrates..." | Describes what skill IS, not what to DO. |
+| "The purpose of this skill is..." | Documentation language, not instruction. |
+| Large inline schemas (YAML, JSON examples) | Should be in references/, loaded when needed. |
+| Explaining how phases work abstractly | Should just route to phase files with instructions. |
+
+**What a good SKILL.md looks like:**
+
+```markdown
+## What To Do Now
+
+<step name="Get Input">
+Ask the user which form to implement.
+</step>
+
+<step name="Check State">
+Look for existing workflow at `.claude/workflows/{formname}/workflow.yaml`
+
+If exists: Read it, determine current phase.
+If not: Initialize new workflow.
+</step>
+
+<step name="Route to Phase">
+Based on current phase, read the appropriate file:
+
+| Phase | File |
+|-------|------|
+| phase1 | `references/phase1.md` |
+| phase2 | `references/phase2.md` |
+</step>
+```
+
+**What a BAD SKILL.md looks like:**
+
+```markdown
+## Purpose
+
+This skill orchestrates the complete migration of Oracle Forms...
+
+**Who this is for**: Developers migrating Oracle Forms.
+
+**Success looks like**: Running /implement-form progresses through all phases.
+
+## Phase Overview
+
+Phase 1 does X, Phase 2 does Y...
+
+## YAML Schema
+
+```yaml
+# 50 lines of YAML schema inline
+```
+```
+
+**Evaluation questions:**
+
+1. If Claude reads this right now, does it know what to DO?
+2. Is there a clear "What To Do Now" section with concrete steps?
+3. Or does it just describe what the skill is and how it works?
+
+**Record severity:**
+- **CRITICAL** if SKILL.md reads like documentation
+- **CRITICAL** if large schemas/examples are inline instead of in references/
+- **CRITICAL** if no clear action instructions exist
+
+```
+PROMPT_QUALITY: [skill-name] - CRITICAL: Written as documentation, not instructions. Contains "Who this is for", "Success looks like" meta-descriptions.
+PROMPT_QUALITY: [skill-name] - CRITICAL: ~200 lines of YAML schemas inline. Move to references/.
+PROMPT_QUALITY: [skill-name] - CRITICAL: No "What To Do" section. Claude won't know what action to take.
+```
+
+---
+
+### CHECK 1: Content That Should Be in References
+
+**Read the SKILL.md and identify content that doesn't belong:**
+
+| Content Type | Should Be In | Why |
+|--------------|--------------|-----|
+| YAML/JSON schemas | `references/schemas.md` | Loaded only when needed |
+| Detailed phase explanations | `references/phaseN.md` | Progressive disclosure |
+| Examples >10 lines | `references/examples.md` | Keep SKILL.md lean |
+| API documentation | `references/api.md` | Not needed upfront |
+| Historical context | `references/background.md` | Not actionable |
+
+**Count lines of inline content that should be moved:**
+- Code blocks >20 lines
+- Tables >10 rows
+- Schema definitions
+- Detailed explanations of internals
+
+**Record issues:**
+```
+CONTENT: [skill-name] - ~150 lines of YAML schemas should be in references/
+CONTENT: [skill-name] - Phase explanations (lines 50-200) should be in separate phase files
+CONTENT: [skill-name] - "Key Design Principles" section is background, not instructions
+```
+
+---
+
+### CHECK 2: Router Pattern (for complex skills)
+
+**If the skill has multiple workflows or phases:**
+
+Does SKILL.md act as a lean router that:
+1. Asks/determines what to do
+2. Routes to the appropriate reference file
+3. Lets the reference file contain the detailed instructions
+
+**Good pattern:**
+```markdown
+<step name="Route to Phase">
+| currentPhase | Action |
+|--------------|--------|
+| phase1 | Read `references/phase1.md` |
+| phase2 | Read `references/phase2.md` |
+</step>
+```
+
+**Bad pattern:**
+```markdown
+## Phase 1: Scaffolding
+[100 lines of phase 1 instructions]
+
+## Phase 2: Discovery
+[100 lines of phase 2 instructions]
+
+## Phase 3: Analysis
+[100 lines of phase 3 instructions]
+```
+
+**Record issues:**
+```
+ROUTER: [skill-name] - Has 12 phases but all instructions inline. Should route to reference files.
+ROUTER: [skill-name] - references/ directory exists but SKILL.md doesn't route to it.
+```
+
+---
+
+### CHECK 3: 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:**
+```
+STRUCTURE: [skill-name] - [specific issue]
+```
+
+---
+
+### CHECK 4: Description Quality
+
+**Read the description and verify:**
+- [ ] Under 1024 characters
+- [ ] Uses third person ("This skill should be used when...")
+- [ ] Contains specific trigger phrases users would say
+- [ ] Explains WHEN to use, not just WHAT it does
+
+**Record issues:**
+```
+DESCRIPTION: [skill-name] - [specific issue]
+```
+
+---
+
+### CHECK 5: Writing Style
+
+**Scan for second person:**
+- "you should", "you can", "you need", "you might", "your"
+
+**Scan for negative framing:**
+- "don't", "never", "avoid", "do not"
+
+**Record issues:**
+```
+STYLE: [skill-name] - Found [count] instances of second person
+STYLE: [skill-name] - Negative framing: "[example]"
+```
+
+---
+
+### CHECK 6: Size Analysis
+
+**Measure:**
+- Word count of SKILL.md body
+- Line count
+
+**Thresholds:**
+| Metric | Good | Warning | Critical |
+|--------|------|---------|----------|
+| Words | <2,000 | 2,000-3,500 | >3,500 |
+| Lines | <300 | 300-500 | >500 |
+
+**Record issues:**
+```
+SIZE: [skill-name] - SKILL.md is [X] words ([Y] lines) - needs restructuring
+```
+
+---
+
+### CHECK 7: Reference Integrity
+
+**For every path mentioned in SKILL.md:**
+- Verify file exists
+- Flag broken references
+
+**For every file in references/:**
+- Check if SKILL.md mentions it
+- Flag orphaned files
+
+**Record issues:**
+```
+BROKEN: [skill-name] - References `references/phase1.md` but file doesn't exist
+ORPHAN: [skill-name] - `references/old-workflow.md` exists but isn't referenced
+```
+
+</step>
+
+<step name="Generate Report">
+Compile findings, prioritizing CRITICAL issues first.
+
+**Report format:**
+
+```markdown
+# Skill Audit Report
+
+Generated: [timestamp]
+Skills audited: [count]
+
+## Critical Issues (Fix Immediately)
+
+### [skill-name]
+- PROMPT_QUALITY: Written as documentation, not instructions
+  - Contains "Who this is for:", "Success looks like:" meta-descriptions
+  - No clear "What To Do" section
+  - ~200 lines of inline YAML schemas
+
+  **This skill will not work properly.** Claude won't know what action to take.
+
+## Warnings
+
+### [skill-name]
+- SIZE: 2,800 words - consider moving content to references/
+- STYLE: 3 instances of negative framing
+
+## Passing
+
+- skill-name-1
+- skill-name-2
+
+## Recommendations
+
+1. **[skill-name]**: Complete rewrite needed. Current version is documentation, not a prompt.
+2. **[other-skill]**: Move YAML schemas to references/schemas.md
+```
+
+**Present the report to the user.**
+</step>
+
+<step name="Offer Fixes">
+After presenting the report, offer to help fix issues.
+
+**For CRITICAL prompt quality issues:**
+Offer to help rewrite the skill properly. This requires:
+1. Understanding what the skill should DO
+2. Rewriting as instructions, not documentation
+3. Moving heavy content to references/
+4. Creating proper router pattern
+
+**For other issues:**
+- Second person → imperative conversion
+- Negative → positive framing
+- Content moves to references/
+
+Use `AskUserQuestion`:
+- **Help fix critical issues** - Work through rewriting problematic skills
+- **Fix style issues only** - Auto-fix second person, negative framing
+- **Just the report** - No fixes now
+
+If user wants to fix critical issues, transition to `references/modify.md`.
+</step>
+
+</steps>
+
+## Quick Audit Checklist
+
+### Critical (Must Fix)
+- [ ] SKILL.md is written as instructions, not documentation
+- [ ] No meta-descriptions ("Who this is for", "Success looks like")
+- [ ] Clear "What To Do" section with concrete steps
+- [ ] Heavy content (schemas, examples) in references/, not inline
+- [ ] Router pattern used for multi-phase skills
+
+### Important
+- [ ] Valid frontmatter with name and description
+- [ ] Description has trigger phrases
+- [ ] Under 2,000 words
+- [ ] All references exist
+
+### Style
+- [ ] No second person
+- [ ] Positive framing
+- [ ] Imperative form
+
+## Anti-Patterns to Catch
+
+### The Documentation Skill
+**Pattern:** Reads like a README explaining what the skill does.
+```markdown
+## Purpose
+This skill helps developers migrate forms...
+
+## Who This Is For
+Developers working on Oracle Forms migration.
+
+## How It Works
+The skill has 12 phases...
+```
+
+**Problem:** Claude reads this and thinks "interesting, but what should I DO?"
+
+**Fix:** Rewrite as instructions:
+```markdown
+## What To Do Now
+
+<step name="Get Form Name">
+Ask which form to implement.
+</step>
+
+<step name="Route to Current Phase">
+Read workflow.yaml, route to appropriate phase file.
+</step>
+```
+
+### The Kitchen Sink Skill
+**Pattern:** Everything inline, no progressive disclosure.
+
+**Problem:** 500+ lines, Claude gets lost in irrelevant details.
+
+**Fix:** Keep SKILL.md as router (<150 lines), move details to references/.
+
+### The Schema Dump
+**Pattern:** 100+ lines of YAML/JSON schemas inline.
+
+**Problem:** Schemas are reference material, not instructions.
+
+**Fix:** Move to `references/schemas.md`, reference when needed.

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

@@ -0,0 +1,129 @@
+# Create a New Skill
+
+Guide the user through building a skill via interactive conversation. Extract their domain knowledge, then produce a properly structured skill.
+
+## What To Do
+
+<steps>
+
+<step name="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>
+
+<step name="Determine Scope and Structure">
+Based on the conversation, decide:
+
+1. **Name**: What to call it (hyphen-case)
+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>
+
+<step name="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>
+
+<step name="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>
+
+<step name="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>
+
+<step name="Create and Validate">
+Write the files, then validate:
+
+```bash
+node ~/.claude/skills/create-agent-skills/scripts/validate-skill.js [skill-path]
+```
+
+Fix any issues found. The validator checks structure, but also 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>
+
+<step name="Test">
+Guide the user:
+1. Restart Claude Code
+2. Say one of the trigger phrases
+3. Verify the skill activates and behaves as expected
+
+If it doesn't work, iterate. The conversation isn't over until the skill works.
+</step>
+
+</steps>
+
+## 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.