Feedback on your history skill #124
Description
I took a look at your history skill and wanted to share some thoughts.
Links:
The TL;DR
You're at 87/100, solid B grade territory. This is based on Anthropic's skill best practices rubric. Your strongest area is Progressive Disclosure Architecture (27/30) — you've got a really clean multi-file structure that keeps SKILL.md tight while pushing details to specialized reference docs. The main weakness is Spec Compliance (11/15) because your description is missing trigger phrases that help users find the skill.
What's Working Well
-
Reference file architecture is chef's kiss — workflow.md, output-template.md, verification-guide.md, and reference.md are all exactly one level deep from SKILL.md. Clear purpose separation with good navigation signals (anchors like
workflow.md#step-0). This is how PDA should look. -
Verification workflow is thorough — Your V1-V4 verification steps with specific tolerances (±20% checks) and error recovery procedures show you actually thought about how someone uses this. Strong feedback loop design.
-
Practical utility — You're solving a real problem: git history analysis for identifying tech debt, coupling, and bus factor. The scope/force flags give appropriate constraints while still allowing customization.
The Big One: Add Trigger Phrases to Description
Right now your description is:
Smart temporal analysis using git history - Hotspots, Coupling, and Recent Contributors
Why it matters: Users won't discover this skill when they search for "git history analysis" or "coupling analysis." The description is purely marketing fluff with zero trigger phrases. You lose points on Spec Compliance (description_quality) and Ease of Use (discoverability).
The fix: Add trigger phrases that match how people actually ask for this:
Performs git history analysis. Use when asked to "analyze git history", "find code hotspots",
"analyze code coupling", "identify contributors", "assess bus factor", or "temporal analysis".
This alone bumps you up 2 points.
Other Things Worth Fixing
-
Redundant workflow content — Your SKILL.md repeats full bash commands and step details from workflow.md (lines 59-145). Instead, make SKILL.md a brief overview with bullets pointing to workflow.md for the actual commands. Saves tokens, improves PDA.
-
Output format duplication — Lines 153-183 in SKILL.md duplicate what's already in output-template.md. Replace with a reference + just the header example.
-
Second-person voice creeping in — Line 33 says "You are analyzing" and "Your Task". Stick to imperative: "This command analyzes" or "Analyze git commit history". Small fix, +1 point on Writing Style.
-
Generic skill name — "history" is pretty broad. Consider "git-history" to avoid conflicts. If you keep it, lean harder on those trigger phrases (see issue feature/commands-prd-2-5-2 #1).
Quick Wins
- ✅ Add trigger phrases to description → +2 points
- ✅ Consolidate duplicate content in SKILL.md → +2 points
- ✅ Fix second-person voice → +1 point
- ✅ Consider renaming for uniqueness → +1 point
You're close to A territory (90+). These are mostly cleanup items, not structural issues.
Checkout your skill here: [SkillzWave.ai](https://skillzwave.ai) | [SpillWave](https://spillwave.com) 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.