cc-dev-template 0.1.6 → 0.1.7

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

@@ -1,377 +1,104 @@
 # Modify an Existing Skill
 
-This workflow guides improvements to existing skills. Use it to fix issues found during audits, add new capabilities, or refine skill behavior based on usage experience.
+Fix issues, add capabilities, or refine behavior of an existing skill.
 
-## Purpose
-
-Improve existing skills while maintaining:
-- Structural integrity (valid frontmatter, correct paths)
-- Writing conventions (imperative form, positive framing)
-- Progressive disclosure (lean SKILL.md, heavy content in references/)
-- Activation reliability (good description with triggers)
-
-**Success looks like:** The skill works better after modification, passes all validation checks, and the user's specific concerns are addressed.
-
-## Before Starting
-
-Read `references/principles.md` if not already familiar with skill standards.
-
-## Workflow
+## What To Do
 
 <steps>
 
-<step name="Identify the Skill">
+<step name="Find the Skill">
 Determine which skill to modify.
 
-**If coming from audit:**
-The skill path is already known. Proceed to next step.
-
-**If user request:**
-Ask which skill they want to modify.
-
-Use `AskUserQuestion` with discovered skills as options, or ask for the skill name/path directly.
-
-**Find the skill:**
+If coming from audit, the path is known. Otherwise, ask the user or discover:
 ```bash
-# Check user level
-ls ~/.claude/skills/[name]/SKILL.md
-
-# Check project level
-ls .claude/skills/[name]/SKILL.md
-
-# Check source (dev-template)
-ls src/skills/[name]/SKILL.md
+node ~/.claude/skills/create-agent-skills/scripts/find-skills.js
 ```
 
 Confirm the skill exists before proceeding.
 </step>
 
-<step name="Understand Current State">
-Read and analyze the existing skill.
-
-**Read all skill files:**
-1. SKILL.md (required)
-2. All files in references/ (if exists)
-3. All files in scripts/ (if exists)
-4. List files in assets/ (if exists)
-
-**Analyze:**
-- Current frontmatter (name, description)
-- Overall structure and organization
-- Word count and complexity
-- Writing style compliance
-- Resource utilization
+<step name="Read and Understand">
+Read the entire skill - SKILL.md and all files in references/, scripts/, assets/.
 
-**Present summary to user:**
-```
-Current state of [skill-name]:
-- Location: [path]
-- Description: [first 100 chars]...
-- SKILL.md size: [X] words
-- References: [list or "none"]
-- Scripts: [list or "none"]
-- Issues found: [list or "none"]
-```
+Summarize for the user:
+- Current structure
+- Word count
+- Any obvious issues (documentation-style writing, inline content that should be in references)
 </step>
 
-<step name="Understand Desired Changes">
-Discuss what the user wants to change.
-
-**Common modification types:**
+<step name="Understand What to Change">
+Ask what the user wants to change:
+- Fix issues from an audit?
+- Improve activation (better description/triggers)?
+- Add new capability?
+- Refactor structure?
+- Fix incorrect behavior?
 
-| Type | Description |
-|------|-------------|
-| **Fix issues** | Address audit findings (style, size, structure) |
-| **Improve activation** | Better description, more trigger phrases |
-| **Add capability** | New workflow, additional functionality |
-| **Refactor structure** | Move content to references/, add scripts |
-| **Update content** | Revise instructions based on usage experience |
-| **Fix bugs** | Skill doesn't behave as expected |
-
-**Ask the user:**
-- "What's not working well with this skill?"
-- "What would you like it to do differently?"
-- "Are there specific issues from an audit to address?"
-
-**For audit-driven modifications:**
-Reference the specific findings and address each one.
+Get specific about what's wrong and what "fixed" looks like.
 </step>
 
-<step name="Plan the Changes">
-Before making changes, create a clear plan.
-
-**For each change, identify:**
-1. What file(s) need modification
-2. What specifically changes
-3. Whether new files are needed
-4. Whether files should be deleted or moved
-
-**Present plan to user:**
-```
-Proposed changes to [skill-name]:
-
-1. SKILL.md
-   - Update description to include trigger phrases
-   - Convert 12 instances of "you should" to imperative form
-   - Move "Advanced Patterns" section to references/
-
-2. New file: references/patterns.md
-   - Contains moved content from SKILL.md
-   - ~800 words
-
-3. No changes to: scripts/validate.py
+<step name="Plan Changes">
+Before editing, state what will change:
+- Which files
+- What specifically changes
+- Any new files needed
 
-Proceed with these changes?
-```
-
-Wait for user confirmation before making changes.
+Confirm with user before proceeding.
 </step>
 
 <step name="Apply Changes">
-Make the planned modifications.
-
-**Follow these rules:**
+Make the modifications. Key rules:
 
-### Preserve Valid Content
-Keep working content intact. Only change what needs changing.
+**Keep it as instructions, not documentation.**
+If rewriting, ensure Claude would know what to DO after reading.
 
