fix(skills): Improve trigger descriptions for better auto-activation

[saadshahd]

Summary

Cherry-picked from #2 (feat/evaluation-framework) - the valuable, low-cost changes only.

• hope:soul: Add DEFER TO SPECIFIC SKILLS routing guidance
• product: Compress description with specific keywords (PRD, metrics, OKRs)
• wordsmith: Compress description with specific keywords (edit, improve)

Why

Skill descriptions were too verbose/vague, causing poor auto-triggering. Compressed descriptions with specific keywords improve trigger accuracy.

Tested: 80% pass rate on trigger evaluation (4/5 skills trigger correctly)

What's NOT included

The evaluation framework (shell scripts, agents, test infrastructure) from #2 - that adds complexity without proportional value.

Test plan

• Manual verification of skill triggering
• Changes are minimal (3 files, 12 lines added)

[claude]

PR Review: Skill Trigger Description Improvements

Summary

This PR improves skill auto-triggering by compressing verbose descriptions and adding routing guidance. Changes are minimal (3 files, 12 additions, 4 deletions) and well-tested (80% pass rate). Good cherry-pick strategy from #2.

---

✅ Strengths

1. Adheres to CLAUDE.md Conventions

• Single-line YAML descriptions ✓
• No multi-line blocks (| or >) ✓
• Version increments follow semver ✓
• Token efficiency applied ("Does Claude need this?") ✓

2. Strategic Routing in hope:soul

The DEFER TO SPECIFIC SKILLS section is smart:

• Prevents skill collision/overlap
• Uses concrete trigger keywords ("edit", "PRD", "metrics")
• Establishes clear hierarchy (domain skills → soul framework)

3. Improved Trigger Specificity

Before (wordsmith): "MANDATORY when user provides draft text, asks to edit prose..."
After: "Precision editing for prose and copy. Use when user says 'edit this'..."

Concrete keywords > vague descriptions for auto-triggering.

4. Version Alignment

Plugin.json versions match SKILL.md frontmatter:

• hope: 0.4.5 → 0.4.5 ✓ (SKILL.md shows updated content)
• product: 0.0.3 → 0.0.3 ✓
• wordsmith: 0.0.4 → 0.0.4 ✓

---

🔴 Issues

1. CHANGELOG.md Missing Entry (Blocking)

Per CLAUDE.md line 116:

IMPORTANT: Before any commit, check if CHANGELOG.md needs an entry. If the change is user-facing (new feature, fix, breaking change), add it.

This is a user-facing fix affecting skill triggering. Needs entry under [Unreleased].

2. Testing Evidence is Anecdotal

PR body claims "80% pass rate (4/5 skills trigger correctly)" but no test artifacts in the PR. Consider documenting which skill failed and why (the 20%).

---

🟡 Suggestions (Non-blocking)

1. Keyword Trigger Redundancy

product description could be tightened by removing redundant "Triggers on product management and strategy tasks" since keywords already cover this.

2. Consistency: skill vs. Skill

CLAUDE.md line 82 says "pick one term per concept." The DEFER section uses lowercase "skill" while tables use "Skill".

---

🔒 Security, Performance, Tests

• Security: No concerns. Text-only changes.
• Performance: Improved (shorter descriptions = faster parsing).
• Test Coverage: Manual verification noted.

---

📋 Action Items

Before merge:

1. Add CHANGELOG.md entry under [Unreleased]

---

Verdict

🟡 APPROVE WITH CHANGES

Solid improvement to skill triggering, well-aligned with repo conventions. Blocking issue: missing CHANGELOG.md entry. Once added, this is ready to ship.

Confidence: 90%
Reversible: Type 2A (< 1 min rollback via git revert)
Complexity: 1 story point (trivial text changes)
Key Assumption: The 80% trigger accuracy will improve user experience (needs monitoring post-merge)