Skip to content
Fenil's Notes

Skills — Real-World Examples Library

Every skill below is a complete, drop-in .claude/skills/<name>/SKILL.md file you can use in a real project.

Skill 1: Full Quality Check

Section titled “Skill 1: Full Quality Check”

Use case: Run before every commit. Ensures nothing broken ships.

.claude/skills/check/SKILL.md:

---
title: "Check"
description: "Run lint, type check, and tests — report any failures"
---


# Quality Check


Run all quality checks in order. Stop and report clearly on first failure.


1. Run: `npm run lint`
   - If failures: show exactly which files failed and why
   - Attempt auto-fix: `npm run lint -- --fix`
   - Re-run lint to confirm fixed


2. Run: `npx tsc --noEmit`
   - If failures: show each type error with file and line number
   - Fix type errors before proceeding


3. Run: `npm test`
   - If failures: show which tests failed and the assertion that failed
   - Do NOT fix failing tests by deleting them


4. If all pass: report "All checks passed ✓" with a summary count
5. If any fail: list all failures with suggested fixes

Invoke: /check

Skill 2: Deploy with Safety Gates

Section titled “Skill 2: Deploy with Safety Gates”

Use case: Deploy to any environment, with environment-specific checks.

.claude/skills/deploy/SKILL.md:

---
title: "Deploy"
description: "Deploy to staging or production with safety checks"
require-approval: true
---


# Deploy to $ARGUMENTS


## Validation
First, validate the target environment:
- $ARGUMENTS must be exactly "staging" or "production"
- If invalid, stop immediately and explain valid options


## Pre-deploy checks
1. Confirm branch: `git branch --show-current`
   - For production: must be on `main`
   - For staging: any branch is ok


2. Check for uncommitted changes: `git status`
   - If dirty working tree: stop and ask user to commit or stash


3. Run: `npm run lint` — must pass
4. Run: `npm test` — must pass
   - For production: run full suite `npm run test:all`
   - For staging: standard suite `npm test`


## Build
5. Run: `npm run build`
   - If build fails: stop, show the build error


## Deploy
6. Run: `npm run deploy:$ARGUMENTS`


## Post-deploy verification
7. Run: `npm run smoke-test:$ARGUMENTS`
   - If smoke test fails: immediately run `npm run deploy:rollback:$ARGUMENTS`
   - Notify: "Deployment failed — rolled back automatically"


## Success
8. Print:
   - Deployment URL
   - Git commit hash deployed
   - Timestamp
   - "Deployment to $ARGUMENTS successful ✓"

Invoke: /deploy staging or /deploy production

Skill 3: Open a Pull Request

Section titled “Skill 3: Open a Pull Request”

Use case: Commit current work and open a well-described PR in one command.

.claude/skills/open-pr/SKILL.md:

---
title: "Open PR"
description: "Commit changes, push, and open a pull request"
---


# Open PR: $ARGUMENTS


## Pre-checks
1. Check for changes: `git status`
   - If nothing to commit: report "No changes to commit"


2. Run: `npm run lint` — fix any issues before committing
3. Run: `npm test` — abort if tests fail


## Commit and push
4. Stage all changes: `git add -A`
5. Show what will be committed: `git diff --staged --stat`
6. Commit: `git commit -m "$ARGUMENTS"`
7. Push: `git push -u origin HEAD`


## Open PR
8. Get the current branch name: `git branch --show-current`
9. Read `.github/pull_request_template.md` if it exists
10. Create PR with `gh pr create`:
    - Title: $ARGUMENTS
    - Body: summary of changes made, tests added, how to test
    - Auto-fill the PR template if one exists


11. Print the PR URL

Invoke: /open-pr "feat: add rate limiting to API endpoints"

Skill 4: New Feature (TDD Scaffold)

Section titled “Skill 4: New Feature (TDD Scaffold)”

Use case: Start a new feature the right way — plan, test, implement.

.claude/skills/new-feature/SKILL.md:

---
title: "New Feature"
description: "Scaffold a new feature using test-driven development"
---


# New Feature: $ARGUMENTS


## Phase 1: Explore (read-only, do NOT edit yet)
Read to understand the codebase before writing anything:
- Find the most similar existing feature in `src/`
- Read its implementation, test file, and how it's exported
- Read `CLAUDE.md` for any constraints


## Phase 2: Plan
Write out exactly:
- Which new files you will create
- Which existing files you will modify
- The function signatures / API design


Show the plan to the user. Do not proceed until they confirm.