-### Maintain Conventions
-All changes must follow skill conventions:
-- Imperative form
-- Positive framing
-- Third-person descriptions
-- Proper file references
+**Maintain progressive disclosure.**
+If adding content, consider whether it belongs in references/ instead of SKILL.md.
 
-### Update References
-If moving content:
-1. Create new reference file with moved content
-2. Update SKILL.md to reference the new file
-3. Verify the reference path is correct
-
-### Keep Backups (Optional)
-For significant changes, consider:
-```bash
-cp SKILL.md SKILL.md.backup
-```
+**Follow writing conventions.**
+Imperative form, positive framing, no second person.
 
-**Apply changes in order:**
-1. Structural changes first (new directories, files)
-2. Content moves second
-3. Content edits third
-4. Deletions last
+Read `references/principles.md` for full guidelines.
 </step>
 
-<step name="Validate Changes">
-After modifications, verify the skill is correct.
-
-**Run validation:**
+<step name="Validate">
+Run validation:
 ```bash
 node ~/.claude/skills/create-agent-skills/scripts/validate-skill.js [skill-path]
 ```
 
-**Manual checks:**
-- [ ] SKILL.md still has valid frontmatter
-- [ ] All references point to existing files
-- [ ] No broken paths
-- [ ] Word count is acceptable
-- [ ] Writing style is correct
+Also manually verify:
+- Is this instructions, not documentation?
+- Would Claude know what to DO?
+- Is heavy content in references/?
 
-**If validation fails:**
-Fix issues before proceeding. Don't leave skill in broken state.
+Fix any issues before finishing.
 </step>
 
-<step name="Test the Skill">
-Verify the skill works as expected.
-
-**For activation changes:**
-1. Restart Claude Code
-2. Test trigger phrases
-3. Verify skill activates
-
-**For content changes:**
-1. Activate the skill
-2. Walk through the modified workflow
-3. Verify behavior matches expectations
-
-**Ask user to test:**
-"Please restart Claude Code and try using the skill. Let me know if it behaves as expected."
-</step>
-
-<step name="Document Changes">
-Record what was changed for future reference.
-
-**If skill has version in metadata:**
-```yaml
-metadata:
-  version: 1.0.0 → 1.1.0
-```
-
-**Summarize changes:**
-```
-Changes made to [skill-name]:
-- Fixed 12 second-person violations
-- Added 5 trigger phrases to description
-- Moved patterns section to references/patterns.md
-- Reduced SKILL.md from 3,200 to 1,800 words
-```
+<step name="Test">
+If the change affects behavior:
+1. Reinstall if needed
+2. Restart Claude Code
+3. Test that the skill works as expected
 </step>
 
 </steps>
 
 ## Common Modifications
 
-### Fix Second Person
-
-**Find instances:**
-```
-Search for: "you should", "you can", "you need", "you might", "you will", "your"
-```
-
-**Convert to imperative:**
-
-| Before | After |
-|--------|-------|
-| You should parse the file | Parse the file |
-| You can use grep | Use grep |
-| If you need validation | For validation |
-| You might want to check | Consider checking |
-| Your configuration | The configuration |
-
-### Improve Description
-
-**Current (bad):**
-```yaml
-description: Helps with API development.
-```
-
-**Improved (good):**
-```yaml
-description: This skill should be used when the user asks to "create an API endpoint", "add a REST route", "build an API", or mentions API design, endpoint creation, or REST patterns. Provides guidance for building RESTful APIs with proper error handling and validation.
-```
-
-**Process:**
-1. Ask user: "What do you say when you need this skill?"
-2. Collect 5-10 phrases
-3. Combine with capability summary
-4. Keep under 1024 characters
-
-### Restructure for Size
-
-**Current (too large):**
-```
-skill/
-└── SKILL.md (4,000 words)
-```
-
-**Restructured:**
-```
-skill/
-├── SKILL.md (1,500 words - router + essentials)
-└── references/
-    ├── detailed-workflow.md (1,500 words)
-    └── patterns.md (1,000 words)
-```
-
-**Process:**
-1. Identify logical sections in oversized SKILL.md
-2. Determine what's essential (stays in SKILL.md)
-3. Move detailed content to references/
-4. Add clear references: "For detailed workflow, read `references/detailed-workflow.md`"
-
-### Add Scripts
-
-**When to add scripts:**
-- Same code gets written repeatedly
-- Operation needs deterministic reliability
-- Validation that must be consistent
-
-**Process:**
-1. Identify the operation to script
-2. Write script in appropriate language
-3. Add to scripts/ directory
-4. Reference in SKILL.md: "Run `scripts/validate.py` to check"
-5. Make executable: `chmod +x scripts/validate.py`
-
-### Convert Negative to Positive Framing
-
-| Negative | Positive |
-|----------|----------|
-| Don't use deprecated APIs | Use only current, supported APIs |
-| Never commit secrets | Store secrets in environment variables |
-| Avoid long functions | Keep functions under 50 lines |
-| Don't skip tests | Include tests for all new code |
-
-### Add New Workflow
-
-**For routing skills:**
-
-1. Create new reference file: `references/new-workflow.md`
-2. Add routing option in SKILL.md
-3. Update description if new triggers needed
-
-**Structure of new workflow file:**
-```markdown
-# New Workflow Name
-
-## Purpose
-
-[What this workflow accomplishes]
-
-## Steps
-
-<steps>
-<step name="Step 1">
-[Instructions]
-</step>
-</steps>
-
-## Key Principles
-
-[Domain knowledge for this workflow]
-```
-
-## Modification Checklist
-
-Before completing any modification:
-
-- [ ] All changes follow skill conventions
-- [ ] Frontmatter still valid
-- [ ] All references point to existing files
-- [ ] SKILL.md under 2,000 words (or justified)
-- [ ] No second person in body
-- [ ] Positive framing throughout
-- [ ] User has confirmed changes are correct
-- [ ] Validation passes
-
-## Edge Cases
-
-### Skill Has No Issues But User Wants Changes
-
-Proceed with user's requested changes while ensuring no regressions. Run full validation after.
-
-### Multiple Skills Need Same Fix
-
-Consider creating a batch modification:
-1. List all skills needing the fix
-2. Apply same fix pattern to each
-3. Validate all at once
-
-### User Wants to Delete a Skill
-
-```bash
-# Backup first
-cp -r [skill-path] [skill-path].backup
-
-# Remove
-rm -rf [skill-path]
-```
+**Fix documentation-style writing:**
+Rewrite sections that describe the skill ("This skill does X") as instructions ("Do X").
 
