name: skill-editor description: Multi-agent workflow for editing Claude Code skills with quality gates version: 1.0.0 tags: [meta, workflow, skill-development, multi-agent]
Skill Editor
Comprehensive multi-agent workflow system for editing Claude Code skills with structured phases, quality gates, and expert review.
When to Use This Skill
Use this skill when:
- Creating new skills: User wants to add a new skill to the repository
- Modifying existing skills: User wants to update, enhance, or refactor a skill
- Complex skill changes: Change involves multiple files, agents, or architectural decisions
- Quality assurance needed: Change requires thorough review and validation
This skill provides:
- Structured 4-phase workflow
- Interactive requirements refinement
- Parallel expert analysis (3 simultaneous agents)
- Adversarial review before implementation
- Automated validation and testing
- Integration with sync-config.py and planning journal
When NOT to Use This Skill
Do NOT use this skill when:
- Simple documentation fixes: Typo fixes, minor documentation updates (edit directly)
- Non-skill changes: Modifying agents, settings, or other configuration
- Urgent hotfixes: Emergency fixes that can't wait for full workflow
- Exploratory work: Just browsing or understanding skills (use Read or Explore agent)
Four-Phase Workflow
Phase 1: REFINEMENT (10-30 min)
├─→ request-refiner: Interactive specification
└─→ Quality Gate 1: User approves specification
Phase 2: PARALLEL ANALYSIS (30-60 min)
├─→ best-practices-reviewer ┐
├─→ external-researcher ├─ Run in parallel
├─→ edge-case-simulator ┘
└─→ Quality Gate 2: All analyses complete
Phase 3: DECISION & REVIEW (45-90 min)
├─→ decision-synthesizer: Synthesize + user collaboration
├─→ adversarial-reviewer: Expert review with exact file paths
└─→ Quality Gate 3: User approves plan
Phase 4: EXECUTION (60-120 min)
├─→ executor: Implement, validate, sync, test, commit
├─→ Quality Gate 4: Pre-sync validation
└─→ Quality Gate 5: Post-execution verification
Workflow
Pre-Workflow: Safety Checks
Before starting workflow:
# Check git status
git status
# Should be clean or show only tracked files
# Check sync status
./sync-config.py status
# Should show "No changes detected" or expected divergence
# Verify in correct directory
pwd
# Should be repo root: /Users/davidangelesalbores/repos/claude
# Create session directory for output files
mkdir -p /tmp/skill-editor-session
echo "Session directory: /tmp/skill-editor-session"
If checks fail: Ask user to resolve before proceeding.
Phase 1: Refinement (Interactive)
Objective: Transform user's request into detailed, unambiguous specification.
Agent: skill-editor-request-refiner
Model: Opus 4.5
Process:
- Launch request-refiner agent via Task tool
- Agent asks clarifying questions to understand:
- What user wants to change
- Why they want this change
- What success looks like
- What's in scope vs. out of scope
- Agent reads existing skill (if modifying)
- Agent establishes clear boundaries and success criteria
- Agent presents refined specification to user
Output File: /tmp/skill-editor-session/refined-specification.md containing:
- Objective (one sentence)
- Scope (IN/OUT lists)
- Success criteria (measurable)
- Files affected
- User approval
Quality Gate 1: Specification Approval
User must approve:
- Specification matches intent
- Scope is appropriate
- Success criteria are clear
- Ready to proceed to analysis
If Gate 1 fails: Return to request-refiner for more refinement.
If Gate 1 passes: Proceed to Phase 2.
Phase 2: Parallel Analysis (3 Simultaneous Agents)
Objective: Analyze proposed change from multiple expert perspectives.
Agents (all run in parallel):
skill-editor-best-practices-reviewer(Opus 4.5)skill-editor-external-researcher(Opus 4.5)skill-editor-edge-case-simulator(Opus 4.5)
Process:
Launch all 3 agents in parallel (single message with 3 Task tool calls):
Task 1: best-practices-reviewer
- Reviews against Anthropic guidelines
- Checks skill structure specification
- Identifies architectural concerns
Task 2: external-researcher
- Searches community patterns and forums
- Finds relevant documentation and examples
- Identifies recommended approaches
Task 3: edge-case-simulator
- Simulates failure scenarios
- Identifies edge cases
- Proposes handling strategies
Important: All 3 agents run simultaneously (not sequential). Wait for all to complete before proceeding.
Output Files (must be created before proceeding to Phase 3):
/tmp/skill-editor-session/best-practices-review.md/tmp/skill-editor-session/external-research.md/tmp/skill-editor-session/edge-cases.md
Verification: Before Phase 3, verify all output files exist:
ls -lh /tmp/skill-editor-session/*.md
# Should show all 3 files with content
Quality Gate 2: Analysis Completion
Check agent completion status:
- All 3 agents complete: ✅ Proceed to Phase 3
- 2 of 3 agents complete: ⚠️ Ask user to proceed with partial analysis or retry failed agent
- <2 agents complete: ❌ Must retry failed agents or abort workflow
Additional checks:
- No critical blocking issues flagged
- No conflicting recommendations (or conflicts documented for synthesis)
- Sufficient information for decision-making
If all 3 agents fail: Stop workflow, investigate environment/configuration issues.
If partial completion (2/3):
The [failed-agent-name] agent did not complete.
Options:
1. Proceed with analysis from 2 agents (faster, less comprehensive)
2. Retry failed agent (more thorough, takes more time)
3. Abort workflow
Recommendation: If failed agent is external-researcher, safe to proceed.
If best-practices-reviewer or edge-case-simulator failed, retry recommended.
If Gate 2 passes: Proceed to Phase 3.
Phase 3: Decision & Review (Synthesis + Adversarial)
Objective: Synthesize analyses, make decisions, create plan, get expert approval.
Part A: Decision Synthesis
Agent: skill-editor-decision-synthesizer
Model: Opus 4.5 (critical decision-making)
Process:
- Read all 3 analysis reports + refined specification
- Identify consensus and conflicts
- Resolve conflicts or present options to user:
- Major decisions: MUST ask user (new agents, structure changes)
- Medium decisions: SHOULD ask user (workflow changes)
- Minor decisions: Agent decides (examples, docs)
- Create detailed implementation plan with:
- Exact file paths
- Specific changes (line numbers if possible)
- Edge case handling
- Git workflow
- Validation steps
- Rollback plan
Output File: /tmp/skill-editor-session/implementation-plan.md
Part B: Adversarial Review
Agent: skill-editor-adversarial-reviewer
Model: Opus 4.5 (expert review)
Process:
- Read implementation plan with expert skepticism
- Challenge assumptions and approach
- Identify failure modes not caught by analysis
- Verify exact file paths (run bash checks)
- Verify git workflow safety
- Check alignment with original specification
- Provide go/no-go decision
Output File: /tmp/skill-editor-session/adversarial-review.md containing:
- Architecture assessment
- Failure mode analysis
- Integration risk assessment
- Exact file path verification
- Git workflow verification
- Final decision: ✅ GO / ⚠️ CONDITIONAL / ❌ NO-GO
Quality Gate 3: Plan Approval
Check:
- Implementation plan has exact file paths
- Git workflow is safe and correct
- Integration points identified
- No architectural concerns
- Adversarial reviewer approved (GO or CONDITIONAL with fixes applied)
- User approves plan
If Gate 3 fails:
- If CONDITIONAL: Fix issues, re-review
- If NO-GO: Return to decision-synthesizer, revise plan
- If user doesn't approve: Refine plan or return to Phase 1
If Gate 3 passes: Proceed to Phase 4.
Phase 4: Execution (Implement + Validate + Commit)
Objective: Execute approved plan with validation at each step.
Agent: skill-editor-executor
Model: Opus 4.5
Process:
Step 1: Pre-Implementation Safety
git status # Must be clean
./sync-config.py status # Must be synced
pwd # Must be repo root
Stop if any check fails.
Step 2: Implement Changes
For each file in implementation plan:
- Edit: Read first, then Edit with exact string replacement
- Create: Write new file
- Delete: Remove file
Step 3: Quality Gate 4 - Pre-Sync Validation
Validate before syncing to ~/.claude/:
# Validate YAML (for skills)
for skill in claude-config/skills/*/SKILL.md; do
python3 -c "import yaml; yaml.safe_load(open('$skill').read().split('---')[1])"
done
# Validate JSON (for agents)
for agent in claude-config/agents/*.json; do
python3 -m json.tool "$agent" > /dev/null
done
# Dry-run sync
./sync-config.py push --dry-run
Quality Gate 4 Checklist:
- YAML frontmatter validates
- JSON validates (if agents modified)
- Skill structure follows specification
- File naming conventions followed
- No conflicting settings
- Dry-run sync succeeds
If Gate 4 fails: Fix issues, re-validate, do NOT proceed until pass.
Step 4: Sync to ~/.claude/
# Sync (prompts user for confirmation)
./sync-config.py push
# Verify
./sync-config.py status # Should show no divergence
Step 5: Test Skill Invocation
# Create test script
cat > /tmp/test-skill.sh << 'EOF'
#!/bin/bash
SKILL_NAME="$1"
# Check skill exists
[ -f "$HOME/.claude/skills/$SKILL_NAME/SKILL.md" ] || exit 1
# Check YAML parses
python3 -c "import yaml; yaml.safe_load(open('$HOME/.claude/skills/$SKILL_NAME/SKILL.md').read().split('---')[1])"
EOF
chmod +x /tmp/test-skill.sh
# Test skill
/tmp/test-skill.sh {skill-name}
# Smoke test existing skills (no regressions)
/tmp/test-skill.sh skill-editor
/tmp/test-skill.sh completion-verifier
Step 6: Quality Gate 5 - Post-Execution Verification
Quality Gate 5 Checklist:
- Original requirement met (from refined spec)
- Edge cases handled (from edge-case report)
- sync-config.py push successful
- Skill invokes without errors
- No regressions in existing skills
- Planning journal entry ready
If Gate 5 fails: Rollback via git reset --hard HEAD, re-sync, fix, retry.
Step 7: Update Planning Journal
./sync-config.py plan --title "[Brief description from refined spec]"
# Document in entry:
# - Objective
# - Changes made (files, lines)
# - Testing results
# - Outcome: Success
Step 8: Commit Changes
# Stage specific files (NEVER -A or .)
git add claude-config/skills/{skill-name}/SKILL.md
git add claude-config/skills/{skill-name}/examples/example.md # if created
git add claude-config/agents/{agent-name}.json # if modified
git add planning/$(hostname)/*.md
# Commit with HEREDOC (multi-line message)
git commit -m "$(cat <<'EOF'
feat(skill-name): [Brief description]
[Detailed description from implementation plan]
Changes:
- Modified SKILL.md: [what changed]
- Added example: [why]
Testing:
- Validated YAML
- Tested invocation
- No regressions
See planning/$(hostname)/[date]-[title].md
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
EOF
)"
# Verify commit
git log -1 --stat
Git Safety Checklist:
- Specific files staged (not -A or .)
- Conventional commit format (feat/fix/docs)
- Descriptive message
- Co-authored-by line
- No destructive operations
- No hook bypasses
Step 9: Report Completion
Generate completion report with:
- Summary of changes
- Validation results (Gates 4 & 5)
- Testing results
- Commit SHA
- Planning journal entry path
- Success criteria verification
Escalation Framework
Decision thresholds (from CONFIG_MANAGEMENT.md):
Major Decisions → User Approval Required
- Add new agent to workflow
- Change skill structure specification
- Modify core workflow phases
Action: Use AskUserQuestion before proceeding
Medium Decisions → User Approval Required
- Modify existing skill's core workflow
- Add new supporting skill
- Change skill naming convention
Action: Use AskUserQuestion with options
Minor Decisions → Agent Decides
- Add example to existing skill
- Fix documentation typo
- Update reference material
Action: Proceed, notify user
Error Handling
If Any Phase Fails
- Stop immediately
- Document error
- Rollback if needed:
git reset --hard HEAD - Re-sync:
./sync-config.py push - Report to user
- Ask: Retry, skip, or abort?
If Validation Fails (Gate 4 or 5)
- Do NOT proceed
- Fix issues in claude-config/
- Re-validate
- Continue only when validated
If User Cancels (Ctrl+C)
- Check git status
- Rollback uncommitted changes:
git reset --hard HEAD - Re-sync:
./sync-config.py push - Document in planning journal: "Cancelled by user"
Integration with Existing Tools
CONFIG_MANAGEMENT.md
This workflow extends the 7-step CONFIG_MANAGEMENT.md process:
- Step 1 (Safety Check): Pre-workflow checks
- Step 2 (Planning Entry): Phase 4, Step 7
- Step 3 (Implement): Phase 4, Step 2
- Step 4 (Quality Analysis): Phases 2-3, Quality Gates
- Step 5 (Preview/Sync): Phase 4, Steps 3-4
- Step 6 (Test): Phase 4, Step 5
- Step 7 (Commit): Phase 4, Step 8
sync-config.py
Executor agent uses sync-config.py:
./sync-config.py status(pre-flight check)./sync-config.py push --dry-run(validation)./sync-config.py push(apply changes)./sync-config.py plan(create planning entry)
Planning Journal
Planning entry created in Phase 4, Step 7:
- Title: Brief description from refined spec
- Objective: From refined specification
- Changes: Files modified
- Testing: Validation and test results
- Outcome: Success/Partial/Failed
Quality Gates Summary
| Gate | Phase | Owner | Criteria | Failure Action |
|---|---|---|---|---|
| 1 | Phase 1 | request-refiner | Spec approved | Return to refinement |
| 2 | Phase 2 | decision-synthesizer | All analyses complete | Re-run agents |
| 3 | Phase 3 | adversarial-reviewer | Plan approved | Revise plan |
| 4 | Phase 4 | executor | Syntax validated | Fix issues |
| 5 | Phase 4 | executor | Implementation verified | Rollback |
Examples
Example 1: Add Parallel Execution to Researcher
User Request:
/skill-editor "Add parallel web search to researcher skill"
Phase 1 Output:
Objective: Modify researcher skill to execute 3 WebSearch calls in parallel
Scope:
- IN: researcher/SKILL.md Phase 2 workflow
- OUT: No changes to agents or other phases
Success Criteria:
- 3 WebSearch calls execute simultaneously
- Results synthesized correctly
- No regressions
Phase 2 Findings:
- Best practices: Use Task tool for parallel calls ✅
- Research: Community uses this pattern ✅
- Edge cases: Handle timeout, network failure
Phase 3 Plan:
Edit: claude-config/skills/researcher/SKILL.md
Lines 45-60: Replace sequential WebSearch with parallel
Implementation:
[3 Task tool calls in single message]
Phase 4 Result:
✅ YAML validates
✅ Sync succeeds
✅ Skill invokes correctly
✅ Commit: feat(researcher): Add parallel web search
Example 2: Create New Skill
User Request:
/skill-editor "Create a new skill for API documentation"
Process:
- Phase 1: Refine requirements (which APIs? format? tools?)
- Phase 2: Analyze (best practices for doc skills, community patterns, edge cases)
- Phase 3: Plan (file structure, workflow steps, examples)
- Phase 4: Create files, validate, sync, test, commit
Notes
- Parallel execution in Phase 2: All 3 agents run simultaneously (3x faster than sequential)
- All agents use Opus 4.5: Maximum quality for all workflow phases (requirements analysis, research, edge cases, decision-making, review, execution)
- Quality gates enforce standards: No bypassing validation
- Rollback on failure: Safe to abort at any point
- Planning journal provides traceability: Full documentation of changes
- Integration tested: Works with sync-config.py and existing workflows
References
See skill-editor/references/ for:
anthropic-guidelines-summary.md: Anthropic best practicesskill-structure-specification.md: Skill format and validationquality-gates.md: Detailed quality gate checklistsconfig-management-integration.md: Integration with CONFIG_MANAGEMENT.md
Success Criteria
Skill-editor workflow succeeds when:
- User's original request is fulfilled
- All quality gates pass
- Changes are synced to
~/.claude/ - Skill invokes without errors
- No regressions in existing skills
- Planning journal documents changes
- Changes committed to git
- User confirms satisfaction