## Phase 3: Write failing tests first
- Create test file: `src/__tests__/$ARGUMENTS.test.ts`
- Write tests for: happy path, edge cases, error cases
- Run: `npm test src/__tests__/$ARGUMENTS.test.ts`
- Confirm tests FAIL (expected — implementation doesn't exist yet)


## Phase 4: Implement
- Create: `src/$ARGUMENTS.ts`
- Implement until all tests pass
- Run: `npm test src/__tests__/$ARGUMENTS.test.ts` after each function


## Phase 5: Integration
- Export from barrel: `src/index.ts`
- Run full test suite: `npm test`
- Run: `npm run lint`
- Run: `npx tsc --noEmit`


## Phase 6: Commit
- `git add -A`
- `git commit -m "feat: $ARGUMENTS"`

Invoke: /new-feature user-subscription-management

Skill 5: Database Migration

Section titled “Skill 5: Database Migration”

Use case: Add or change a database column safely.

.claude/skills/db-migrate/SKILL.md:

---
title: "DB Migrate"
description: "Create and apply a Prisma database migration"
---


# Database Migration: $ARGUMENTS


## Safety checks
1. Confirm current git status: `git status`
2. Check current migration state: `npx prisma migrate status`
3. If pending migrations exist: apply them first before creating new one


## Plan the schema change
Read `prisma/schema.prisma` and describe:
- Exactly what change is needed
- Impact on existing data
- Whether a default value is needed for existing rows
- Whether the change is reversible


Show the plan. Wait for user approval.


## Make the change
4. Edit `prisma/schema.prisma` with the change
5. Generate migration: `npx prisma migrate dev --name $ARGUMENTS`
6. Review the generated SQL in `prisma/migrations/` — confirm it looks right


## Update application code
7. Search for any code that references the changed fields: grep for field names
8. Update any affected TypeScript types, validators, or queries


## Verify
9. Run: `npm test` — ensure nothing broke
10. Run: `npx prisma studio` and describe the expected table structure


## RULES
- NEVER manually edit a migration file that has already been applied
- ALWAYS include a default value for new NOT NULL columns on existing tables
- ALWAYS run tests after migrating

Invoke: /db-migrate add-subscription-tier-to-users

Skill 6: Fix Failing Tests

Section titled “Skill 6: Fix Failing Tests”

Use case: Tests are red, fix them without cheating.

.claude/skills/fix-tests/SKILL.md:

---
title: "Fix Tests"
description: "Diagnose and fix failing tests without deleting them"
---


# Fix Failing Tests


## Diagnose
1. Run: `npm test -- --reporter=verbose 2>&1 | head -100`
   - Show which tests are failing
   - Show the exact assertion error for each


2. For each failing test:
   - Read the test file
   - Read the source file being tested
   - Determine: is this a bug in the code, or an outdated test?


## Rules (CRITICAL)
- NEVER fix a test by deleting it or weakening the assertion
- NEVER change `expect(result).toBe(5)` to `expect(result).toBeDefined()`
- If the test is wrong: explain WHY and get user approval before changing it
- If the code is wrong: fix the code


## Fix
3. Fix the root cause (in source code, not in test)
4. Run the specific failing test: `npm test -- --testPathPattern <file>`
5. Confirm it passes
6. Run full test suite: `npm test`
7. Confirm nothing else broke


## Report
Show a before/after summary:
- Tests that were failing → now passing
- Root cause of each failure
- What was changed to fix it

Invoke: /fix-tests

Skill 7: Dependency Upgrade

Section titled “Skill 7: Dependency Upgrade”

Use case: Safely upgrade one package at a time.

.claude/skills/upgrade/SKILL.md:

---
title: "Upgrade"
description: "Safely upgrade a dependency and verify nothing broke"
---


# Upgrade: $ARGUMENTS


## Research
1. Check current version: `npm list $ARGUMENTS`
2. Check latest: `npm info $ARGUMENTS version`
3. Fetch changelog or migration guide for the version gap


## Check for breaking changes
Read the changelog. If there are breaking changes:
- List every breaking change
- List which files in the project are affected
- Show the migration steps


Ask user: "There are breaking changes. Proceed?"


## Upgrade
4. Run: `npm install $ARGUMENTS@latest`
5. Run: `npx tsc --noEmit` — check for type errors from the upgrade
6. Run: `npm test` — check for test failures


## Fix any breakage
If tests or types fail:
- Apply the migration steps from the changelog
- Re-run tests after each fix


## Commit
7. `git add package.json package-lock.json`
8. `git commit -m "chore: upgrade $ARGUMENTS to $(npm list $ARGUMENTS --depth=0 | grep $ARGUMENTS)"`

Invoke: /upgrade stripe

Skill 8: Code Review (Self-Review)

Section titled “Skill 8: Code Review (Self-Review)”

Use case: Review your own changes before opening a PR.

.claude/skills/self-review/SKILL.md:

---
title: "Self Review"
description: "Review current changes as if you were a senior code reviewer"
---


# Self Review


## Get the diff
1. Run: `git diff main...HEAD`
2. Run: `git log main...HEAD --oneline`


## Review each changed file for:


### Correctness
- Logic errors and off-by-one errors
- Unhandled edge cases (null, empty, large inputs)
- Race conditions in async code
- Missing error handling


### Security
- User input used without validation or sanitization
- SQL/NoSQL injection risks
- Exposed secrets or sensitive data in logs or responses
- Missing authorization checks


### Performance
- N+1 queries (loops that each make a DB call)
- Missing database indexes for new queries
- Large objects loaded into memory unnecessarily


### Maintainability
- Functions longer than 40 lines (should be split)
- Variables named `data`, `result`, `temp` (unclear names)
- Missing tests for new logic
- Deviations from project conventions in CLAUDE.md


## Output
Format each finding:
**Issue:** what's wrong
**File:** path:line
**Severity:** critical / high / medium / low
**Fix:** specific suggestion


End with: "X critical, Y high, Z medium issues found."

Invoke: /self-review

Skill 9: Onboard to Codebase

Section titled “Skill 9: Onboard to Codebase”

Use case: First session on a new project — build understanding fast.

.claude/skills/onboard/SKILL.md:

---
title: "Onboard"
description: "Explore and explain this codebase to a new developer"
disable-model-invocation: true
---


# Codebase Onboarding


## What to explore
Read and understand:
1. `package.json` — dependencies, scripts, project metadata
2. `README.md` — project description
3. Main entry point (index.ts, main.ts, app.ts, server.ts)
4. Directory structure: `ls -la src/` and subdirectories
5. One example of each main entity type (model, service, handler, test)


## What to produce
Write a clear explanation covering:


### What this project does
One paragraph summary.


### Tech stack
List: language, framework, database, test framework, build tool.


### Directory structure
Explain each top-level directory in `src/` in one sentence.


### Data flow
Trace one request from entry point to response. Show the layers.


### Key files to know
List 5-10 files that are essential to understand.


### How to run it locally
Exact commands in order.


### Common patterns
2-3 patterns used throughout (e.g. repository pattern, error handling style).


### Gotchas
1-3 non-obvious things a new dev needs to know.

Invoke: /onboard

Skill 10: Generate API Documentation

Section titled “Skill 10: Generate API Documentation”

Use case: Keep docs in sync with code.

.claude/skills/gen-docs/SKILL.md:

---
title: "Gen Docs"
description: "Generate or update API documentation from source code"
---


# Generate API Docs


## Discover all routes
1. Run: `grep -r "router\.\|app\." src/routes/ src/handlers/ --include="*.ts" -l`
2. Read each route file


## For each endpoint, document:
- Method and path: `POST /api/users`
- Description: what it does
- Authentication: required or not
- Request body: schema with types and which fields are required
- Query parameters: if any
- Response: success shape and status code
- Error responses: each possible error code and message


## Output format
Write to `docs/api.md` in this format:


### POST /api/users
Create a new user account.


**Auth:** Not required


**Request body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | Must be valid email |
| name | string | Yes | 1-100 characters |
| role | enum | No | "user" (default) or "admin" |


**Response 201:**
```json
{ "id": "uuid", "email": "...", "name": "...", "createdAt": "..." }

Errors:

  • 400 — validation error
  • 409 — email already exists

After writing, run: git diff docs/api.md and show what changed.

Invoke: `/gen-docs`




## 🧠 Quick Recall


- **Trick:** "Steal all 10, adapt 2 today."


## 👨‍🏫 Teach It


- **Do:** assign each learner one skill to adapt to their own repo before next session.
- **They'll trip on:** reading without shipping — a skill isn't learned until it runs.


---


**Learning path:** ⬅ [21-skills-step-by-step.md](/21-skills-step-by-step/) · [Index](/readme/) · ➡ [23-hooks.md](/23-hooks/)

Written by Fenil Patel