From eaf7d98bf3eed64ddbc1eb5390dd2b5284b0d667 Mon Sep 17 00:00:00 2001 From: Yogesh Rao Date: Wed, 15 Apr 2026 15:34:52 +0530 Subject: [PATCH 1/2] feat: improve skill scores for dotclaude MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hey @spejman 👋 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 | |-------|--------|-------|--------| | commit | 69% | 93% | +24% | | create-pr | 74% | 90% | +16% | | review-pr-comments | 63% | 83% | +20% | | test-coverage-improve | 77% | 85% | +8% | | fix-ci | 93% | 93% | +0% |
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 @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 🙏 --- skills/commit/SKILL.md | 69 ++++------- skills/create-pr/SKILL.md | 44 +++---- skills/fix-ci/SKILL.md | 22 +--- skills/review-pr-comments/SKILL.md | 158 +++++++++++--------------- skills/test-coverage-improve/SKILL.md | 32 ++---- 5 files changed, 115 insertions(+), 210 deletions(-) diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md index 201e2d5..838e9f8 100644 --- a/skills/commit/SKILL.md +++ b/skills/commit/SKILL.md @@ -1,73 +1,48 @@ --- name: commit -description: Create git commits from current changes using Conventional Commits format. Use when ready to commit staged or unstaged changes. +description: "Analyze diffs, stage files, and generate descriptive commit messages using Conventional Commits format. Use when ready to commit staged or unstaged changes, write a commit message, save changes, or check in code." allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git branch:*), Bash(git diff:*), Bash(git log:*) --- # Commit Changes -You are tasked with creating git commits for the changes made during this session. +This skill creates git commits for changes made during the current session. Commits are authored solely by the user with no AI attribution, co-author lines, or "Generated with Claude" messages. ## Process: -1. **Think about what changed:** - - Review the conversation history and understand what was accomplished +1. **Assess changes:** + - Review the conversation history to understand what was accomplished - Run `git status` to see current changes - Run `git diff` to understand the modifications - - Consider whether changes should be one commit or multiple logical commits + - Determine whether changes should be one commit or multiple logical commits -2. **Plan your commit(s):** - - Identify which files belong together - - Draft clear, descriptive commit messages - - Use imperative mood in commit messages - - Focus on why the changes were made, not just what +2. **Plan commits:** + - Identify which files belong together in logical, atomic groups + - Draft clear, descriptive commit messages focused on why the changes were made, not just what -3. **Add changes to the staging area:** - - Add files that you want to commit to the staging area using: `git add ""`. Always use the exact file path with quotes to avoid any errors. - - Confirm the changes were added to the staging area with `git status` +3. **Stage files:** + - Add files using: `git add ""` (always quote the exact file path) + - Confirm staging with `git status` -4. **Create commit with proper format:** +4. **Compose the commit message:** - Get current branch name: `git branch --show-current` - Extract issue number from branch name (first part before the dash) - Detect issue tracker: - If branch starts with `hey-` → Linear issue (format: `HEY-123`) - Otherwise → GitHub issue (format: `#123`) - - Follow **Conventional Commits** format: `[optional scope]: ` + - Format: `[optional scope]: ` - Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore` - - Description: Lowercase, imperative mood, no period at end - - Add issue reference at the end to create a link + - Description: lowercase, imperative mood ("add" not "added"), no period at end - Examples: - - Linear: `feat(dashboard): add comprehensive user dashboard component with profile management HEY-123` - - GitHub: `fix(media): handle multiple file types and size limits in upload validation #45` + - Linear: `feat(dashboard): add user dashboard with profile management HEY-123` + - GitHub: `fix(media): handle multiple file types in upload validation #45` - Linear: `refactor(auth): simplify token validation logic HEY-78` - GitHub: `docs(api): update authentication endpoint documentation #92` - - NEVER add "Generated with Claude Code" or similar AI attribution 5. **Execute commit:** - - Create the commit using: `git commit -m "FORMATTED_MESSAGE"` - - Confirm the commit was successful with `git status` + - Run: `git commit -m "FORMATTED_MESSAGE"` + - Confirm success with `git status` -6. **Repeat steps 3-5 for each change:** - - If changes should be committed separately, repeat steps 2-4 for each change. - - If changes should be committed in the same commit, repeat steps 2-4 for each change. - - Confirm there are no changes left to commit with `git status` - - If there are no changes, exit with `echo "No changes to commit"` - -## Important: -- **NEVER add co-author information or Claude attribution** -- Always follow **Conventional Commits** format: `[optional scope]: ` -- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore` -- Use imperative mood (e.g., "add" not "added" or "adds") -- Description should be lowercase and descriptive -- Issue reference format depends on tracker: - - Linear issues (branch `hey-X`): Use `HEY-123` format - - GitHub issues: Use `#123` format -- Commits should be authored solely by the user -- Do not include any "Generated with Claude" messages -- Do not add "Co-Authored-By" lines -- Write commit messages as if the user wrote them - -## Remember: -- You have the full context of what was done in this session -- Group related changes together -- Keep commits focused and atomic when possible -- The user trusts your judgment - they asked you to commit +6. **Multiple commits:** + - Repeat steps 3-5 for each additional logical commit + - Confirm no uncommitted changes remain with `git status` + - If nothing remains, exit with `echo "No changes to commit"` diff --git a/skills/create-pr/SKILL.md b/skills/create-pr/SKILL.md index 01c9400..0106c48 100644 --- a/skills/create-pr/SKILL.md +++ b/skills/create-pr/SKILL.md @@ -1,12 +1,12 @@ --- name: create-pr -description: Create a pull request from the current branch with quality checks. Use when changes are ready for review, after committing. +description: "Create a pull request from the current branch with lint, typecheck, and test validation. Use when changes are ready for review, after committing. Triggers: PR, open a PR, submit for review, merge request, push for review." allowed-tools: Bash(gh pr:*), Bash(git:*), Bash(npm test:*), Bash(npm run lint:*), Bash(npm run typecheck:*), Read, Glob, Grep --- # Create Pull Request -You are tasked with creating a pull request from the current branch. +The agent creates a pull request from the current branch, running lint, typecheck, and test validation before submission. ## Process: @@ -14,35 +14,35 @@ You are tasked with creating a pull request from the current branch. - Run `git status` to check for uncommitted changes - If there are uncommitted changes: - Show the uncommitted changes clearly - - Tell the user: "You have uncommitted changes. Please either:" + - Prompt the user: "You have uncommitted changes. Please either:" - "1. Exit and run `/commit` to commit your changes first (recommended)" - "2. Stash the changes temporarily with `git stash`" - "3. Continue anyway if these changes aren't meant for this PR" - - Wait for user's decision + - Wait for the user's decision - Run `git branch --show-current` to get the current branch name -- Verify we're not on main/master branch +- Verify the branch is not main/master ### 2. Code Quality Verification Run the following checks in parallel: -- `npm run lint` - Check for linting issues -- `npm run typecheck` - Check for TypeScript errors -- `npm test` - Run the test suite +- `npm run lint` - Linting issues +- `npm run typecheck` - TypeScript errors +- `npm test` - Test suite If any checks fail: -- Show me the errors -- Ask if I want to fix them before creating the PR -- If yes, help fix the issues and re-run the checks +- Display the errors +- Ask the user whether to fix them before creating the PR +- If yes, fix the issues and re-run the checks ### 3. Analyze Changes -- Run `git log origin/main..HEAD --oneline` to see commits that will be in the PR +- Run `git log origin/main..HEAD --oneline` to see commits included in the PR - Run `git diff origin/main...HEAD --stat` to see changed files summary - Run `git diff origin/main...HEAD` to understand the full changes - Identify the type of changes (feature, bugfix, refactor, chore, etc.) ### 4. Extract Context -- If branch name contains an issue number (e.g., "123-feature-name"), extract it -- Look for related issue by checking recent commits for issue references -- Understand the purpose and scope of the changes +- If the branch name contains an issue number (e.g., "123-feature-name"), extract it +- Look for related issues by checking recent commits for issue references +- Determine the purpose and scope of the changes ### 5. Draft PR Description Create a comprehensive PR description with: @@ -78,13 +78,12 @@ Closes #[issue-number] (if applicable) ``` ### 6. Review with User -- Show me the draft PR title and description +- Show the draft PR title and description - Ask: "Does this look good? Any changes needed?" - Wait for approval or make requested changes ### 7. Push Changes - Run `git push -u origin HEAD` to push the branch to remote -- This ensures the branch exists on GitHub before creating the PR ### 8. Create the PR After approval, create the PR using: @@ -99,25 +98,16 @@ gh pr create \ Note: PRs are created as drafts by default to allow for final review before requesting feedback. ### 9. Post-Creation -- Show me the PR URL +- Display the PR URL - Run `gh pr view --web` to open the PR in browser (optional) - Suggest next steps: - Request reviews from team members - Add labels if needed - Link to project board if applicable -## Important Notes: -- Always ensure all tests pass before creating PR -- Use conventional commit style for PR titles when possible -- Include issue numbers for automatic linking -- Be thorough in the description - it helps reviewers -- Check for any .env or sensitive data in the diff - ## PR Title Format Examples: - `feat: Add user authentication system` - `fix: Resolve date parsing issue in calendar` - `refactor: Improve appointment service performance` - `chore: Update dependencies to latest versions` - `docs: Add API documentation for new endpoints` - -Remember: A good PR description saves review time and provides context for future reference. diff --git a/skills/fix-ci/SKILL.md b/skills/fix-ci/SKILL.md index 7f4d612..4421989 100644 --- a/skills/fix-ci/SKILL.md +++ b/skills/fix-ci/SKILL.md @@ -4,7 +4,7 @@ description: "Run Prisma generate, lint (auto-fix), typecheck, and tests; iterat allowed-tools: Bash(npx prisma generate:*), Bash(npm run db:generate:*), Bash(npm run lint:*), Bash(npm run lint:fix:*), Bash(npm run typecheck:*), Bash(npm test:*) --- -You are running in a Next.js + TypeScript project. +This skill operates in a Next.js + TypeScript project. ## Goal @@ -14,7 +14,7 @@ Get the repo into a clean state by: 3) passing typecheck, 4) passing tests. -Then produce a short status report (OK/FAIL for each step) plus any follow-ups I should do. +Then produce a short status report (OK/FAIL for each step) plus any recommended follow-ups. ## What to do @@ -48,21 +48,3 @@ Follow this sequence. After each step, if it fails, apply minimal, safe fixes an Lint: [OK|FAIL] (counts, key rules fixed) Typecheck: [OK|FAIL] (top 1–2 culprits) Tests: [OK|FAIL] (failing suites & test names) - - -## Runbook (you may run these as needed) - -- Prisma: - - `npm run db:generate` - - `npx prisma generate` - -- Lint: - - `npm run lint` - - `npm run lint:fix` - -- Types: - - `npm run typecheck` - -- Tests: - - `npm test` - diff --git a/skills/review-pr-comments/SKILL.md b/skills/review-pr-comments/SKILL.md index cf1dfd8..8ea84ca 100644 --- a/skills/review-pr-comments/SKILL.md +++ b/skills/review-pr-comments/SKILL.md @@ -1,124 +1,100 @@ --- name: review-pr-comments -description: Review and apply Claude's PR feedback interactively. Use after receiving a Claude Code review on a PR to triage and implement feedback. +description: "Review pull request code review comments and address feedback on PR #$ARGUMENT$. The agent resolves review comments, applies suggested code changes, dismisses or acknowledges feedback, and documents decisions for the specified pull request." allowed-tools: Bash(gh pr:*), Bash(gh api:*), Bash(git checkout:*), Bash(git pull:*), Read, Edit, MultiEdit, Write --- -# GitHub PR Workflow for PR #$ARGUMENT$ +# Review PR Comments for PR #$ARGUMENT$ ## Primary Task -Retrieve the latest Claude review comment from the specified pull request and initiate an interactive conversation to help me decide which feedback items to apply. +The agent retrieves the latest review comments from PR #$ARGUMENT$, categorizes each feedback item, and guides the user through triaging and implementing changes. ## Step-by-Step Instructions -### 1. Get PR Review Information -- Fetch the latest Claude review comment from the specified PR -- Parse and organize the feedback items clearly -- Identify the scope and nature of each suggestion +### 1. Fetch PR Review Comments -### 2. Get last changes and move to branch -- Go to main branch and fetch the latest changes. +The agent fetches all review comments and organizes them by category. ```bash -git checkout main -git pull --rebase +# Get all review comments with full context +gh api repos/{owner}/{repo}/pulls/$ARGUMENT$/reviews --jq '.[].body' + +# Get inline review comments +gh api repos/{owner}/{repo}/pulls/$ARGUMENT$/comments --jq '.[] | {path: .path, line: .diff_hunk, body: .body}' + +# View PR details and all comments +gh pr view $ARGUMENT$ --comments ``` -- Checkout to the pull request branch. +**Validation**: Confirm the API calls returned valid JSON and at least one review exists. If no reviews are found, notify the user and stop. + +### 2. Check Out the PR Branch + +The agent checks out the PR branch directly: ```bash -git checkout PULL_REQUEST_BRANCH_NAME +gh pr checkout $ARGUMENT$ ``` -### 3. Present Feedback Summary -Display the review feedback in a structured format: -- **Critical Issues**: Security, bugs, or breaking changes -- **Code Quality**: Performance, maintainability, best practices -- **Style/Convention**: Formatting, naming, documentation -- **Suggestions**: Nice-to-have improvements or alternatives - -### 4. Interactive Discussion Framework -For each feedback item, ask me: -- Do you agree with this feedback? (Yes/No/Partially) -- What's your reasoning for applying or not applying it? -- Are there any constraints or context I should consider? -- Would you like me to help implement this change? - -### 5. Decision Tracking -Keep track of: -- ✅ Feedback to implement -- ❌ Feedback to skip (with reasoning) -- ⚠️ Feedback that needs clarification -- 🔄 Feedback requiring further discussion - -### 6. Implementation Planning -For accepted feedback: -- Prioritize changes by impact and effort -- Identify dependencies between changes -- Suggest implementation order -- Offer to help with code modifications - -### 7. Document Decisions in PR -Write a summary comment in the PR that includes: -- Overview of review feedback received -- Decision rationale for each feedback item -- List of changes that will be implemented -- List of feedback items declined (with reasons) -- Timeline or next steps for implementation - -## GitHub CLI Commands Reference - -### Viewing PR Reviews -```bash -# List all reviews for a PR -gh pr review list $ARGUMENT$ +**Validation**: Confirm the checkout succeeded by verifying the current branch matches the PR branch name (`git branch --show-current`). -# View specific review details -gh pr view $ARGUMENT$ --comments +### 3. Categorize and Present Feedback -# Get PR review comments in JSON format -gh api repos/:owner/:repo/pulls/[PR_NUMBER]/reviews -``` +The agent organizes each feedback item into one of these categories: + +- **Critical**: Security vulnerabilities, bugs, or breaking changes requiring immediate action +- **Code Quality**: Performance improvements, maintainability, or best-practice violations +- **Style/Convention**: Formatting, naming, or documentation issues +- **Suggestions**: Optional improvements or alternative approaches + +For each item, the agent presents: the category, the file and line affected, the reviewer's comment, and a recommended action. + +### 4. Plan and Implement Accepted Changes + +For feedback the user accepts, the agent: + +1. Prioritizes changes by impact (critical first) and groups related changes +2. Identifies dependencies between changes to determine safe ordering +3. Applies each change using Edit/MultiEdit, verifying the modification compiles or passes lint where applicable +4. Stages and commits changes with clear messages referencing the review feedback + +### 5. Document Decisions in the PR + +The agent posts a summary comment on PR #$ARGUMENT$ covering: + +- Each feedback item and whether it was accepted, declined, or deferred +- Rationale for declined items +- List of commits implementing accepted changes -### Commenting on PRs ```bash -# Add a general comment to PR -gh pr comment $ARGUMENT$ --body "Your comment text" +# Post the decision summary as a PR comment +gh pr comment $ARGUMENT$ --body-file decisions.md +``` -# Add a comment from a file -gh pr comment $ARGUMENT$ --body-file comment.md +## GitHub CLI Reference -# Reply to a specific review thread -gh api repos/:owner/:repo/pulls/[PR_NUMBER]/reviews/[REVIEW_ID]/replies \ +### Responding to Reviews +```bash +# Reply to a specific review comment thread +gh api repos/{owner}/{repo}/pulls/$ARGUMENT$/comments/{comment_id}/replies \ --method POST \ - --field body="Reply text" + --field body="Response text" + +# Post a general PR comment +gh pr comment $ARGUMENT$ --body "Comment text" + +# Post a comment from a file +gh pr comment $ARGUMENT$ --body-file comment.md ``` -### Getting PR Information +### Inspecting the PR ```bash -# View PR details +# View PR details and status gh pr view $ARGUMENT$ -# Get PR status and checks -gh pr status - -# List all PRs -gh pr list - -# Get PR diff +# View the PR diff gh pr diff $ARGUMENT$ -``` -### Additional Considerations -- Consider the PR's context (feature branch, hotfix, etc.) -- Respect team conventions and existing patterns -- Balance code quality with practical constraints - -## Expected Workflow -1. Fetch and analyze the Claude review -2. Present organized feedback summary -3. Discuss each item interactively -4. Create action plan for accepted changes -5. Offer implementation assistance -6. Write summary comment in PR documenting all decisions -7. Update PR based on decisions +# Check PR status and CI checks +gh pr checks $ARGUMENT$ +``` diff --git a/skills/test-coverage-improve/SKILL.md b/skills/test-coverage-improve/SKILL.md index cbd653d..fa171d0 100644 --- a/skills/test-coverage-improve/SKILL.md +++ b/skills/test-coverage-improve/SKILL.md @@ -1,14 +1,14 @@ --- name: test-coverage-improve -description: Analyze and improve test coverage for the codebase targeting 80%+. Use when coverage is low or after adding new untested code. +description: "Identify uncovered code paths, generate unit tests, and produce coverage reports targeting 80%+. Use when code coverage is low, unit tests are missing, after adding new untested code, or when a coverage report is needed." allowed-tools: Bash(npm test:*), Task, Read, Edit, MultiEdit, Write, Glob, Grep --- -# Test Coverage Enhancement Task +# Test Coverage Enhancement -Please analyze and improve the test coverage for this codebase following the established testing strategy. Run `npm test -- --coverage` to get current coverage and target ≥80% coverage. +The agent analyzes and improves test coverage for this codebase following the established testing strategy. It runs `npm test -- --coverage` to get current coverage and targets ≥80% coverage. -Use parallel subagents to run tests and improve coverage. +Parallel subagents should be used to run tests and improve coverage. ## 1. Coverage Analysis & Strategy - Run `npm test -- --coverage` to identify gaps in coverage @@ -111,24 +111,7 @@ expect(mockUtil.inspect).toHaveBeenCalledWith(testObj, { // process.env.NODE_ENV = "development"; // TypeScript error ``` -## 6. Test Quality Standards - -### Arrange-Act-Assert Structure -- **Arrange:** Set up test data and mocks -- **Act:** Execute the function/behavior being tested -- **Assert:** Verify expected outcomes and side effects - -### Descriptive Naming -- Use clear `describe` blocks that explain the component/function context -- Write `it`/`test` descriptions that read like specifications -- Group related tests logically - -### Mock Cleanup -- Always restore spies and mocks in `afterAll` or `afterEach` -- Isolate tests to avoid shared state -- Clear mocks between tests when needed - -## 7. Implementation Checklist +## 6. Implementation Checklist For each file with coverage gaps: - [ ] Check if it's a repository (skip if yes) @@ -136,12 +119,11 @@ For each file with coverage gaps: - [ ] Mock all external dependencies appropriately - [ ] Write tests covering happy path and edge cases - [ ] Use Spanish business context in test data -- [ ] Follow AAA pattern with clear descriptions - [ ] Test error handling and boundary conditions - [ ] Verify mock calls with expected parameters - [ ] Clean up mocks and spies properly -## 8. Coverage Verification +## 7. Coverage Verification After implementing tests: - Run `npm test -- --coverage` to verify improvement @@ -149,4 +131,4 @@ After implementing tests: - Focus on statement, branch, and function coverage - Address any remaining critical gaps -Start by analyzing current coverage, then systematically address gaps while strictly following the mocking strategy and using realistic Spanish business data. +The agent starts by analyzing current coverage, then systematically addresses gaps while strictly following the mocking strategy and using realistic Spanish business data. From 5f9991ec5f3391aadd67d35b4cb9b66d6709fb6c Mon Sep 17 00:00:00 2001 From: Yogesh Rao Date: Wed, 15 Apr 2026 15:41:50 +0530 Subject: [PATCH 2/2] ci: add skill-review GitHub Action for automated skill review on PRs --- .github/workflows/skill-preview.yml | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .github/workflows/skill-preview.yml diff --git a/.github/workflows/skill-preview.yml b/.github/workflows/skill-preview.yml new file mode 100644 index 0000000..60c71a4 --- /dev/null +++ b/.github/workflows/skill-preview.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