Document skill description trap: descriptions override flowcharts

Testing revealed that skill descriptions summarizing workflow cause
Claude to follow the description instead of reading the skill body.

- A description saying "code review between tasks" caused ONE review
- The flowchart clearly showed TWO reviews (spec compliance + quality)
- Minimal description ("Use when...") correctly deferred to flowchart

Updated writing-skills with:
- "Description = When to Use, NOT What the Skill Does" section
- Cautionary tale about this actual failure
- Examples of good (triggers only) vs bad (workflow summary) descriptions

Updated subagent-driven-development:
- Removed workflow summary from description
- Now just: "Use when executing implementation plans..."

Updated test runner:
- Added --dangerously-skip-permissions for automated testing
This commit is contained in:
Jesse Vincent
2025-12-11 20:03:39 -08:00
parent cd83439bb2
commit 2a19be0b78
3 changed files with 35 additions and 8 deletions

View File

@@ -71,10 +71,11 @@ echo ""
# Run claude and capture output
# Using stream-json to get token usage stats
# Run from project directory so .claude/settings.local.json is picked up
# --dangerously-skip-permissions for automated testing (subagents don't inherit parent settings)
cd "$OUTPUT_DIR/project"
claude -p "$PROMPT" \
--plugin-dir "$PLUGIN_DIR" \
--dangerously-skip-permissions \
--output-format stream-json \
> "$LOG_FILE" 2>&1 || true