Improve/skill review optimization

[yogesh-tessl]

Hey @excatt 👋

Running 120 skills and 23 agents through system-enforced rules is a whole new paradigm built on top of SuperClaude. Skill-rules.json + Circuit Breaker + Prompt Injection Scanner shows you've moved from prompt-dependent to real engineering. 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
debug	39%	96%	+57%
refactoring	30%	90%	+60%
api-design	43%	84%	+41%
security-audit	90%	90%	+0%
tdd	90%	90%	+0%

The biggest wins were on debug (+57%), refactoring (+60%), and api-design (+41%). Yhe other two were already strong and just got minor cleanup.

Changes Summary

debug (39% → 96%)

• Rewrote description with specific actions (reproduces bugs, analyzes stack traces, git bisect), natural trigger terms (bug, error, crash, exception, not working), and explicit "Use when" / "Do NOT use for" clauses
• Removed common bug patterns section (race conditions, null refs, memory leaks) - Claude already knows these
• Removed language-specific tool listings - general knowledge that doesn't add value
• Added explicit feedback loops in the workflow (return to Step 3 after failed hypothesis, broaden to Step 2 after 3 failures)
• Added dynamic context section for recent bug-fix commits
• Added concrete git bisect and grep commands

refactoring (30% → 90%)

• Rewrote description with specific actions (detects code smells, applies targeted patterns), comprehensive trigger terms (refactor, clean up, technical debt, DRY, decompose), and scope boundaries
• Removed entire pattern catalog (Extract Function, Inline Function, Guard Clauses, Polymorphism, etc.) - all standard knowledge Claude already has
• Removed code smell → refactoring mapping table - general knowledge
• Added structured 5-step workflow with explicit test gates at each step
• Added error recovery guidance (revert immediately if tests fail, investigate coupling)
• Added dynamic context section for recent refactoring commits

api-design (43% → 84%)

• Rewrote description with specific actions (designs REST endpoints, GraphQL schemas, generates OpenAPI specs), trigger terms (API design, endpoint structure, Swagger, API versioning), and boundaries
• Removed HTTP status codes listing - standard knowledge
• Removed basic CRUD URL patterns - general knowledge
• Added structured 5-step design workflow from resource identification through validation
• Added REST vs GraphQL decision criteria table
• Added dynamic context section for discovering existing API files
• Added comprehensive validation checklist (security, consistency, performance, documentation)

security-audit (90% → 90%)

• Converted description from YAML block scalar (|) to quoted string format for consistency
• Removed severity definitions table (Claude already knows Critical/High/Medium/Low definitions)

tdd (90% → 90%)

• Converted description from YAML block scalar (|) to quoted string format for consistency
• Removed "Integration with Verification Iron Law" section - inferrable context that doesn't add actionable guidance

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 🙏

[excatt]

Hi @yogesh-tessl, thanks for the careful review and the detailed breakdown. The trigger-heavy descriptions, argument-hint, Dynamic Context blocks, and structured workflows match where we've been heading with v2.0+ (system-enforced auto-activation), and we'd like to land most of this.

Before merging, could we split this into three PRs? It keeps the review scopes clean and lets the strongest parts land quickly.

PR 1 — Skill rewrites (high confidence, ready to merge)

• skills/debug/SKILL.md
• skills/refactoring/SKILL.md
• skills/api-design/SKILL.md

These three are well-aligned with our framework principles (lean SKILL.md, Dynamic Context Injection, incremental delivery). Happy to merge as-is.

PR 2 — tdd and security-audit (needs revision)

A couple of concerns:

• skills/tdd/SKILL.md: The "Integration with Verification Iron Law" section is load-bearing in this framework — it's how /tdd connects to RULES.md → Verification Iron Law (the hard-evidence gate before any completion claim). Removing it disconnects the skill from a cross-cutting safety rule. Could we keep a short pointer (1–2 lines + link to RULES.md) instead of full removal?
• skills/security-audit/SKILL.md: The YAML format conversion is fine. The severity table removal is borderline — it's general knowledge, but the explicit Critical/High/Medium/Low rubric mirrors RULES.md → Two-Stage Review severity levels, so it serves as a local consistency anchor. Open to either keeping or removing, but want to flag the cross-reference.

PR 3 — .github/workflows/skill-review.yml (needs security review)

Adding a third-party GitHub Action that runs on every SKILL.md PR is a meaningful supply-chain decision for the repo. We'd like to review this separately:

• The SHA pin is appreciated (22e928d...)
• pull-requests: write permission scope is appropriate
• But we want to evaluate Tessl's review action independently of the skill content changes

If you'd prefer not to split, we can also cherry-pick the three "PR 1" files manually and you can decide what to do with the rest. Whichever is easier on your end.

Also — honest reciprocation on the disclosure: we're aware of Tessl's positioning here, and that's totally fine. The technical work stands on its own and we want to take what's useful. Just being explicit that the framework integration concerns (Verification Iron Law, Two-Stage Review) come from this repo's design constraints, not from rejecting the tooling.

Thanks again 🙏