From 05f061d2474f0975eddbd848e19c52e24b70778a Mon Sep 17 00:00:00 2001 From: rohan-tessl Date: Mon, 23 Mar 2026 11:49:40 +0530 Subject: [PATCH] fix: use user-invocable everywhere; remove pr_description.md. --- .claude/skills/adapt/SKILL.md | 2 +- .claude/skills/animate/SKILL.md | 2 +- .claude/skills/arrange/SKILL.md | 2 +- .claude/skills/audit/SKILL.md | 2 +- .claude/skills/bolder/SKILL.md | 2 +- .claude/skills/clarify/SKILL.md | 2 +- .claude/skills/colorize/SKILL.md | 2 +- .claude/skills/critique/SKILL.md | 2 +- .claude/skills/delight/SKILL.md | 2 +- .claude/skills/distill/SKILL.md | 2 +- .claude/skills/extract/SKILL.md | 2 +- .claude/skills/harden/SKILL.md | 2 +- .claude/skills/normalize/SKILL.md | 2 +- .claude/skills/onboard/SKILL.md | 2 +- .claude/skills/optimize/SKILL.md | 2 +- .claude/skills/overdrive/SKILL.md | 2 +- .claude/skills/polish/SKILL.md | 2 +- .claude/skills/quieter/SKILL.md | 2 +- .claude/skills/teach-impeccable/SKILL.md | 2 +- .claude/skills/typeset/SKILL.md | 2 +- pr_description.md | 68 ------------------------ scripts/lib/transformers/claude-code.js | 2 +- scripts/lib/transformers/opencode.js | 2 +- 23 files changed, 22 insertions(+), 90 deletions(-) delete mode 100644 pr_description.md diff --git a/.claude/skills/adapt/SKILL.md b/.claude/skills/adapt/SKILL.md index ccda56df5..8de3da6dc 100644 --- a/.claude/skills/adapt/SKILL.md +++ b/.claude/skills/adapt/SKILL.md @@ -1,7 +1,7 @@ --- name: adapt description: "Adapt designs to work across different screen sizes, devices, contexts, or platforms. Implements breakpoints, fluid layouts, and touch targets. Use when the user mentions responsive design, mobile layouts, breakpoints, viewport adaptation, or cross-device compatibility." -user-invokable: true +user-invocable: true args: - name: target description: The feature or component to adapt (optional) diff --git a/.claude/skills/animate/SKILL.md b/.claude/skills/animate/SKILL.md index 7a7934d17..a483f6bab 100644 --- a/.claude/skills/animate/SKILL.md +++ b/.claude/skills/animate/SKILL.md @@ -1,7 +1,7 @@ --- name: animate description: "Review a feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight. Use when the user mentions adding animation, transitions, micro-interactions, motion design, hover effects, or making the UI feel more alive." -user-invokable: true +user-invocable: true args: - name: target description: The feature or component to animate (optional) diff --git a/.claude/skills/arrange/SKILL.md b/.claude/skills/arrange/SKILL.md index e7514dee1..9604aee03 100644 --- a/.claude/skills/arrange/SKILL.md +++ b/.claude/skills/arrange/SKILL.md @@ -1,7 +1,7 @@ --- name: arrange description: "Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when the user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition." -user-invokable: true +user-invocable: true args: - name: target description: The feature or component to improve layout for (optional) diff --git a/.claude/skills/audit/SKILL.md b/.claude/skills/audit/SKILL.md index 95d86be8b..9b57da6c3 100644 --- a/.claude/skills/audit/SKILL.md +++ b/.claude/skills/audit/SKILL.md @@ -1,7 +1,7 @@ --- name: audit description: "Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a prioritized report with severity ratings. Use when the user wants a design review, accessibility check, quality audit, or a full list of UI issues to fix." -user-invokable: true +user-invocable: true args: - name: area description: The feature or area to audit (optional) diff --git a/.claude/skills/bolder/SKILL.md b/.claude/skills/bolder/SKILL.md index 6af413c87..13835b3e8 100644 --- a/.claude/skills/bolder/SKILL.md +++ b/.claude/skills/bolder/SKILL.md @@ -1,7 +1,7 @@ --- name: bolder description: "Amplify safe or boring designs to make them more visually interesting and stimulating. Increases impact while maintaining usability. Use when the user says the design looks bland, generic, too safe, lacks personality, or wants more visual impact and character." -user-invokable: true +user-invocable: true args: - name: target description: The feature or component to make bolder (optional) diff --git a/.claude/skills/clarify/SKILL.md b/.claude/skills/clarify/SKILL.md index 69dc4e40e..689c4a202 100644 --- a/.claude/skills/clarify/SKILL.md +++ b/.claude/skills/clarify/SKILL.md @@ -1,7 +1,7 @@ --- name: clarify description: "Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when the user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing." -user-invokable: true +user-invocable: true args: - name: target description: The feature or component with unclear copy (optional) diff --git a/.claude/skills/colorize/SKILL.md b/.claude/skills/colorize/SKILL.md index c95004fec..b44e117f1 100644 --- a/.claude/skills/colorize/SKILL.md +++ b/.claude/skills/colorize/SKILL.md @@ -1,7 +1,7 @@ --- name: colorize description: "Add strategic color to features that are too monochromatic or lack visual interest, making interfaces more engaging and expressive. Use when the user mentions the design looking gray, dull, lacking warmth, needing more color, or wanting a more vibrant or expressive palette." -user-invokable: true +user-invocable: true args: - name: target description: The feature or component to colorize (optional) diff --git a/.claude/skills/critique/SKILL.md b/.claude/skills/critique/SKILL.md index 25ee79736..e1d7da7ff 100644 --- a/.claude/skills/critique/SKILL.md +++ b/.claude/skills/critique/SKILL.md @@ -1,7 +1,7 @@ --- name: critique description: "Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. Use when the user asks to review, critique, evaluate, audit, or give feedback on a design, UI, or component." -user-invokable: true +user-invocable: true args: - name: area description: The feature or area to critique (optional) diff --git a/.claude/skills/delight/SKILL.md b/.claude/skills/delight/SKILL.md index 002830f64..0764327fe 100644 --- a/.claude/skills/delight/SKILL.md +++ b/.claude/skills/delight/SKILL.md @@ -1,7 +1,7 @@ --- name: delight description: "Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable." -user-invokable: true +user-invocable: true args: - name: target description: The feature or area to add delight to (optional) diff --git a/.claude/skills/distill/SKILL.md b/.claude/skills/distill/SKILL.md index c2c33162b..a07e47bd4 100644 --- a/.claude/skills/distill/SKILL.md +++ b/.claude/skills/distill/SKILL.md @@ -1,7 +1,7 @@ --- name: distill description: "Strip designs to their essence by removing unnecessary complexity. Great design is simple, powerful, and clean. Use when the user asks to simplify, declutter, reduce noise, remove elements, or make a UI cleaner and more focused." -user-invokable: true +user-invocable: true args: - name: target description: The feature or component to distill (optional) diff --git a/.claude/skills/extract/SKILL.md b/.claude/skills/extract/SKILL.md index 9df195661..4c3d89fa0 100644 --- a/.claude/skills/extract/SKILL.md +++ b/.claude/skills/extract/SKILL.md @@ -1,7 +1,7 @@ --- name: extract description: "Extract and consolidate reusable components, design tokens, and patterns into your design system. Identifies opportunities for systematic reuse and enriches your component library. Use when the user asks to create components, refactor repeated UI patterns, build a design system, or extract tokens." -user-invokable: true +user-invocable: true args: - name: target description: The feature, component, or area to extract from (optional) diff --git a/.claude/skills/harden/SKILL.md b/.claude/skills/harden/SKILL.md index f5d58fb1d..a241c86c9 100644 --- a/.claude/skills/harden/SKILL.md +++ b/.claude/skills/harden/SKILL.md @@ -1,7 +1,7 @@ --- name: harden description: "Improve interface resilience through better error handling, i18n support, text overflow handling, and edge case management. Makes interfaces robust and production-ready. Use when the user asks to harden, make production-ready, handle edge cases, add error states, or fix overflow and i18n issues." -user-invokable: true +user-invocable: true args: - name: target description: The feature or area to harden (optional) diff --git a/.claude/skills/normalize/SKILL.md b/.claude/skills/normalize/SKILL.md index f34978a7a..1a4cf1795 100644 --- a/.claude/skills/normalize/SKILL.md +++ b/.claude/skills/normalize/SKILL.md @@ -1,7 +1,7 @@ --- name: normalize description: "Audits and realigns UI to match design system standards, spacing, tokens, and patterns. Use when the user mentions consistency, design drift, mismatched styles, tokens, or wants to bring a feature back in line with the system." -user-invokable: true +user-invocable: true args: - name: feature description: The page, route, or feature to normalize (optional) diff --git a/.claude/skills/onboard/SKILL.md b/.claude/skills/onboard/SKILL.md index 318b9e14c..bc9c327ac 100644 --- a/.claude/skills/onboard/SKILL.md +++ b/.claude/skills/onboard/SKILL.md @@ -1,7 +1,7 @@ --- name: onboard description: "Designs and improves onboarding flows, empty states, and first-run experiences to help users reach value quickly. Use when the user mentions onboarding, first-time users, empty states, activation, getting started, or new user flows." -user-invokable: true +user-invocable: true args: - name: target description: The feature or area needing onboarding (optional) diff --git a/.claude/skills/optimize/SKILL.md b/.claude/skills/optimize/SKILL.md index 751ff1fb4..8800af3b5 100644 --- a/.claude/skills/optimize/SKILL.md +++ b/.claude/skills/optimize/SKILL.md @@ -1,7 +1,7 @@ --- name: optimize description: "Diagnoses and fixes UI performance across loading speed, rendering, animations, images, and bundle size. Use when the user mentions slow, laggy, janky, performance, bundle size, load time, or wants a faster, smoother experience." -user-invokable: true +user-invocable: true args: - name: target description: The feature or area to optimize (optional) diff --git a/.claude/skills/overdrive/SKILL.md b/.claude/skills/overdrive/SKILL.md index aee68d5de..7e63bba8d 100644 --- a/.claude/skills/overdrive/SKILL.md +++ b/.claude/skills/overdrive/SKILL.md @@ -1,7 +1,7 @@ --- name: overdrive description: "Pushes interfaces past conventional limits with technically ambitious implementations — shaders, spring physics, scroll-driven reveals, 60fps animations. Use when the user wants to wow, impress, go all-out, or make something that feels extraordinary." -user-invokable: true +user-invocable: true args: - name: target description: The feature or area to push into overdrive (optional) diff --git a/.claude/skills/polish/SKILL.md b/.claude/skills/polish/SKILL.md index a006c6885..a3c1c4d04 100644 --- a/.claude/skills/polish/SKILL.md +++ b/.claude/skills/polish/SKILL.md @@ -1,7 +1,7 @@ --- name: polish description: "Performs a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when the user mentions polish, finishing touches, pre-launch review, something looks off, or wants to go from good to great." -user-invokable: true +user-invocable: true args: - name: target description: The feature or area to polish (optional) diff --git a/.claude/skills/quieter/SKILL.md b/.claude/skills/quieter/SKILL.md index 734af7ad8..b4ae9297d 100644 --- a/.claude/skills/quieter/SKILL.md +++ b/.claude/skills/quieter/SKILL.md @@ -1,7 +1,7 @@ --- name: quieter description: "Tones down visually aggressive or overstimulating designs, reducing intensity while preserving quality. Use when the user mentions too bold, too loud, overwhelming, aggressive, garish, or wants a calmer, more refined aesthetic." -user-invokable: true +user-invocable: true args: - name: target description: The feature or component to make quieter (optional) diff --git a/.claude/skills/teach-impeccable/SKILL.md b/.claude/skills/teach-impeccable/SKILL.md index 18d04d160..998cfa6a3 100644 --- a/.claude/skills/teach-impeccable/SKILL.md +++ b/.claude/skills/teach-impeccable/SKILL.md @@ -1,7 +1,7 @@ --- name: teach-impeccable description: "One-time setup that gathers project design context and persists it to your AI config file for all future sessions. Use when starting a new project, when design context is missing, or before running any other impeccable skill for the first time." -user-invokable: true +user-invocable: true --- Gather design context for this project, then persist it for all future sessions. diff --git a/.claude/skills/typeset/SKILL.md b/.claude/skills/typeset/SKILL.md index b9881238c..06ed4e3cb 100644 --- a/.claude/skills/typeset/SKILL.md +++ b/.claude/skills/typeset/SKILL.md @@ -1,7 +1,7 @@ --- name: typeset description: "Improves typography by fixing font choices, hierarchy, sizing, weight, and readability so text feels intentional. Use when the user mentions fonts, type, readability, text hierarchy, sizing looks off, or wants more polished, intentional typography." -user-invokable: true +user-invocable: true args: - name: target description: The feature or component to improve typography for (optional) diff --git a/pr_description.md b/pr_description.md deleted file mode 100644 index efa995b79..000000000 --- a/pr_description.md +++ /dev/null @@ -1,68 +0,0 @@ -## Summary - -Hey @pbakaus 👋 - -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 | -|-------|--------|-------|--------| -| distill | 31% | 80% | +49% | -| delight | 32% | 74% | +42% | -| polish | 44% | 80% | +36% | -| animate | 55% | 89% | +34% | -| clarify | 49% | 83% | +34% | -| critique | 51% | 85% | +34% | -| normalize | 46% | 80% | +34% | -| optimize | 49% | 83% | +34% | -| adapt | 48% | 81% | +33% | -| extract | 48% | 81% | +33% | -| harden | 49% | 79% | +30% | -| arrange | 51% | 76% | +25% | -| bolder | 51% | 76% | +25% | -| colorize | 48% | 72% | +24% | -| overdrive | 48% | 70% | +22% | -| typeset | 64% | 85% | +21% | -| audit | 61% | 81% | +20% | -| onboard | 56% | 75% | +19% | -| quieter | 59% | 76% | +17% | -| teach-impeccable | 68% | 80% | +12% | -| frontend-design | 76% | 76% | +0% | - -![Score Card](score_card.png) - -**Note:** These skills are auto-generated from `source/skills/` via your build system, so the changes target the source files directly. The `dist/` outputs were regenerated with `bun run build`. - -
-Changes made - -All changes are limited to the `description` field in each skill's YAML frontmatter (in `source/skills/*/SKILL.md`). No skill body content was modified. - -The consistent improvement across all skills was adding: -- **"Use when..." clauses** with explicit trigger terms — the #1 issue flagged by the reviewer. Without these, agents have no clear signal for when to select a skill from a large library. -- **Natural user keywords** — terms users would actually say (e.g., "too bold", "laggy", "spacing issues") rather than abstract descriptors. -- **Specific concrete actions** — listing what the skill actually does rather than describing outcomes in vague terms. -- **Quoted string format** — ensuring descriptions use standard YAML quoted strings. - -`frontend-design` was already well-scored and left unchanged. - -
- -## Type of change - -- [x] New / updated skill reference - -## Checklist - -- [x] Source files updated in `source/` -- [x] `bun run build` ran successfully -- [ ] `bun test` passes -- [ ] Tested with at least one provider (Cursor / Claude Code / Gemini CLI / Codex / Copilot / Kiro / OpenCode) -- [ ] README / DEVELOP.md updated if needed - ---- - -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](https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me - [@rohan-tessl](https://github.com/rohan-tessl) - if you hit any snags. - -Thanks in advance 🙏 diff --git a/scripts/lib/transformers/claude-code.js b/scripts/lib/transformers/claude-code.js index 365647bda..eeebaccbd 100644 --- a/scripts/lib/transformers/claude-code.js +++ b/scripts/lib/transformers/claude-code.js @@ -5,7 +5,7 @@ import { cleanDir, ensureDir, writeFile, generateYamlFrontmatter, replacePlaceho * Claude Code Transformer (Skills Only) * * All skills output to .claude/skills/{name}/SKILL.md - * User-invokable skills get args support in frontmatter. + * User-invocable skills get args support in frontmatter. * * @param {Array} skills - All skills (including user-invocable ones) * @param {string} distDir - Distribution output directory diff --git a/scripts/lib/transformers/opencode.js b/scripts/lib/transformers/opencode.js index 05181d964..26b68f726 100644 --- a/scripts/lib/transformers/opencode.js +++ b/scripts/lib/transformers/opencode.js @@ -12,7 +12,7 @@ import { * OpenCode Transformer (Skills Only) * * All skills output to .opencode/skills/{name}/SKILL.md - * User-invokable skills get args support in frontmatter. + * User-invocable skills get args support in frontmatter. * * @param {Array} skills - All skills (including user-invocable ones) * @param {string} distDir - Distribution output directory