Customization Guide

Customize Skills for
Your Project

Every skill is designed to be adapted. Fill in your tech stack, add project-specific rules, and create custom skills that match how your team actually works.

Project Configuration Create Custom Skills
Core Concept

How Project Configuration Works

Every skill has a Project Configuration section with HTML comment placeholders. Replace these with your actual project details, and the LLM reads them before every task.

1
🧠
Expert Persona
unique per skill
2
⚙️
Project Configuration
you customize this
3
📜
Domain-Specific Rules
6 per skill
4
🛠️
Step-by-Step Workflow
with flow diagrams
5
✅
Quality Checklists
before you ship

Before vs After: Project Configuration

Before — Default Placeholders
### API Framework <!-- Example: Express.js + TypeScript, Zod for validation, JWT auth middleware --> ### URL Convention <!-- Example: /api/v1/{resource}, plural nouns, kebab-case --> ### Auth Pattern <!-- Example: Bearer JWT in Authorization header --> ### Error Response Format <!-- Example: { error: { code: string, message: string } } -->
After — Filled In For Your Project
### API Framework Express.js + TypeScript, Zod validation, Prisma ORM, JWT auth middleware ### URL Convention /api/v1/{resource}, plural nouns, kebab-case, tenant-scoped routes ### Auth Pattern Bearer JWT in Authorization header, role-based middleware (owner, admin, manager, learner), tenant isolation ### Error Response Format { error: { code: string, message: string, details?: object }, statusCode: number }
Why this matters: When you fill in your Project Configuration, the LLM reads it before every task. Instead of generating generic Express.js boilerplate, it generates code that matches your actual patterns — correct auth middleware, correct error format, correct URL structure.

✦ Step-by-Step: Customize a Skill

Follow these four steps to customize any skill for your project. It takes about 5 minutes per skill.

Step 1
Open
Find the SKILL.md file
→
Step 2
Find
Project Configuration
→
Step 3
Replace
Comments with details
→
Step 4
Save
LLM reads it on every task
1

Open the SKILL.md file

Navigate to the skill you want to customize. For example, if you're customizing the API Design skill:

.claude/skills/api-design/SKILL.md
2

Find the Project Configuration section

Scroll to the ## Project Configuration heading. You'll see sub-headings with HTML comments like <!-- Example: ... -->. These are your placeholders.

3

Replace HTML comments with your project details

Delete the HTML comment and type your actual project configuration. Be specific — include framework names, library versions, naming conventions, and file paths. The more detail you provide, the better the LLM output.

# Before: ### API Framework <!-- Example: Express.js + TypeScript, Zod for validation --> # After: ### API Framework Express.js + TypeScript, Zod validation on all request bodies, Prisma ORM for database access, Winston for logging, JWT auth middleware on all protected routes
4

Save — the LLM reads it before every task

That's it. The next time the skill is invoked, the LLM will read your project configuration and produce output that matches your actual codebase. No generic boilerplate.

Full Example

Example: Customizing api-design

Here's a complete before/after of the api-design skill's Project Configuration filled in for a real SaaS project.

Default (from repo)
## Project Configuration ### API Framework <!-- Example: Express.js + TypeScript, Zod for validation, JWT auth middleware --> ### URL Convention <!-- Example: /api/v1/{resource}, plural nouns, kebab-case --> ### Auth Pattern <!-- Example: Bearer JWT in Authorization header, role-based middleware --> ### Pagination Pattern <!-- Example: Cursor-based with ?cursor=&limit=, or offset ?page=&pageSize= --> ### Error Response Format <!-- Example: { error: { code: string, message: string, details?: object } } --> ### Existing API Reference <!-- Example: See /specs/api-contracts.md for current endpoints -->
Customized for a SaaS LMS project
## Project Configuration ### API Framework Express.js + TypeScript, Zod validation on all request/response schemas, Prisma ORM, JWT refresh tokens, Winston structured logging ### URL Convention /api/v1/{resource}, plural nouns, kebab-case. All routes tenant-scoped via tenantMiddleware. No /api/v2. ### Auth Pattern Bearer JWT (Authorization header). Roles: superadmin, owner, admin, manager, learner. tenantMiddleware injects tenant_id on every request. ### Pagination Pattern Offset-based: ?page=1&pageSize=20. Response: { items: T[], total: number, page: number, pageSize: number }. ### Error Response Format throw new ApiError(statusCode, message). Response: { error: { code: string, message: string, details?: object } } ### Existing API Reference See /specs/api-contracts.md for current endpoints. Backend: src/backend/src/ routes/. Use existing route patterns.

✦ Customizing Domain-Specific Rules

Each skill has 6 mandatory rules that are unique to its domain. You can add project-specific sub-rules under any of these to enforce your team's conventions.

1
Understand the 6 Rules
Every skill's Common Rules section has exactly 6 domain-specific rules. For example, the code-review skill has rules like "Check error handling" and "Verify component reuse."
2
Add Sub-Rules
Under each rule, add project-specific checks. If rule 3 says "Check security patterns," add sub-items like "Verify all Prisma queries include tenant_id filter."
3
Add Checklist Items
Every time a bug slips through that a skill should have caught, add a new checklist item. Your skills get smarter over time and prevent repeat mistakes.
4
Keep Rules Actionable
Every rule and sub-rule should be a verifiable check. "Write good code" is not actionable. "Verify all new API routes use tenantMiddleware" is actionable.

