Feedback on your architect-agent skill #44
Description
I took a look at your architect-agent skill and wanted to share some thoughts.
Links:
The TL;DR
You're at 93/100, which puts you solidly in A territory. This evaluation is based on Anthropic's skill best practices. Your strongest area is Spec Compliance (15/15) — your YAML frontmatter is solid and naming conventions are perfect. The weakest spot is Utility (18/20), mostly because you're missing some quick-reference examples that would make onboarding faster.
What's Working Well
- Progressive Disclosure Architecture is textbook — The 216-line SKILL.md routing to 33 reference files, 4 workflow guides, and 43 templates is exactly how PDA should work. You're not dumping everything upfront; you're layering information strategically.
- Trigger phrases are comprehensive — You've got 8+ specific action phrases ("plan multi-agent work", "delegate to code agents", "grade implementations") that make your skill actually discoverable. The "DO NOT Trigger For" section prevents false positives too, which is smart.
- Terminology is locked in — "architect/code agent", "instructions/human instructions", "grades" — you're consistent throughout, which matters way more than it sounds for maintainability.
The Big One: Redundant Routing Tables
Your Intent Classification and Decision Tree tables in SKILL.md are basically saying the same thing twice. You've got overlapping mappings between user phrases and actions, which wastes tokens and confuses users about which table to actually use.
Merge them into a single Decision Tree with three columns: Intent, Pre-condition, and Action. Instead of checking two tables, users check one. You'd drop maybe 15-20 lines of text and gain clarity. This alone could bump you to +2 points on PDA.
Other Things Worth Fixing
-
No inline examples in SKILL.md — You point to references for everything, but a 3-5 line abbreviated example of what an instruction header or grade looks like would be huge for onboarding. Users shouldn't have to dig into a 300+ line reference file to see what you're talking about. (+1 point potential)
-
Second-person voice in workflow guides — Your guides use "you" and "your" instead of imperative form. Rephrase to "After approval:" or "Suggest workspace initialization:" to match the rest of your skill's voice. It's subtle but consistent. (+1 point)
-
Missing TOCs in large references — Files like
instruction_structure.md(551 lines) don't have a table of contents at the top. For anything over 100 lines, add a linked TOC so people can jump to sections. Navigation matters when files get that long.
Quick Wins
- Merge the routing tables in SKILL.md (biggest bang for buck)
- Add one inline example showing instruction format or grade structure
- Audit workflow guides for second-person language and convert to imperative
- Add TOCs to references over 100 lines
You're already at 93 — these tweaks would get you to 96+ without major rework.
Checkout your skill here: SkillzWave.ai | SpillWave We have an agentic skill installer that install skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.