Improve/skill review optimization

[yogesh-tessl]

Hey @spejman 👋

13 skills covering the full Define → Implement → Review lifecycle, each with its own SKILL.md. This is exactly the kind of structured skill library that benefits from automated quality checks. The three-phase agentic flow you've mapped out (with /gh-issue through /review-pr-comments) is a really thoughtful take on end-to-end Claude Code automation.

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

Changes made

commit (+24%)

• Enriched description with specific actions ("analyze diffs, stage files, generate commit messages") and natural trigger terms ("commit message", "save changes", "check in code")
• Removed redundant "Important" and "Remember" sections that duplicated content already in the process steps
• Consolidated Conventional Commits format, type list, and attribution rules to single mentions
• Fixed step 6 which gave identical instructions for separate vs. combined commits
• Switched to third-person voice

create-pr (+16%)

• Added trigger terms ("PR", "open a PR", "submit for review", "merge request") and specified quality checks concretely (lint, typecheck, test)
• Removed coaching platitudes and redundant "Important Notes" section
• Switched to third-person voice throughout

review-pr-comments (+20%)

• Rewrote description with specific actions ("resolve review comments, apply suggested changes, dismiss feedback") and trigger terms
• Removed sections describing behaviors Claude already knows (Interactive Discussion Framework, Decision Tracking emoji legend, Additional Considerations, redundant Expected Workflow)
• Fixed invalid CLI commands (gh pr review list is not a valid command - replaced with correct gh api calls)
• Replaced unnecessary main branch checkout with direct gh pr checkout
• Added validation checkpoints after API calls and branch checkout

test-coverage-improve (+8%)

• Enriched description with specific actions ("identify uncovered code paths, generate unit tests, produce coverage reports") and trigger terms
• Removed "Test Quality Standards" section (AAA pattern, descriptive naming, mock cleanup) - Claude already knows these fundamentals
• Preserved all project-specific domain expertise (mocking strategy, Spanish business context, file structure rules)

fix-ci (+0%)

• Removed redundant Runbook section (commands already listed in workflow steps)
• Switched to third-person voice
• Score held steady at 93% — already a strong skill

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 🙏