cc-dev-template 0.1.4 → 0.1.6

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

@@ -0,0 +1,377 @@
+# 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.
+
+## 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
+
+<steps>
+
+<step name="Identify 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:**
+```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
+```
+
+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
+
+**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"]
+```
+</step>
+
+<step name="Understand Desired Changes">
+Discuss what the user wants to change.
+
+**Common modification types:**
+
+| 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.
+</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
+
+Proceed with these changes?
+```
+
+Wait for user confirmation before making changes.
+</step>
+
+<step name="Apply Changes">
+Make the planned modifications.
+
+**Follow these rules:**
+
+### Preserve Valid Content
+Keep working content intact. Only change what needs changing.
+
+### Maintain Conventions
+All changes must follow skill conventions:
+- Imperative form
+- Positive framing
+- Third-person descriptions
+- Proper file references
+
+### 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
+```
+
+**Apply changes in order:**
+1. Structural changes first (new directories, files)
+2. Content moves second
+3. Content edits third
+4. Deletions last
+</step>
+
+<step name="Validate Changes">
+After modifications, verify the skill is correct.
+
+**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
+
+**If validation fails:**
+Fix issues before proceeding. Don't leave skill in broken state.
+</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>
+
+</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]
+```
+
+Confirm with user before deleting.
+
+### Skill Is Part of a Plugin or Framework
+
+Check if skill is:
+- In src/skills/ (development version)
+- In ~/.claude/skills/ (installed version)
+
+Modify the source version (src/skills/) and reinstall, rather than modifying installed version directly.