Improve/skill review optimization

[yogesh-tessl]

Hey @ratacat 👋

98 skills ranging from kalshi prediction markets to DHH-style Rails reviewing to systematic debugging. This is one of the most eclectic and practical skill collections out there. Love that you built skill-creator and skill-installer tooling to make the whole ecosystem self-sustaining. Wanted to suggest a few improvements to the SKILL.md.

I ran your skills through tessl skill review at work and found some targeted improvements. Here's the full before/after:

Skill	Before	After	Change
systematic-debugging	47%	88%	+41%
writing-claude-skills	60%	78%	+18%
postgres-query-expert	72%	90%	+18%
design-patterns	69%	83%	+14%
clean-code	79%	86%	+7%

What changed

All 5 skills - improved descriptions:

• Added concrete "what it does" actions alongside "when to use" triggers (the evaluator weights both)
• Expanded trigger terms with natural language users would actually type (e.g. "postgres", "psql", "slow query" for postgres-query-expert)
• Used quoted string format for frontmatter descriptions

systematic-debugging (+41%):

• Collapsed verbose "When to Use" section (15+ bullet points saying the same thing) into a single clear sentence
• Removed "Common Rationalizations" table, "Red Flags" list, "Signals You're Doing It Wrong", and "Real-World Impact" stats — all motivational content that doesn't help Claude follow the actual four-phase workflow
• Core debugging methodology and phase structure preserved intact

writing-claude-skills (+18%):

• Removed "Skills vs Other Claude Features" comparison table (concepts Claude already knows)
• Removed "TDD Mapping" table (redundant with the RED-GREEN-REFACTOR section that follows)
• Removed "Common Rationalizations" table and "Bulletproofing Skills Against Rationalization" section (68 lines of meta-advice that repeated earlier content)
• Core CSO guidance, skill structure, and RED-GREEN-REFACTOR workflow preserved

postgres-query-expert (+18%):

• Added a 4-step "Performance Diagnosis Workflow" with an explicit verify/feedback loop (Identify → Diagnose → Fix → Verify via EXPLAIN)

design-patterns (+14%):

• Replaced verbose "Foundational Principles" table (SOLID principles Claude already knows) with a concise one-liner
• Added explicit 4-step "Pattern Application Workflow" (Identify symptom → Select pattern → Implement minimally → Verify)

clean-code (+7%):

• Removed philosophical quotes that consumed tokens without adding actionable guidance
• Replaced "The Craft" prose section with a concrete 6-step "Clean Code Review Workflow" checklist

---

Honest disclosure. I work at https://github.com/tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute.

I also added a lightweight GitHub Action that auto-reviews any skill.md changed in a PR (includes min permissions, uses a pinned action version, only posts a review comment).

This means that it gives you and your contributors an instant quality signal before you have to review yourself (no signup, no tokens needed).

Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at this Tessl guide (https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me - @yogesh-tessl (https://github.com/yogesh-tessl) - if you hit any snags.

Thanks in advance 🙏