From c14eb0060cc9668cbf740469ed751880fad530ea Mon Sep 17 00:00:00 2001 From: Yogi Date: Tue, 31 Mar 2026 11:12:15 +0530 Subject: [PATCH 1/3] feat: improve skill scores for claude-plugins MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hey @mintuz 👋 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 | |-------|--------|-------|--------| | react | 63% | 100% | +37% | | typescript | 75% | 95% | +20% | | tdd | 78% | 94% | +16% | | swift-testing | 76% | 90% | +14% | | commit-messages | 86% | 90% | +4% | Description improvements (biggest impact): - react: Rewrote from category labels to concrete actions, added trigger terms and NOT clause - typescript: Added specific capabilities (z.infer, discriminated unions, branded types, type guards) - tdd: Expanded trigger terms, added concrete actions and "retrofitting tests" exclusion - swift-testing: Added missing capabilities (@Test, #expect/#require, @Suite), expanded NOT clause - commit-messages: Added concrete actions (analyzes diffs, formats type(scope): subject lines) Content improvements: - react: Replaced redundant "When to Use Each Guide" with canonical feature module + API example - typescript: Replaced redundant "When to Use Each Guide" with inline schema-first pattern - tdd: Replaced redundant "When to Use Each Guide" with inline Red-Green-Refactor example - swift-testing: Trimmed unnecessary "Works alongside XCTest" bullet - commit-messages: Removed "When to Use" and "Philosophy" sections --- plugins/app/skills/swift-testing/SKILL.md | 5 +- plugins/core/skills/commit-messages/SKILL.md | 18 +--- plugins/typescript/skills/SKILL.md | 68 ++++--------- plugins/web/skills/react/SKILL.md | 100 +++++-------------- plugins/web/skills/tdd/SKILL.md | 56 +++-------- pr-description.md | 38 +++++++ 6 files changed, 98 insertions(+), 187 deletions(-) create mode 100644 pr-description.md diff --git a/plugins/app/skills/swift-testing/SKILL.md b/plugins/app/skills/swift-testing/SKILL.md index 3b22534..c061c63 100644 --- a/plugins/app/skills/swift-testing/SKILL.md +++ b/plugins/app/skills/swift-testing/SKILL.md @@ -1,11 +1,11 @@ --- name: swift-testing -description: WHEN writing tests in Swift with the Swift Testing framework; NOT XCTest. +description: "WHEN writing tests in Swift with the Swift Testing framework; NOT for XCTest or Objective-C tests; creates @Test-annotated functions, writes #expect and #require assertions, validates thrown errors with #expect(throws:), structures test suites with @Suite, and applies macro-driven testing patterns." --- # Swift Testing Framework: Basics -Guidance for starting with Swift Testing (Testing framework) and writing clear, macro-driven tests. +Guidance for writing clear, macro-driven tests with Swift Testing. ## Core Concepts @@ -13,7 +13,6 @@ Guidance for starting with Swift Testing (Testing framework) and writing clear, - Name tests freely; use `@Test("Display Name")` to set the navigator title. - `#expect` is the primary assertion; pass a boolean expression to assert truthy outcomes. - Async/throwing tests are supported via `async`/`throws` on the test function. -- Works alongside XCTest in the same project. ## Example: Simple Test diff --git a/plugins/core/skills/commit-messages/SKILL.md b/plugins/core/skills/commit-messages/SKILL.md index e979134..1162fb0 100644 --- a/plugins/core/skills/commit-messages/SKILL.md +++ b/plugins/core/skills/commit-messages/SKILL.md @@ -1,25 +1,11 @@ --- name: commit-messages -description: WHEN writing git/conventional commits; NOT for PR text; returns concise, why-first commit lines with proper type/scope. +description: "WHEN writing git/conventional commits; NOT for PR text; analyzes diffs, formats type(scope): subject lines, assesses commit scope for splitting, and returns concise why-first messages with proper conventional commit structure." --- # Commit Messages -Use this skill to generate clear, conventional commit messages that explain the "why" not just the "what". Follow this guide when writing commit messages or helping users structure their commits. - -## When to Use - -- User asks for help writing a commit message -- User wants to understand conventional commit format -- User needs to split a large commit into smaller ones -- User asks about commit best practices - -## Philosophy - -- **Why > What** - The diff shows what changed; the message explains why -- **Atomic commits** - One logical change per commit -- **Future readers** - Write for someone debugging at 2am in 6 months -- **Searchable** - Make it easy to find with `git log --grep` +Generate clear, conventional commit messages that explain the "why" not just the "what". ## Format diff --git a/plugins/typescript/skills/SKILL.md b/plugins/typescript/skills/SKILL.md index 6f65b90..3915d40 100644 --- a/plugins/typescript/skills/SKILL.md +++ b/plugins/typescript/skills/SKILL.md @@ -1,6 +1,6 @@ --- name: typescript -description: WHEN writing TypeScript, defining types/schemas, or building type-safe apps; outputs strict, schema-first, production-ready code. +description: "WHEN writing TypeScript, defining types/schemas in .ts/.tsx files, or building type-safe apps with Zod; NOT for plain JavaScript without types; generates schema-first validation with z.infer, creates discriminated unions and branded types, defines strict interfaces and type guards, and enforces immutable patterns with readonly." --- # TypeScript Best Practices @@ -25,60 +25,26 @@ Production-grade TypeScript development with schema-first design, strict type sa | Branded types, utility types, code smells reference | [utilities.md](references/utilities.md) | | Common TypeScript patterns with examples | [patterns.md](references/patterns.md) | -## When to Use Each Guide +## Inline Example: Schema-First Pattern -### Schemas +```typescript +import { z } from "zod"; -Use [schemas.md](references/schemas.md) when you need: +// 1. Define schema at trust boundary +const UserSchema = z.object({ + id: z.string().brand<"UserId">(), + email: z.string().email(), + role: z.enum(["admin", "member"]), +}); -- Schema-first development patterns -- Decision framework: when schema is required vs optional -- Trust boundary identification -- Test data factory patterns with schema validation -- Examples of schema usage (API responses, business validation) +// 2. Derive type from schema +type User = z.infer; -### Types and Interfaces - -Use [types-interfaces.md](references/types-interfaces.md) when you need: - -- Type vs interface guidance -- The any vs unknown decision -- Type assertion best practices -- Strict mode configuration -- tsconfig.json settings - -### Immutability - -Use [immutability.md](references/immutability.md) when you need: - -- Immutability patterns (spread operators) -- Readonly modifiers -- Forbidden array methods reference -- Options objects vs positional parameters -- Boolean parameter anti-patterns -- Result types for error handling -- Early return patterns - -### Utilities - -Use [utilities.md](references/utilities.md) when you need: - -- Branded types for domain concepts -- Built-in utility types (Pick, Omit, Partial, etc.) -- Custom utility types -- Code smell reference tables - -### Patterns - -Use [patterns.md](references/patterns.md) when you need: - -- Schema-first examples at trust boundaries -- Internal type examples without schemas -- Schema with test factory patterns -- Result type for error handling -- Branded types for domain safety -- Immutable array operations -- Options object pattern +// 3. Validate at boundary, trust internally +function parseUser(raw: unknown): User { + return UserSchema.parse(raw); +} +``` ## Quick Reference: Decision Trees diff --git a/plugins/web/skills/react/SKILL.md b/plugins/web/skills/react/SKILL.md index afd16fc..ab94351 100644 --- a/plugins/web/skills/react/SKILL.md +++ b/plugins/web/skills/react/SKILL.md @@ -1,6 +1,6 @@ --- name: react -description: WHEN building React components/pages/apps; enforces scalable architecture, state management, API layer, performance patterns. +description: "WHEN building React components, pages, or apps with JSX/TSX; NOT for non-React frontends or server-only code; creates feature-based folder structures, implements hooks and state management with React Query/Zustand, builds API integration layers, applies code splitting and memoization, and enforces component composition patterns." --- # React Best Practices @@ -29,86 +29,34 @@ Production-grade React development with feature-based architecture, type-safe st | Testing pyramid and strategy | [testing-strategy.md](./references/testing-strategy.md) | | Project tooling standards | [project-standards.md](./references/project-standards.md) | -## When to Use Each Guide +## Canonical Feature Module -### Project Structure - -Use [project-structure.md](./references/project-structure.md) when you need: - -- Directory organization (app, features, components) -- Feature module structure -- Import architecture (unidirectional flow) -- ESLint boundary enforcement -- File naming conventions - -### Component Patterns - -Use [component-patterns.md](./references/component-patterns.md) when you need: - -- Colocation principles -- Composition over props patterns -- Wrapping third-party components -- Avoiding nested render functions - -### Compound Components - -Use [compound-components.md](./references/compound-components.md) when you need: - -- Multi-part components (Card, Accordion, etc.) -- Flexible composition patterns -- Semantic component structure - -### State Management - -Use [state-management.md](./references/state-management.md) when you need: - -- State category decisions (component, application, server cache) -- useState vs useReducer guidance -- Server cache with React Query -- State placement guidelines - -### API Layer - -Use [api-layer.md](./references/api-layer.md) when you need: - -- API client configuration -- Request structure (schema, fetcher, hook) -- Error handling (interceptors, boundaries) -- Security patterns (auth, sanitization, authorization) - -### Performance - -Use [performance.md](./references/performance.md) when you need: - -- Code splitting strategies -- State optimization -- Children optimization patterns -- Styling performance -- Image optimization - -### useEffect - -Use [useeffect.md](./references/useeffect.md) when you need: - -- When NOT to use useEffect (most cases) -- When useEffect IS appropriate (external systems) -- Dependency array rules -- Alternatives to useEffect - -### Testing Strategy - -Use [testing-strategy.md](./references/testing-strategy.md) when you need: +``` +src/features/auth/ +├── components/ +│ └── LoginForm.tsx # Feature-scoped component +├── hooks/ +│ └── useAuth.ts # Custom hook wrapping React Query +├── api/ +│ └── auth.ts # Schema → fetcher → hook +└── index.ts # Public API (barrel export) +``` -- Testing pyramid (prioritize integration over unit) -- What to test at each level (unit, integration, E2E) -- Testing Library principles (query by accessible names) +```tsx +// src/features/auth/api/auth.ts — schema-first API pattern +import { z } from "zod"; +import { useQuery } from "@tanstack/react-query"; +import { api } from "@/lib/api-client"; -### Project Standards +const UserSchema = z.object({ id: z.string(), email: z.string() }); +type User = z.infer; -Use [project-standards.md](./references/project-standards.md) when you need: +const getUser = async (id: string): Promise => + api.get(`/users/${id}`).then((r) => UserSchema.parse(r.data)); -- Required tooling (ESLint, Prettier, TypeScript, Husky) -- Pre-commit hook configuration +export const useUser = (id: string) => + useQuery({ queryKey: ["user", id], queryFn: () => getUser(id) }); +``` ## Quick Reference: Decision Trees diff --git a/plugins/web/skills/tdd/SKILL.md b/plugins/web/skills/tdd/SKILL.md index ec27daf..16b58ac 100644 --- a/plugins/web/skills/tdd/SKILL.md +++ b/plugins/web/skills/tdd/SKILL.md @@ -1,6 +1,6 @@ --- name: tdd -description: WHEN working in TDD Red-Green-Refactor; NOT ad-hoc coding; write tests first, add minimal code to green, then assess refactoring. +description: "WHEN working in test-driven development with Red-Green-Refactor; NOT for ad-hoc coding or retrofitting tests; writes failing test cases first, implements minimal passing code, assesses refactoring opportunities, uses factory functions for test data, and enforces behavior-focused testing through public APIs." --- # TDD Best Practices @@ -59,49 +59,23 @@ With tests green, assess whether refactoring would add value. | Critical violations, high priority issues, style improvements | [violations.md](references/violations.md) | | Behavior testing patterns, test naming, and organization | [patterns.md](references/patterns.md) | -## When to Use Each Guide +## Inline Example: One TDD Cycle -### Workflow Examples +```typescript +// RED — describe desired behavior +test("applies 10% discount for orders over $100", () => { + const order = createOrder({ items: [{ price: 150 }] }); + expect(calculateTotal(order)).toBe(135); +}); -Use [workflow-examples.md](references/workflow-examples.md) when you need: +// GREEN — minimal implementation +function calculateTotal(order: Order): number { + const subtotal = order.items.reduce((sum, i) => sum + i.price, 0); + return subtotal > 100 ? subtotal * 0.9 : subtotal; +} -- Complete TDD workflow examples (free shipping, payment validation) -- Step-by-step RED-GREEN-REFACTOR cycles -- When to refactor vs when to move on -- Refactoring assessment criteria -- Refactoring rules (commit first, preserve API, etc.) - -### Test Factories - -Use [test-factories.md](references/test-factories.md) when you need: - -- Factory function patterns with overrides -- Why factories beat let/beforeEach -- Composing factories for complex data -- Test organization by behavior -- No 1:1 mapping between tests and implementation -- Achieving 100% coverage through behavior testing - -### Violations - -Use [violations.md](references/violations.md) when you need: - -- Critical violations reference (production code without test, etc.) -- High priority issues (let/beforeEach, testing privates, etc.) -- Style issues (large files, duplication, magic values) -- Behavior vs implementation examples -- Quality gates checklist - -### Patterns - -Use [patterns.md](references/patterns.md) when you need: - -- Behavior-focused testing examples -- Testing through public APIs only -- Factory patterns with schema validation -- Composing factories for complex data -- Descriptive test naming patterns -- Test organization by business behavior +// REFACTOR — extract threshold/rate if needed, commit first +``` ## Quick Reference: Decision Trees diff --git a/pr-description.md b/pr-description.md new file mode 100644 index 0000000..1e5f6a3 --- /dev/null +++ b/pr-description.md @@ -0,0 +1,38 @@ +Hey @mintuz 👋 + +I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after: + +![score_card](./score_card.png) + +| Skill | Before | After | Change | +|-------|--------|-------|--------| +| react | 63% | 100% | +37% | +| typescript | 75% | 95% | +20% | +| tdd | 78% | 94% | +16% | +| swift-testing | 76% | 90% | +14% | +| commit-messages | 86% | 90% | +4% | + +
+Changes made + +**Description improvements (biggest impact):** +- **react**: Rewrote from category labels to concrete actions (creates feature-based folder structures, implements hooks/state management with React Query/Zustand, builds API integration layers), added explicit trigger terms (JSX/TSX, hooks) and NOT clause for non-React frontends +- **typescript**: Added specific capabilities (generates schema-first validation with z.infer, creates discriminated unions and branded types, defines type guards), added .ts/.tsx file extensions and Zod as trigger terms +- **tdd**: Expanded trigger terms to include "test-driven development", added concrete actions (writes failing test cases, implements minimal passing code, uses factory functions), added "retrofitting tests" to exclusion clause +- **swift-testing**: Added missing "what" capabilities (@Test functions, #expect/#require assertions, #expect(throws:) validation, @Suite structuring), expanded NOT clause to include Objective-C tests +- **commit-messages**: Added concrete actions (analyzes diffs, formats type(scope): subject lines, assesses commit scope for splitting) + +**Content improvements:** +- **react**: Removed redundant "When to Use Each Guide" section (duplicated the Quick Reference table), added a canonical feature module directory layout and executable schema-first API pattern with Zod + React Query +- **typescript**: Removed redundant "When to Use Each Guide" section, added inline schema-first pattern example with branded types and z.infer +- **tdd**: Removed redundant "When to Use Each Guide" section, added inline Red-Green-Refactor code example (discount calculation with factory function) +- **swift-testing**: Trimmed unnecessary "Works alongside XCTest" bullet from Core Concepts +- **commit-messages**: Removed "When to Use" and "Philosophy" sections (content Claude already knows) + +
+ +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 - [@yogesh-tessl](https://github.com/yogesh-tessl) - if you hit any snags. + +Thanks in advance 🙏 From 2b17f4845e2c908f30bff98c63784fd0f54d8944 Mon Sep 17 00:00:00 2001 From: Yogi Date: Wed, 1 Apr 2026 13:47:16 +0530 Subject: [PATCH 2/3] ci: add automated skill review for SKILL.md changes --- .github/workflows/skill-review.yml | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .github/workflows/skill-review.yml diff --git a/.github/workflows/skill-review.yml b/.github/workflows/skill-review.yml new file mode 100644 index 0000000..60c71a4 --- /dev/null +++ b/.github/workflows/skill-review.yml @@ -0,0 +1,13 @@ +name: Skill Review +on: + pull_request: + paths: ['**/SKILL.md'] +jobs: + review: + runs-on: ubuntu-latest + permissions: + pull-requests: write + contents: read + steps: + - uses: actions/checkout@v4 + - uses: tesslio/skill-review@22e928dd837202b2b1d1397e0114c92e0fae5ead # main \ No newline at end of file From 8318fa7c53bd78878a1ae3ac1ae96ae3f1d575b2 Mon Sep 17 00:00:00 2001 From: Yogi Date: Wed, 1 Apr 2026 13:52:26 +0530 Subject: [PATCH 3/3] Removed unwanted artifacts --- pr-description.md | 38 -------------------------------------- 1 file changed, 38 deletions(-) delete mode 100644 pr-description.md diff --git a/pr-description.md b/pr-description.md deleted file mode 100644 index 1e5f6a3..0000000 --- a/pr-description.md +++ /dev/null @@ -1,38 +0,0 @@ -Hey @mintuz 👋 - -I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after: - -![score_card](./score_card.png) - -| Skill | Before | After | Change | -|-------|--------|-------|--------| -| react | 63% | 100% | +37% | -| typescript | 75% | 95% | +20% | -| tdd | 78% | 94% | +16% | -| swift-testing | 76% | 90% | +14% | -| commit-messages | 86% | 90% | +4% | - -
-Changes made - -**Description improvements (biggest impact):** -- **react**: Rewrote from category labels to concrete actions (creates feature-based folder structures, implements hooks/state management with React Query/Zustand, builds API integration layers), added explicit trigger terms (JSX/TSX, hooks) and NOT clause for non-React frontends -- **typescript**: Added specific capabilities (generates schema-first validation with z.infer, creates discriminated unions and branded types, defines type guards), added .ts/.tsx file extensions and Zod as trigger terms -- **tdd**: Expanded trigger terms to include "test-driven development", added concrete actions (writes failing test cases, implements minimal passing code, uses factory functions), added "retrofitting tests" to exclusion clause -- **swift-testing**: Added missing "what" capabilities (@Test functions, #expect/#require assertions, #expect(throws:) validation, @Suite structuring), expanded NOT clause to include Objective-C tests -- **commit-messages**: Added concrete actions (analyzes diffs, formats type(scope): subject lines, assesses commit scope for splitting) - -**Content improvements:** -- **react**: Removed redundant "When to Use Each Guide" section (duplicated the Quick Reference table), added a canonical feature module directory layout and executable schema-first API pattern with Zod + React Query -- **typescript**: Removed redundant "When to Use Each Guide" section, added inline schema-first pattern example with branded types and z.infer -- **tdd**: Removed redundant "When to Use Each Guide" section, added inline Red-Green-Refactor code example (discount calculation with factory function) -- **swift-testing**: Trimmed unnecessary "Works alongside XCTest" bullet from Core Concepts -- **commit-messages**: Removed "When to Use" and "Philosophy" sections (content Claude already knows) - -
- -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 - [@yogesh-tessl](https://github.com/yogesh-tessl) - if you hit any snags. - -Thanks in advance 🙏