-Confirm with user before deleting.
+**Improve activation:**
+Collect trigger phrases from user, add to description in third person with quotes.
 
-### Skill Is Part of a Plugin or Framework
+**Move content to references:**
+Identify inline content (schemas, detailed explanations) that should be loaded on-demand. Create reference file, add pointer in SKILL.md.
 
-Check if skill is:
-- In src/skills/ (development version)
-- In ~/.claude/skills/ (installed version)
+**Fix second person:**
+"You should parse" → "Parse"
+"You can use" → "Use"
 
-Modify the source version (src/skills/) and reinstall, rather than modifying installed version directly.
+**Fix negative framing:**
+"Don't skip validation" → "Always validate"
+"Never assume" → "Verify explicitly"

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

@@ -16,6 +16,83 @@ This document contains the deep knowledge required to create, audit, and modify
 
 When a skill "activates," Claude simply reads the SKILL.md file. The file contains natural language instructions telling Claude what to do.
 
+## The Most Common Mistake: Documentation vs Instructions
+
+**This is the #1 reason skills fail.** People write SKILL.md as if it's a README explaining what the skill does. But SKILL.md IS the prompt—it must tell Claude what to DO.
+
+### Documentation (WRONG)
+
+```markdown
+## Purpose
+
+This skill orchestrates the complete migration of Oracle Forms to React/Go.
+
+**Who this is for**: Developers migrating Oracle Forms.
+
+**Success looks like**: Running /implement-form progresses through all phases.
+
+## How It Works
+
+The skill has 12 phases. Phase 1 does scaffolding, Phase 2 does discovery...
+
+## YAML Schema
+
+```yaml
+form:
+  name: FORMNAME
+  prefix: xx
+status: in_progress
+# ... 50 more lines of schema
+```
+```
+
+**Why this fails:** Claude reads this and thinks "interesting information, but what should I DO right now?" There are no actionable instructions.
+
+### Instructions (CORRECT)
+
+```markdown
+## What To Do Now
+
+<step name="Get Form Name">
+Ask which form to implement. Store the form name.
+</step>
+
+<step name="Check Workflow State">
+Look for `.claude/workflows/{formname}/workflow.yaml`
+
+If exists: Read it, determine current phase.
+If not: Create new workflow, start at phase 1.
+</step>
+
+<step name="Route to Phase">
+Based on `currentPhase`, read the appropriate file:
+
+| Phase | File |
+|-------|------|
+| phase1 | `references/phase1.md` |
+| phase2 | `references/phase2.md` |
+</step>
+```
+
+**Why this works:** Claude knows exactly what to do. Each step is an action. Heavy content (schemas, phase details) lives in references/.
+
+### Red Flags in SKILL.md
+
+| Red Flag | Problem |
+|----------|---------|
+| "Who this is for:" | Meta-description. Claude doesn't need audience info. |
+| "Success looks like:" | Describes outcomes, doesn't instruct. |
+| "This skill orchestrates..." | Describes what skill IS, not what to DO. |
+| "The purpose is..." | Documentation language. |
+| Large inline schemas | Reference material, not instructions. |
+| Phase explanations | Should route to phase files, not explain inline. |
+
+### The Test
+
+After writing SKILL.md, ask: **"If Claude reads this right now, does it know what action to take?"**
+
+If the answer is "it would understand what the skill is about" but not "it would know what to do," rewrite it.
+
 ## Why Progressive Disclosure Matters
 
 ### The Problem Without Skills