Feedback on your project-memory skill

[RichardHightower]

I took a look at your project-memory skill and wanted to share some thoughts.

Links:

• GitHub
• SkillzWave Marketplace

The TL;DR

You're at 92/100, solid A territory. This is based on Anthropic's skill best practices rubric. Your strongest area is Ease of Use (23/25)—the skill is genuinely discoverable and the four reference templates are well-structured. The weakest pillar is Spec Compliance (13/15), which is more of a technical formality than a real problem.

What's Working Well

• Templates hit the right level of detail. Your bugs_template.md, decisions_template.md, and others give concrete examples without being overwhelming. They're actually usable, not just theoretical.
• Trigger phrases are solid. Phrases like "set up project memory," "log a bug fix," and "document architectural decisions" make the skill discoverable. Someone could actually find this when they need it.
• The layered structure works. SKILL.md stays focused on the "why" and "what," while reference templates contain the actionable details. Good separation of concerns.
• Real problem being solved. Institutional knowledge loss across AI coding sessions is a genuine pain point that other skills don't address. Your positioning here is unique.

The Big One: Second-Person Voice in Workflows

This is holding you back about 1-2 points. Your example workflows use narrative style ("User: I'm getting a connection refused error") instead of imperative instructions. It reads more like documentation of a conversation than instructions for someone to actually follow.

Current approach:

User: "I'm getting a 'connection refused' error from the database"
-> Search docs/project_notes/bugs.md

Should be:

When encountering connection errors:
1. Search bugs.md: `grep -i 'connection' docs/project_notes/bugs.md`
2. Apply documented solution if found

This shift makes the skill feel more like an actual tool and less like a scenario walkthrough. It's the difference between explaining how something works vs. telling someone how to use it.

Other Things Worth Fixing

1. "Tips for Effective Memory Management" section is filler. Those 5 tips (be proactive, keep it current, etc.) restate things already embedded in your memory protocols. Trim it or move it to a reference file. You'd gain ~2 points on Progressive Disclosure Architecture (PDA).

2. Missing a setup checklist. Your Initial Setup section says "create the following structure" but doesn't give a checkbox-style checklist. Add something like:

   - [ ] Create docs/project_notes/ directory
   - [ ] Copy bugs_template.md → bugs.md
   - [ ] Update CLAUDE.md with memory protocols
   

3. No TOC in reference files. Your reference templates are short enough that they don't need one, but SKILL.md could use a proper table of contents if you're keeping those bonus sections.

Quick Wins

• Rewrite example workflows from narrative ("User:") to imperative (numbered steps with actual commands). Biggest bang for buck—should get you +1-2 points.
• Cut the Tips section or move it to a reference file. Token economy improvement.
• Add a setup checklist in Initial Setup to make completion explicit and trackable.

These three changes would realistically push you to 95+/100.

---

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.