parallel-worktrees

I took a look at your parallel-worktrees skill and wanted to share some thoughts.

Links:

• GitHub
• SkillzWave marketplace

The TL;DR

You're at 90/100, solid A-grade work. This is based on Anthropic's skill best practices. Your strongest area is Utility (18/20) – you're solving a real problem that doesn't have many alternatives. Weakest area is Progressive Disclosure Architecture (25/30) – your SKILL.md is doing too much heavy lifting at once.

What's Working Well

• Excellent trigger coverage – You nailed this with 10 specific triggers ('parallel agents', 'worktrees', 'async Claude', etc.). Discoverability is a strength here.
• Solid reference architecture – Your workflow-patterns.md and cli-reference.md are properly delegated. The one-level-deep structure is clean and navigable.
• Real-world examples and templates – Shell scripts, status JSON templates, agent task templates, and RESULTS.md format show you've thought through actual usage.
• Addresses a genuine gap – Parallel AI development with worktrees + subagents is legitimately useful and not something most people are doing yet.

The Big One: SKILL.md Is Overweight

Your main file is 407 lines, and the Background Agents section alone is 176 lines (lines 231-407). This section should live in its own reference file.

Why it matters: Token economy is critical for skills. When Claude loads this, they're getting everything upfront, even if they only need the quick-start workflow.

The fix:

1. Create references/background-agents.md with the full 176-line section
2. Replace SKILL.md lines 231-407 with a 5-10 line summary + link: "For orchestrating background agents across multiple worktrees, see Background Agents"
3. This should bump you from 25/30 → 28/30 on PDA (+3 points)

Other Things Worth Fixing

1. Terminology inconsistency – You alternate between "subagents" and "agents" without clear distinction. Standardize on "subagent" throughout to avoid confusion (impacts Ease of Use, +1 point).

2. Redundant pattern descriptions – Patterns 1-4 get brief coverage in SKILL.md (154-174), then full details in workflow-patterns.md. SKILL.md should just list pattern names with one-liners and link out (Writing Style, +1 point).

3. Missing TOC in reference files – Your main SKILL.md has good TOC, but workflow-patterns.md and cli-reference.md don't. Add markdown TOCs to anything over 100 lines (Navigation Signals, +1 point).

Quick Wins

• Move Background Agents section to references/background-agents.md → +3 points
• Standardize on "subagent" terminology throughout → +1 point
• Trim pattern descriptions in SKILL.md, link to reference → +1 point
• Add TOCs to reference files → +1 point

These fixes alone would push you to 96/100 – A+ territory. The skill is genuinely useful as-is, but tightening the PDA will make it easier for Claude to navigate and load faster.

Checkout your skill here: SkillzWave.ai | SpillWave We have an agentic skill installer that installs skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.