Skip to content

feat: improve 5 lowest-scoring skills + add Tessl review action - #2

Open
rohan-tessl wants to merge 2 commits into
peterbamuhigire:mainfrom
rohan-tessl:improve/skill-review-optimization
Open

feat: improve 5 lowest-scoring skills + add Tessl review action#2
rohan-tessl wants to merge 2 commits into
peterbamuhigire:mainfrom
rohan-tessl:improve/skill-review-optimization

Conversation

@rohan-tessl

@rohan-tessl rohan-tessl commented Apr 27, 2026

Copy link
Copy Markdown

Hey @peterbamuhigire 👋

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
update-claude-documentation 16% 67% +51%
ux-for-ai 34% 62% +28%
new-project 35% 67% +32%
software-business-models 37% 68% +31%
language-standards 40% 74% +34%

This PR covers your 5 lowest-scoring skill(s) in the repo (out of 237 total). The remaining skills can be improved incrementally via the included GitHub Action — every future PR that touches a SKILL.md will get automatic review scores.

What changed in update-claude-documentation
  • Fixed reserved word violation — renamed name field from update-claude-documentation to update-project-documentation (the word "claude" is reserved by tessl validators and was causing the skill to fail deterministic validation at 16%)
  • Description rewritten with concrete "Use when..." clause covering session-end documentation, code changes, and architecture updates
  • Added user-invocable: true and triggers array (update docs, close for the day, sync documentation, etc.)
  • Replaced generic boilerplate Use When/Do Not Use When/Workflow/Quality Standards with skill-specific guidance tailored to the documentation update workflow
What changed in ux-for-ai
  • Description rewritten with explicit "Use when..." clause and RETCH framework mention for discoverability
  • Added user-invocable: true and triggers array (AI UX review, chatbot UX, copilot design, etc.)
  • Replaced generic sections with AI-specific Use When (chatbots, copilots, search, recommendations), Do Not Use When (no AI component, backend-only), and concrete Required Inputs
  • Anti-patterns section now lists the 5 most critical AI UX anti-patterns from the skill body for quick reference
What changed in new-project
  • Description rewritten from vague "Use when the task matches skill" to concrete explanation of the 4-question interview, PRIME methodology, and auto domain deduction
  • Added user-invocable: true and triggers array matching the existing trigger phrases in the skill body (start a new project, scaffold a project, etc.)
  • Added portable: true and compatible_with metadata for consistency with other skills
  • Removed redundant metadata block that duplicated frontmatter keys as nested strings
What changed in software-business-models
  • Description rewritten with "Use when..." clause covering business model selection, services-to-product transition, and Cusumano's frameworks
  • Added user-invocable: true and triggers array (product vs service, SaaS business model, open source strategy, etc.)
  • Replaced generic sections with domain-specific Use When (5 concrete scenarios), Do Not Use When (with cross-references to related skills), and actionable Required Inputs
  • Workflow now references specific skill sections (1-7) with clear step sequence
What changed in language-standards
  • Description rewritten with "Use when..." clause covering the three supported languages and specific content types
  • Added user-invocable: true and triggers array (British English style, East African English, multilingual copy, etc.)
  • Replaced generic sections with content-specific Use When/Do Not Use When scenarios and concrete Required Inputs (target language, content type, audience)
  • Quality Standards now list the 5 most important language rules for quick reference

Tessl Skill Review GitHub Action ✅

I've also included a GitHub Action (.github/workflows/skill-review.yml) that automatically reviews any SKILL.md changed in future PRs and posts scores as a PR comment.

What this gives you:

  • 🔍 Automatic tessl skill review runs on every PR touching SKILL.md
  • 💬 One updated PR comment with scores and improvement feedback
  • 🔓 Zero extra accounts — contributors don't need a Tessl login; only GITHUB_TOKEN is used
  • ✅ Non-blocking by default — feedback-only, no surprise red CI (add fail-threshold: 70 later if you want a hard gate)
  • 📈 Covers future skills incrementally as contributors edit them

Want automatic AI optimization on every SKILL.md change? 🚀

The action I've added gives you review scores on PRs. We also have a more powerful variant — tesslio/skill-review-and-optimize — that can:

  • Run AI-powered optimization suggestions on every SKILL.md PR (requires adding TESSL_API_TOKEN as a repo secret)
  • Let contributors accept suggested improvements by commenting /apply-optimize
  • Still works in review-only mode with zero secrets

Interested? Tick the box and I'll raise a follow-up PR:

  • Yes please! Add the tesslio/skill-review-and-optimize action so every SKILL.md PR gets AI optimization suggestions + the /apply-optimize flow
  • No thanks — the review scores action is enough for now

Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch — just saw room for improvement and wanted to contribute.

Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at this Tessl guide and ask it to optimize your skill. Ping me — @rohan-tessl — if you hit any snags.

Thanks in advance 🙏

@rohan-tessl
feat: improve skill scores for 5 lowest-scoring skills
ec9e990 
Optimized frontmatter, descriptions, triggers, and structural clarity
for the 5 lowest-scoring skills identified by tessl skill review:

| Skill                        | Before | After | Change |
|------------------------------|--------|-------|--------|
| update-claude-documentation  | 16%    | 67%   | +51%   |
| ux-for-ai                    | 34%    | 62%   | +28%   |
| new-project                  | 35%    | 67%   | +32%   |
| software-business-models     | 37%    | 68%   | +31%   |
| language-standards           | 40%    | 74%   | +34%   |

Key changes across all skills:
- Rewrote descriptions with "Use when..." clause and concrete trigger terms
- Added user-invocable: true and triggers arrays for frontmatter compliance
- Replaced generic boilerplate Use When/Do Not Use When with skill-specific guidance
- Made workflow steps numbered and actionable with clear inputs/outputs
- Fixed reserved word violation in update-claude-documentation name field
@rohan-tessl
ci: add Tessl skill review workflow for SKILL.md PRs
5ffe402
@rohan-tessl
rohan-tessl marked this pull request as ready for review April 27, 2026 09:30
@peterbamuhigire

peterbamuhigire commented Apr 27, 2026 via email

Copy link
Copy Markdown
Owner

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@rohan-tessl @peterbamuhigire