Example: Adding project-specific checklist items to code-review

# Added checklist items for our project: - [ ] Check that all new API routes use the tenantMiddleware - [ ] Verify Prisma queries include tenant_id filter - [ ] Confirm new components reuse existing UI primitives from /components/ui/ - [ ] Check that new pages follow the existing layout pattern - [ ] Verify error responses use the standard ApiError format - [ ] Ensure new environment variables are added to .env.example
Pro tip: After every production incident or escaped bug, add a checklist item to the relevant skill. Over 6 months your skills will capture every hard lesson your team has learned.

✦ Creating Custom Skills

You can create custom skills for any repeatable process in your team's workflow. Follow the same structure as the built-in skills for best results.

Step 1
Identify
Find a repeated task
→
Step 2
Structure
Follow the template
→
Step 3
Write
Steps + checklists
→
Step 4
Test
Use with real work
→
Step 5
Refine
Iterate and improve

The 5 Sections Every Skill Needs

Follow this structure to create skills that work consistently with any LLM tool.

1

Expert Persona

Define who the LLM becomes when this skill is active. Give it a specific title, years of experience, and domain expertise. The more specific the persona, the better the output quality.

## Your Expertise You are a **Senior Database Migration Specialist** with 15+ years managing schema changes across PostgreSQL, MySQL, and MongoDB. You've migrated databases with 500M+ rows without downtime at fintech and healthcare companies.
2

Project Configuration

Add customizable sections with HTML comment placeholders. This lets anyone using the skill fill in their project-specific details.

## Project Configuration ### Database <!-- Example: PostgreSQL 15, Prisma ORM, UUID primary keys --> ### Migration Tool <!-- Example: Prisma Migrate, or raw SQL with Flyway --> ### Rollback Strategy <!-- Example: Down migrations required, tested in staging first -->
3

Domain-Specific Rules (6 rules)

Write exactly 6 mandatory rules for this skill's domain. Each rule should be battle-tested and specific — not generic advice. These are the non-negotiable checks the LLM must follow every time.

4

Step-by-Step Workflow

Break the process into clear, sequential steps. Each step should have a single focus. Include flow diagrams for complex decision points. The LLM follows these steps in order.

5

Quality Checklists

Add a checklist of items to verify before the task is considered complete. These catch issues that the workflow steps might miss. Update the checklist whenever a new failure mode is discovered.

## Final Checklist - [ ] Migration runs cleanly on empty database - [ ] Migration runs cleanly on production snapshot - [ ] Rollback/down migration tested - [ ] No data loss in existing rows - [ ] Indexes added for new foreign keys - [ ] Prisma client regenerated without errors

Complete Skill Template

Use this template as a starting point for any new skill.

--- name: your-skill-name description: "One-line summary of what this skill does and when to use it." --- # Skill Title — Short Description Takes {input} and produces {output}. --- ## Your Expertise You are a **{Title}** with {N}+ years of experience in {domain}. You've {specific accomplishment that builds credibility}. --- ## Project Configuration ### {Config Section 1} <!-- Example: ... --> ### {Config Section 2} <!-- Example: ... --> --- ## Common Rules 1. {Rule 1 — specific, actionable, verifiable} 2. {Rule 2} 3. {Rule 3} 4. {Rule 4} 5. {Rule 5} 6. {Rule 6} --- ## Workflow ### Step 1: {Step Name} - {What to do} - {What to check} ### Step 2: {Step Name} - {What to do} - {What to check} --- ## Final Checklist - [ ] {Verification item 1} - [ ] {Verification item 2} - [ ] {Verification item 3}
Tips & Best Practices

Keep Skills Effective

Practical advice for maintaining and evolving your skill library over time.

📅
Review quarterly
Set a reminder to review your customized skills every quarter. As your project evolves, so should your Project Configuration, rules, and checklists. Remove stale items and add new patterns.
🐛
Add items from past bugs
Every production bug is a missing checklist item. After a post-mortem, add a new check to the relevant skill. Over time, your skills become a living record of hard-won lessons.
🔄
Keep skills up to date
When you upgrade frameworks, change conventions, or adopt new tools, update the Project Configuration in affected skills. Stale config leads to stale output.
👥
Share customizations with your team
Commit your customized skills to the project repo. When a teammate runs the same skill, they get the same project-specific context. This is how you scale consistency.
🎯
Start with your most common workflow
Don't customize all 66 skills at once. Start with the 3-4 skills you use daily (feature-plan, feature-work, code-review). Customize those first and expand as needed.
📈
Measure the impact
Track how often the LLM produces output that matches your conventions without manual correction. As you fill in more Project Configuration, this rate should increase significantly.

Start Customizing Today

Open any SKILL.md file, fill in your Project Configuration, and watch the LLM produce code that matches your project.

Setup Guide Clone from GitHub