Legacy To Ai Ready

Resource Scout

Search and discover existing Claude Code skills and MCP servers before building custom solutions.

Quick Search Strategy

For Skills: 1. WebSearch: site:skillsmp.com [topic] or claude skill [topic] 2. Check GitHub: awesome-claude-skills [topic] 3. Browse: skillhub.club, claudeskills.info

For MCP: 1. WebSearch: MCP server [tool/service name] 2. Check: glama.ai/mcp/servers, mcpmarket.com 3. Official: github.com/modelcontextprotocol/servers

Skill Search Workflow

Step 1: Define Need

Before searching, clarify:

• What task needs to be accomplished?
• What tools/services are involved?
• Is it a common pattern (git, testing, API) or domain-specific?

Step 2: Search Marketplaces

Primary sources (largest catalogs):

Search patterns:

# On SkillsMP
[domain] skill          → "marketing skill", "database skill"
[framework] claude      → "react claude", "fastapi claude"
[task] automation       → "deployment automation"

Step 3: Search GitHub

Curated lists:

• github.com/keyuyuan/skillhub-awesome-skills - 精选清单
• github.com/VoltAgent/awesome-claude-skills - 生态大全
• github.com/ComposioHQ/awesome-claude-skills - 大量通用技能

Ready-to-use repositories:

• github.com/alirezarezvani/claude-skills - Content/Marketing
• github.com/gked2121/claude-skills - Workflow思维
• github.com/Microck/ordinary-claude-skills - 超大集合
• github.com/sickn33/antigravity-awesome-skills - 结构化

Search command:

# Use WebSearch tool
site:github.com "claude skill" [topic]
site:github.com "SKILL.md" [topic]

Step 4: Evaluate & Install

When skill found: 1. Check last update date (prefer recent) 2. Review SKILL.md for quality 3. Check if has scripts/references 4. Install with skill-downloader or manual copy

MCP Server Search Workflow

Step 1: Identify Integration Need

Common patterns:

• Database access → postgres, mysql, sqlite MCP
• GitHub workflow → github MCP
• Cloud services → AWS, GCP, Azure MCPs
• Communication → slack, discord MCPs
• File systems → filesystem MCP

Step 2: Search Official Sources

Primary:

• Official registry: registry.modelcontextprotocol.io
• Official repo: github.com/modelcontextprotocol/servers

Directories:

Step 3: Search GitHub

# Use WebSearch tool
site:github.com "mcp server" [service]
site:github.com "@modelcontextprotocol" [service]

Awesome lists:

• github.com/punkpeye/awesome-mcp-servers
• github.com/wong2/awesome-mcp-servers

Step 4: Verify & Configure

When MCP found: 1. Check compatibility (stdio vs HTTP) 2. Review required environment variables 3. Test connection locally 4. Add to .claude/settings.json

Search by Category

Development Tools

Skills: "code review skill", "git commit skill", "testing skill"
MCP: "github mcp", "gitlab mcp", "jira mcp"

Databases

Skills: "database skill", "sql skill", "migration skill"
MCP: "postgres mcp", "mysql mcp", "mongodb mcp"

Content & Marketing

Skills: "content creator skill", "seo skill", "social media skill"
MCP: "wordpress mcp", "notion mcp"

Cloud & DevOps

Skills: "deployment skill", "kubernetes skill", "terraform skill"
MCP: "aws mcp", "gcp mcp", "azure mcp"

AI & Data

Skills: "data analysis skill", "ml skill"
MCP: "openai mcp", "huggingface mcp"

Complete Source Reference

See references/sources.md for full directory of all skill and MCP sources with detailed descriptions.

Best Practices

1. Search before build - Always check existing resources first 2. Prefer maintained - Choose skills with recent updates 3. Check quality - Review SKILL.md structure and content 4. Consider combining - Multiple simple skills > one complex custom 5. Verify security - Review MCP permissions and token scopes

Complete Resource Directory

Full directory of all skill and MCP discovery sources.

Table of Contents

• Skills: Marketplaces & Directories
• Skills: GitHub Awesome Lists
• Skills: Ready-to-Use Repositories
• Skills: Tools & Documentation
• MCP: Official Resources
• MCP: Marketplaces & Directories
• MCP: GitHub Lists

---

Skills: Marketplaces & Directories

SkillsMP

• URL: https://skillsmp.com/
• Type: Large marketplace
• Size: 71,000+ skills
• Features: Search by author, popularity, category
• Best for: Long-tail search, discovering niche skills
• Docs: https://skillsmp.com/docs

SkillHub.club

• URL: https://www.skillhub.club/
• Type: Curated marketplace
• Features: AI-evaluated quality, stars/ratings
• Best for: Finding verified, quality skills

agent-skills.md

• URL: https://agent-skills.md/
• Type: Online directory
• Features: Direct install commands, file structure preview
• Best for: Quick browse and install

Claude Skills Hub

• URL: https://claudeskills.info/
• Type: Online directory
• Features: User-friendly UI, category browsing
• Best for: Discovery, "window shopping"

MCP Market (Skills Section)

• URL: https://mcpmarket.com/
• Type: Combined marketplace
• Features: Skills + MCP servers in one place
• Best for: Finding both skills and related MCPs

AwesomeClaude Visual Directory

• URL: https://awesomeclaude.ai/awesome-claude-skills
• Type: Visual browser
• Features: UI for ComposioHQ collection
• Best for: Non-technical users, visual browsing

---

Skills: GitHub Awesome Lists

Skillhub Awesome Skills

• URL: https://github.com/keyuyuan/skillhub-awesome-skills
• Type: Curated list
• Features: Categorized, verified skills
• Best for: Quick discovery of proven skills

Awesome Claude Skills (VoltAgent)

• URL: https://github.com/VoltAgent/awesome-claude-skills
• Type: Ecosystem overview
• Features: Broad coverage, resource compilation
• Best for: Understanding the ecosystem

Awesome Claude Skills (travisvn)

• URL: https://github.com/travisvn/awesome-claude-skills
• Type: Curated list
• Features: Alternative curation perspective
• Best for: Cross-reference validation

Awesome Claude Skills (ComposioHQ)

• URL: https://github.com/ComposioHQ/awesome-claude-skills
• Type: Large collection
• Features: High volume, general/utility skills
• Best for: Finding common utilities

Awesome Agent Skills (heilcheng)

• URL: https://github.com/heilcheng/awesome-agent-skills
• Type: Multi-platform list
• Features: Covers Claude, Codex, Copilot
• Best for: Cross-platform skill discovery

---

Skills: Ready-to-Use Repositories

alirezarezvani/claude-skills

• URL: https://github.com/alirezarezvani/claude-skills
• Focus: Content Creator, Marketing
• Quality: Production-ready
• Best for: Direct workflow integration

gked2121/claude-skills

• URL: https://github.com/gked2121/claude-skills
• Focus: Workflow-oriented, creation pipelines
• Quality: Well-structured
• Best for: Understanding workflow patterns

Microck/ordinary-claude-skills

• URL: https://github.com/Microck/ordinary-claude-skills
• Focus: Large general collection
• Quality: Variable
• Best for: Mining for specific needs

sickn33/antigravity-awesome-skills

• URL: https://github.com/sickn33/antigravity-awesome-skills
• Focus: Registry-style organization
• Quality: Highly structured
• Best for: Easy browsing and copying

synapz-org/marketing-ops-hub

• URL: https://github.com/synapz-org/marketing-ops-hub
• Focus: Marketing, operations, growth
• Quality: Domain-specific
• Best for: Marketing automation workflows

m2ai-portfolio/claude-skills

• URL: https://github.com/m2ai-portfolio/claude-skills
• Focus: Creator, growth, writing
• Quality: Platform-oriented
• Best for: Content creation workflows

---

Skills: Tools & Documentation

SkillHub Desktop

• URL: https://github.com/skillhub-club/skillhub-desktop
• Type: Desktop manager
• Features: Cross-tool sync (Claude/Cursor)
• Best for: Team skill management

Official Claude Skills Docs

• URL: https://code.claude.com/docs/en/skills
• Type: Official documentation
• Content: Structure, rules, best practices
• Best for: Creating/modifying skills

Official OpenAI Codex Skills Docs

• URL: https://developers.openai.com/codex/skills/
• Type: Official documentation
• Content: Codex/ChatGPT skill usage
• Best for: Cross-platform compatibility

---

MCP: Official Resources

MCP Official Servers Repository

• URL: https://github.com/modelcontextprotocol/servers
• Type: Official reference
• Content: Reference implementations, community index
• Best for: Starting point, official servers

MCP Official Examples

• URL: https://modelcontextprotocol.io/examples
• Type: Official examples
• Content: Integration examples, tutorials
• Best for: Learning MCP patterns

MCP Registry (Repository)

• URL: https://github.com/modelcontextprotocol/registry
• Type: Registry service code
• Content: Self-hosted registry implementation
• Best for: Enterprise internal distribution

MCP Registry (Web)

• URL: https://registry.modelcontextprotocol.io/
• Type: Official registry
• Content: Browse registered MCPs
• Best for: Finding official/verified MCPs

---

MCP: Marketplaces & Directories

Glama MCP Directory

• URL: https://glama.ai/mcp/servers
• Type: Large directory
• Features: Stars, downloads, last updated
• Best for: Finding popular, maintained servers

Glama MCP Entry

• URL: https://glama.ai/mcp
• Type: Portal
• Features: Servers, clients, tools navigation
• Best for: Team unified entry point

MCP Market

• URL: https://mcpmarket.com/
• Type: Marketplace
• Features: MCP servers + clients
• Best for: Combined skill/MCP discovery

Awesome MCP Servers (mcpservers.org)

• URL: https://mcpservers.org/
• Type: Categorized directory
• Features: Official/Remote/Clients categories
• Best for: Structured browsing

PulseMCP Servers

• URL: https://www.pulsemcp.com/servers
• Type: Index
• Features: Full index, daily updates
• Best for: Tracking new arrivals

MCP.so Servers

• URL: https://mcp.so/servers
• Type: Directory
• Features: Multi-language (CN/EN)
• Best for: Wide coverage

Smithery

• URL: https://smithery.ai/
• Type: Registry/distribution
• Features: Publish, discover, install
• Best for: "App store" experience

---

MCP: GitHub Lists

punkpeye/awesome-mcp-servers

• URL: https://github.com/punkpeye/awesome-mcp-servers
• Type: Awesome list
• Features: Domain categorization
• Best for: Classic curated list

wong2/awesome-mcp-servers

• URL: https://github.com/wong2/awesome-mcp-servers
• Type: Awesome list
• Features: Alternative curation
• Best for: Additional discoveries

---

Enterprise Resources

GitHub MCP Registry Configuration

• URL: https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-mcp-usage/configure-mcp-registry
• Type: Documentation
• Content: Organization-level MCP registry setup
• Best for: Enterprise governance, compliance

Output Patterns

Use these patterns when skills need to produce consistent, high-quality output.

Template Pattern

Provide templates for output format. Match the level of strictness to your needs.

For strict requirements (like API responses or data formats):

## Report structure

ALWAYS use this exact template structure:

# [Analysis Title]

## Executive summary

[One-paragraph overview of key findings]

## Key findings

- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations

1. Specific actionable recommendation
2. Specific actionable recommendation

For flexible guidance (when adaptation is useful):

## Report structure

Here is a sensible default format, but use your best judgment:

# [Analysis Title]

## Executive summary

[Overview]

## Key findings

[Adapt sections based on what you discover]

## Recommendations

[Tailor to the specific context]

Adjust sections as needed for the specific analysis type.

Examples Pattern

For skills where output quality depends on seeing examples, provide input/output pairs:

## Commit message format

Generate commit messages following these examples:

**Example 1:**
Input: Added user authentication with JWT tokens
Output:

feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:

fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation

Follow this style: type(scope): brief description, then detailed explanation.

Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.

Workflow Patterns

Sequential Workflows

For complex tasks, break operations into clear, sequential steps. It is often helpful to give Claude an overview of the process towards the beginning of SKILL.md:

Filling a PDF form involves these steps:

1. Analyze the form (run analyze_form.py)
2. Create field mapping (edit fields.json)
3. Validate mapping (run validate_fields.py)
4. Fill the form (run fill_form.py)
5. Verify output (run verify_output.py)

Conditional Workflows

For tasks with branching logic, guide Claude through decision points:

1. Determine the modification type:
   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow: [steps]
3. Editing workflow: [steps]

Advanced Patterns & Edge Cases

Handling special scenarios, migrations, and team collaboration.

Table of Contents

• Local Configuration
• File Ignoring
• Permissions
• Migration Strategies
• Team Collaboration
• Monorepo Patterns
• Sensitive Files

---

Local Configuration

CLAUDE.local.md

Personal preferences not shared with team. Place at project root.

Use cases:

• Personal shortcuts and aliases
• Local environment specifics
• Individual workflow preferences
• Experimental settings

Example:

# My Local Preferences

## Shortcuts
- I prefer verbose error messages
- Always show full stack traces
- Use my preferred test runner flags: --watch --coverage

## Environment
- My local DB is on port 5433 (not 5432)
- Use localhost instead of Docker for services

## Personal Style
- I like detailed comments explaining "why"
- Prefer longer variable names for clarity

Git configuration:

# .gitignore
CLAUDE.local.md

When to Use CLAUDE.local.md

---

File Ignoring

.claudeignore

Control which files Claude should not read or modify.

Location: Project root (.claudeignore)

Syntax: Same as .gitignore

Common patterns:

# Secrets and credentials
.env
.env.*
*.pem
*.key
credentials.json
secrets/

# Large generated files
dist/
build/
node_modules/
*.min.js
*.bundle.js

# Binary files
*.png
*.jpg
*.pdf
*.zip

# Sensitive data
**/data/production/
**/backups/
*.sql.gz

# Vendor code (don't modify)
vendor/
third_party/

Auto-generating .claudeignore

Based on .gitignore analysis:

# Patterns to always include in .claudeignore
ALWAYS_IGNORE = [
    "# Secrets",
    ".env",
    ".env.*",
    "*.pem",
    "*.key",
    "credentials*.json",
    "secrets/",
    "",
    "# Large/Binary",
    "*.min.js",
    "*.bundle.js",
    "*.map",
    "",
    "# Data",
    "*.sql",
    "*.db",
    "*.sqlite",
]

---

Permissions

.claude/settings.json permissions

Control what tools Claude can use:

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Bash(npm:*)",
      "Bash(git:*)",
      "Bash(pnpm:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(curl|wget:*)"
    ]
  }
}

Permission patterns

Recommended defaults

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm:*)",
      "Bash(pnpm:*)",
      "Bash(yarn:*)",
      "Bash(git:*)",
      "Bash(python:*)",
      "Bash(pytest:*)",
      "Edit",
      "Write"
    ],
    "deny": [
      "Bash(rm -rf /*:*)",
      "Bash(sudo:*)",
      "Bash(*--force*:*)"
    ]
  }
}

---

Migration Strategies

Scenario 1: No existing configuration

Standard workflow applies. Create from scratch.

Scenario 2: Has README but no CLAUDE.md

1. Extract from README:

• Build/test commands
• Setup instructions
• Architecture overview

2. Convert to CLAUDE.md format:

• Keep README for humans
• CLAUDE.md for AI-specific instructions

Scenario 3: Has basic CLAUDE.md

1. Audit existing content:

• Check if follows best practices
• Identify gaps

2. Enhance incrementally:

• Add missing sections
• Don't remove working content
• Add rules/skills as needed

Scenario 4: Has complete .claude/ setup

1. Validate structure:

• Check skill formats
• Verify agent configurations
• Test commands

2. Update patterns:

• Align with latest best practices
• Add new features (MCP, hooks)

Migration checklist

## Migration Audit

### Current State
- [ ] Has CLAUDE.md?
- [ ] Has .claude/ directory?
- [ ] Has rules files?
- [ ] Has skills?
- [ ] Has agents?
- [ ] Has commands?
- [ ] Has hooks configured?

### Quality Check
- [ ] CLAUDE.md < 500 lines?
- [ ] Skills have proper frontmatter?
- [ ] Commands have descriptions?
- [ ] No sensitive data exposed?

### Gaps to Fill
- [ ] Missing: ___
- [ ] Outdated: ___
- [ ] Needs improvement: ___

---

Team Collaboration

Git workflow for .claude/

What to commit:

CLAUDE.md              ✓ Commit
.claude/rules/         ✓ Commit
.claude/skills/        ✓ Commit
.claude/agents/        ✓ Commit
.claude/commands/      ✓ Commit
.claude/settings.json  ✓ Commit (without secrets)

What to ignore:

CLAUDE.local.md
.claude/settings.local.json

Code review for AI configs

When reviewing .claude/ changes:

1. CLAUDE.md changes:

• Does it accurately reflect current practices?
• Is it concise enough?
• Any outdated information?

2. Skill changes:

• Is the description clear?
• Does it follow skill patterns?
• Is it tested?

3. Command changes:

• Is it useful for the team?
• Does it have proper permissions?

Ownership model

## Config Ownership

| Config | Owner | Review Required |
|--------|-------|-----------------|
| CLAUDE.md | Tech Lead | Yes |
| rules/*.md | Module Owner | Yes |
| skills/* | Skill Author | Yes |
| commands/* | Any | Lightweight |
| settings.json | DevOps | Yes |

---

Monorepo Patterns

Structure

monorepo/
├── CLAUDE.md                    # Root: shared conventions
├── .claude/
│   ├── rules/
│   │   └── shared.md            # Shared rules
│   └── skills/
│       └── monorepo-nav/        # Navigation helper
├── packages/
│   ├── frontend/
│   │   ├── CLAUDE.md            # Package-specific
│   │   └── .claude/rules/
│   ├── backend/
│   │   ├── CLAUDE.md
│   │   └── .claude/rules/
│   └── shared/
│       └── CLAUDE.md
└── apps/
    └── web/
        └── CLAUDE.md

Root CLAUDE.md

# Monorepo

## Structure
- `packages/` - Shared libraries
- `apps/` - Applications
- `tools/` - Build tools

## Commands
- `pnpm install` - Install all deps
- `pnpm build` - Build all packages
- `pnpm test` - Test all packages

## Working in packages
Each package has its own CLAUDE.md with specific conventions.
Navigate to package directory for package-specific context.

## Cross-package changes
When modifying shared packages, check dependents:
\`\`\`bash
pnpm why [package-name]
\`\`\`

Package-specific CLAUDE.md

# Frontend Package

## This Package
React component library for the design system.

## Local Commands
- `pnpm dev` - Storybook
- `pnpm test` - Jest tests
- `pnpm build` - Build library

## Dependencies
- Uses: `@repo/shared`, `@repo/types`
- Used by: `apps/web`, `apps/mobile`

## Conventions
[Package-specific patterns]

---

Sensitive Files

Detection patterns

Files to protect:

SENSITIVE_PATTERNS = [
    # Environment
    ".env", ".env.*",

    # Keys and certs
    "*.pem", "*.key", "*.crt", "*.p12",
    "*.keystore", "*.jks",

    # Credentials
    "credentials*.json",
    "service-account*.json",
    "*secret*",
    "*password*",

    # Cloud configs
    ".aws/", ".gcp/", ".azure/",
    "kubeconfig*",

    # Database
    "*.sql", "*.dump",
    "database.yml",

    # IDE with potential secrets
    ".idea/", ".vscode/settings.json",
]

Protection strategies

1. Add to .claudeignore:

   .env*
   *.pem
   credentials*.json

2. Configure hooks to block:

   {
     "hooks": {
       "PreToolUse": [{
         "matcher": "Edit|Write|Read",
         "hooks": [{
           "type": "command",
           "command": "python -c \"import sys,json; p=json.load(sys.stdin).get('tool_input',{}).get('file_path',''); sys.exit(2 if any(x in p for x in ['.env','.pem','secret','credential']) else 0)\""
         }]
       }]
     }
   }

3. Document in CLAUDE.md:

   ## Security
   NEVER read or modify:
   - .env files
   - Any file with 'secret' or 'credential' in name
   - *.pem, *.key files

Audit command

# Find potentially sensitive files
find . -type f \( \
  -name "*.env*" -o \
  -name "*.pem" -o \
  -name "*.key" -o \
  -name "*secret*" -o \
  -name "*credential*" \
\) -not -path "./node_modules/*" -not -path "./.git/*"

Subagents Design Patterns Reference

Purpose

Subagents are specialized AI assistants that handle specific task types. Create subagents when:

• Tasks need isolation from main conversation context
• Specific tool restrictions are needed
• Specialized system prompts improve performance

Subagent Structure

.claude/agents/
├── code-reviewer.md
├── debugger.md
├── test-runner.md
└── security-auditor.md

Subagent Template

---
name: agent-name
description: What this agent does. Use proactively when [trigger conditions].
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a [role description].

When invoked:
1. [First action]
2. [Second action]
3. [Third action]

## Guidelines
- [Guideline 1]
- [Guideline 2]

## Output Format
[Expected output structure]

Frontmatter Options

Common Project Subagents

Code Reviewer

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes to review for quality, security, and maintainability.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer ensuring code quality.

When invoked:
1. Run `git diff` to see recent changes
2. Analyze modified files
3. Provide structured feedback

## Review Checklist
- Code clarity and readability
- Proper error handling
- Security vulnerabilities
- Test coverage
- Performance concerns

## Output Format
### Critical Issues (must fix)
- [Issue description]

### Warnings (should fix)
- [Issue description]

### Suggestions (consider)
- [Improvement idea]

Debugger

---
name: debugger
description: Debugging specialist. Use when encountering errors, test failures, or unexpected behavior.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---

You are an expert debugger.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate failure location
4. Implement minimal fix
5. Verify solution

## Debugging Process
- Analyze error messages
- Check recent code changes
- Form and test hypotheses
- Add strategic logging
- Inspect variable states

## Output Format
### Root Cause
[Explanation]

### Evidence
[Supporting details]

### Fix
[Code changes]

### Prevention
[How to avoid in future]

Test Runner

---
name: test-runner
description: Test execution and analysis. Use proactively after code changes to run tests and fix failures.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---

You are a testing specialist.

When invoked:
1. Run relevant test suite
2. Analyze failures
3. Fix failing tests or code
4. Verify fixes pass

## Test Commands
- Unit tests: `npm test`
- Integration: `npm run test:integration`
- E2E: `npm run test:e2e`

## Failure Analysis
- Check assertion messages
- Review test setup/teardown
- Verify test data
- Check for race conditions

Security Auditor

---
name: security-auditor
description: Security review specialist. Use when reviewing authentication, authorization, or handling sensitive data.
tools: Read, Grep, Glob
model: sonnet
permissionMode: plan
---

You are a security expert conducting code audits.

When invoked:
1. Identify security-sensitive code
2. Check for common vulnerabilities
3. Review authentication/authorization
4. Report findings

## Security Checklist
- Input validation
- SQL injection prevention
- XSS prevention
- CSRF protection
- Authentication bypasses
- Secrets exposure
- Dependency vulnerabilities

## Output Format
### Critical Vulnerabilities
- [Vulnerability with risk level]

### Security Warnings
- [Potential issue]

### Recommendations
- [Improvement suggestion]

Documentation Writer

---
name: doc-writer
description: Documentation specialist. Use when creating or updating documentation, API docs, or README files.
tools: Read, Write, Grep, Glob
model: sonnet
---

You are a technical documentation expert.

When invoked:
1. Understand the code/feature
2. Identify target audience
3. Create clear documentation
4. Include examples

## Documentation Standards
- Start with overview/purpose
- Include usage examples
- Document parameters/options
- Add troubleshooting section

## Style Guide
- Active voice
- Present tense
- Concise sentences
- Code examples for all features

Extraction Patterns

When analyzing legacy code for subagents:

1. Identify repetitive review tasks

• Code review patterns
• Security checking procedures
• Performance analysis steps

2. Find specialized expertise needs

• Database optimization
• API design review
• Frontend accessibility

3. Document debugging workflows

• Error investigation steps
• Log analysis procedures
• Performance profiling

4. Map tool restrictions

• Read-only tasks → limit to Read, Grep, Glob
• Modification tasks → include Edit, Write
• Execution tasks → include Bash

Tool Combinations

Permission Modes

CLAUDE.md Patterns Reference

Purpose

CLAUDE.md is the project memory file loaded into every Claude Code conversation. It should contain:

• Project-wide coding standards and conventions
• Common commands and workflows
• Architecture decisions and patterns
• Team-specific knowledge

Structure Template

# [Project Name]

## Quick Reference
- Build: `[build command]`
- Test: `[test command]`
- Lint: `[lint command]`
- Deploy: `[deploy command]`

## Code Style

### Naming Conventions
- [Convention rules]

### File Organization
- [Directory structure conventions]

### Import Order
- [Import ordering rules]

## Architecture

### Core Patterns
- [Key architectural patterns used]

### Data Flow
- [How data moves through the system]

### Error Handling
- [Error handling conventions]

## Testing

### Test Organization
- [How tests are structured]

### Testing Patterns
- [Common testing patterns]

## Git Workflow
- Branch naming: `[pattern]`
- Commit format: `[format]`
- PR requirements: `[requirements]`

## Environment
- Required env vars: `[list]`
- Local setup: `[steps]`

Content Guidelines

What to Include

1. Frequently used commands - Build, test, lint, deploy 2. Coding conventions - Naming, formatting, imports 3. Architecture patterns - Domain boundaries, data flow 4. Git workflow - Branch naming, commit format 5. Environment setup - Required variables, local config

What to Avoid

1. Generic advice Claude already knows 2. Verbose explanations (prefer examples) 3. Information that changes frequently 4. Sensitive data or secrets

Language-Specific Patterns

TypeScript/JavaScript Projects

## Code Style
- Use TypeScript strict mode
- Prefer `const` over `let`
- Use named exports, avoid default exports
- Imports: external → internal → relative

## Patterns
- Use Zod for runtime validation
- Prefer composition over inheritance
- Use Result types for error handling

Python Projects

## Code Style
- Follow PEP 8
- Use type hints for all public functions
- Docstrings: Google style
- Imports: stdlib → third-party → local

## Patterns
- Use dataclasses for data containers
- Prefer Protocol over ABC for interfaces
- Use contextmanager for resource management

Go Projects

## Code Style
- Run `gofmt` before commit
- Error handling: wrap with context
- Package naming: singular, lowercase

## Patterns
- Use interfaces at consumption point
- Prefer composition over embedding
- Context propagation for cancellation

Imports in CLAUDE.md

Use @path/to/file to import additional files:

# Project Memory

## Core Guidelines
@docs/coding-standards.md
@docs/architecture.md

## API Reference
@docs/api/README.md

Rules Directory Alternative

For larger projects, use .claude/rules/ for modular organization:

.claude/rules/
├── code-style.md      # Coding conventions
├── testing.md         # Test guidelines
├── api-design.md      # API patterns
└── security.md        # Security requirements

Each rule file can have path-specific scope:

---
paths:
  - "src/api/**/*.ts"
---
# API Rules
- All endpoints must validate input
- Use standard error response format

Extraction Patterns

When analyzing a legacy codebase, extract:

1. From package.json/pyproject.toml/go.mod

• Build/test commands
• Dependencies and their purposes

2. From .eslintrc/.prettierrc/etc.

• Formatting rules
• Linting conventions

3. From existing README

• Project overview
• Setup instructions

4. From code structure

• Directory organization patterns
• Module boundaries
• Naming conventions

5. From git history

• Commit message format
• Branch naming patterns
• PR workflow

Slash Commands Design Patterns Reference

Purpose

Slash commands are quick, reusable prompts triggered by /command. Create commands for:

• Frequently used prompts
• Common workflows
• Quick reminders or templates
• Team-standardized operations

Command Structure

.claude/commands/
├── commit.md           # /commit
├── review.md           # /review
├── deploy.md           # /deploy
└── frontend/
    └── component.md    # /component (project:frontend)

Command Template

---
description: Brief description shown in /help
allowed-tools: Tool1, Tool2
argument-hint: [optional-args]
---

# Command Instructions

[Detailed prompt for Claude to follow]

Frontmatter Options

Common Project Commands

Git Commit

---
description: Create a git commit with proper message format
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [optional message]
---

## Context
- Current git status: !`git status`
- Current git diff: !`git diff HEAD`
- Recent commits: !`git log --oneline -5`

## Instructions
Create a git commit following this format:
- type(scope): subject
- Body explaining what and why

Types: feat, fix, docs, style, refactor, test, chore

If $ARGUMENTS provided, use as commit message hint.

PR Review

---
description: Review pull request changes
allowed-tools: Bash(git:*), Read, Grep
argument-hint: [branch-name]
---

## Context
- Changes to review: !`git diff main...$1`
- Changed files: !`git diff --name-only main...$1`

## Instructions
Review the PR changes for:
1. Code quality and clarity
2. Potential bugs or edge cases
3. Test coverage
4. Security concerns
5. Performance implications

Provide structured feedback with:
- Approval recommendation
- Required changes (if any)
- Suggestions for improvement

Deploy

---
description: Deploy to specified environment
allowed-tools: Bash
argument-hint: [staging|production]
---

## Instructions
Deploy to $1 environment:

1. Verify current branch is deployable
2. Run pre-deployment checks
3. Execute deployment command
4. Verify deployment success

For staging: `npm run deploy:staging`
For production: `npm run deploy:prod`

Test

---
description: Run tests with coverage
allowed-tools: Bash
argument-hint: [file-pattern]
---

## Instructions
Run tests:
- If $ARGUMENTS provided, run tests matching pattern
- Otherwise, run full test suite

Command: `npm test $ARGUMENTS`

After tests complete:
1. Report pass/fail summary
2. Highlight any failures
3. Show coverage changes if available

Create Component

---
description: Create a new React component
allowed-tools: Write, Read
argument-hint: [ComponentName]
---

## Instructions
Create a new React component named $1:

1. Create `src/components/$1/$1.tsx`:
\`\`\`tsx
import { FC } from 'react';
import styles from './$1.module.css';

interface $1Props {
  // TODO: Define props
}

export const $1: FC<$1Props> = (props) => {
  return (
    <div className={styles.container}>
      {/* TODO: Implement */}
    </div>
  );
};
\`\`\`

2. Create `src/components/$1/$1.module.css`
3. Create `src/components/$1/$1.test.tsx`
4. Export from `src/components/$1/index.ts`

API Endpoint

---
description: Create a new API endpoint
allowed-tools: Write, Read
argument-hint: [resource] [method]
---

## Instructions
Create API endpoint for $1 with $2 method:

1. Create route handler in `src/api/$1/route.ts`
2. Add request/response types
3. Implement handler logic
4. Add input validation
5. Create test file

Follow project API patterns from .claude/skills/api-patterns/

Database Migration

---
description: Create a database migration
allowed-tools: Bash, Write
argument-hint: [migration-name]
---

## Context
- Existing migrations: !`ls -la src/db/migrations/`

## Instructions
Create a new migration named $1:

1. Run: `npm run migrate:create $1`
2. Edit the generated migration file
3. Implement both up and down functions
4. Test locally: `npm run migrate:dev`

Format Code

---
description: Format and lint code
allowed-tools: Bash
argument-hint: [file-or-directory]
---

## Instructions
Format and lint code:

1. Run formatter: `npm run format $ARGUMENTS`
2. Run linter: `npm run lint $ARGUMENTS`
3. Report any remaining issues

Bash Command Execution

Use ! prefix to execute bash commands and include output:

## Context
- Current branch: !`git branch --show-current`
- Status: !`git status --short`
- Last commit: !`git log -1 --oneline`

File References

Use @ to include file contents:

Review the implementation in @src/auth/login.ts

Compare @src/old.ts with @src/new.ts

Arguments

All Arguments

# $ARGUMENTS captures all args
Search for: $ARGUMENTS

Positional Arguments

# $1, $2, $3 for specific positions
Create $1 in $2 with $3 priority

Namespacing

Subdirectories create namespaced commands:

.claude/commands/
├── frontend/
│   └── component.md    # /component (project:frontend)
├── backend/
│   └── endpoint.md     # /endpoint (project:backend)
└── deploy.md           # /deploy (project)

Extraction Patterns

When analyzing legacy code for commands:

1. Identify common operations

• Build/test/deploy commands
• Code generation patterns
• Review procedures

2. Find team workflows

• PR review process
• Release procedures
• Debugging steps

3. Document shortcuts

• Frequently typed commands
• Multi-step procedures
• Environment setup

Complete Examples

Real-world examples of AI-ready configurations for common project types.

Table of Contents

• Next.js Web Application
• Python FastAPI Backend
• Go Microservice
• React Component Library

---

Next.js Web Application

Generated CLAUDE.md

# MyApp - Next.js E-commerce Platform

## Quick Reference

| Command | Purpose |
|---------|---------|
| `pnpm dev` | Start development server |
| `pnpm build` | Production build |
| `pnpm test` | Run tests |
| `pnpm lint` | Run ESLint |
| `pnpm format` | Format with Prettier |

## Code Style

### Naming
- Components: PascalCase (`ProductCard.tsx`)
- Hooks: camelCase with `use` prefix (`useCart.ts`)
- Utils: camelCase (`formatPrice.ts`)
- API routes: kebab-case (`/api/get-products`)

### Imports
1. React/Next imports
2. Third-party packages
3. Internal modules (`@/`)
4. Relative imports
5. Type imports last

### Components
- Prefer functional components with TypeScript
- Use named exports
- Props interface above component
- Extract complex logic to custom hooks

## Architecture

src/ ├── app/ # Next.js App Router pages ├── components/ # Reusable UI components ├── hooks/ # Custom React hooks ├── lib/ # Utilities and helpers ├── services/ # API client functions └── types/ # TypeScript types

### Data Flow
- Server Components for data fetching
- Client Components for interactivity
- React Query for client-side data
- Zustand for global client state

## Testing

- Unit tests: Vitest + React Testing Library
- E2E: Playwright
- Test files: `*.test.tsx` next to source

## Git Workflow

- Branch: `feature/[ticket]-description`
- Commits: conventional commits (`feat:`, `fix:`, etc.)
- PR: requires 1 approval + passing CI

Generated .claude/rules/api.md

---
paths:
  - "src/app/api/**/*"
---

# API Route Rules

## Response Format
Always use this structure:
\`\`\`ts
return NextResponse.json({
  success: true,
  data: result,
  error: null
});
\`\`\`

## Error Handling
\`\`\`ts
try {
  // logic
} catch (error) {
  return NextResponse.json(
    { success: false, data: null, error: error.message },
    { status: 500 }
  );
}
\`\`\`

## Validation
Use Zod for all inputs:
\`\`\`ts
const schema = z.object({ ... });
const result = schema.safeParse(body);
if (!result.success) {
  return NextResponse.json({ error: result.error }, { status: 400 });
}
\`\`\`

Generated .claude/commands/commit.md

---
description: Create conventional commit
allowed-tools: Bash(git:*)
---

## Context
- Status: !`git status --short`
- Diff: !`git diff --stat`

## Instructions
Create commit following conventional commits:
- feat: new feature
- fix: bug fix
- docs: documentation
- style: formatting
- refactor: code restructure
- test: adding tests
- chore: maintenance

Format: `type(scope): description`

Generated .claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read f; [[ \"$f\" =~ \\.(ts|tsx|js|jsx)$ ]] && npx prettier --write \"$f\" 2>/dev/null; exit 0; }"
          }
        ]
      }
    ]
  }
}

---

Python FastAPI Backend

Generated CLAUDE.md

# UserService - FastAPI Microservice

## Quick Reference

| Command | Purpose |
|---------|---------|
| `uv run uvicorn main:app --reload` | Dev server |
| `uv run pytest` | Run tests |
| `uv run ruff check .` | Lint |
| `uv run ruff format .` | Format |
| `uv run mypy .` | Type check |

## Code Style

### Naming
- Modules: snake_case (`user_service.py`)
- Classes: PascalCase (`UserRepository`)
- Functions: snake_case (`get_user_by_id`)
- Constants: UPPER_SNAKE (`MAX_RETRIES`)

### Type Hints
- Required for all public functions
- Use `Optional[T]` explicitly
- Prefer `list[T]` over `List[T]` (Python 3.9+)

### Docstrings
Google style:
\`\`\`python
def get_user(user_id: int) -> User:
    """Fetch user by ID.

    Args:
        user_id: The unique user identifier.

    Returns:
        User object if found.

    Raises:
        NotFoundError: If user doesn't exist.
    """
\`\`\`

## Architecture

src/ ├── api/ # FastAPI routers ├── models/ # Pydantic models ├── services/ # Business logic ├── repositories/ # Data access └── core/ # Config, dependencies

### Dependency Injection
Use FastAPI's `Depends()`:
\`\`\`python
@router.get("/users/{user_id}")
async def get_user(
    user_id: int,
    service: UserService = Depends(get_user_service)
):
    return await service.get(user_id)
\`\`\`

## Database

- ORM: SQLAlchemy 2.0 with async
- Migrations: Alembic
- Always use transactions for writes

## Testing

- Framework: pytest + pytest-asyncio
- Fixtures in `conftest.py`
- Use factories for test data

## Environment

Required variables:
- `DATABASE_URL`
- `REDIS_URL`
- `JWT_SECRET`

Generated .claude/skills/database/SKILL.md

---
name: database-patterns
description: SQLAlchemy patterns and migration workflow. Use when writing queries, creating models, or managing migrations.
---

# Database Patterns

## Model Definition
\`\`\`python
from sqlalchemy.orm import Mapped, mapped_column

class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)
    email: Mapped[str] = mapped_column(unique=True, index=True)
    created_at: Mapped[datetime] = mapped_column(default=func.now())
\`\`\`

## Async Queries
\`\`\`python
async with async_session() as session:
    result = await session.execute(
        select(User).where(User.email == email)
    )
    user = result.scalar_one_or_none()
\`\`\`

## Migrations

Create: `alembic revision --autogenerate -m "description"`
Apply: `alembic upgrade head`
Rollback: `alembic downgrade -1`

---

Go Microservice

Generated CLAUDE.md

# OrderService - Go gRPC Service

## Quick Reference

| Command | Purpose |
|---------|---------|
| `make run` | Run service |
| `make test` | Run tests |
| `make lint` | Run golangci-lint |
| `make proto` | Generate protobuf |
| `make build` | Build binary |

## Code Style

### Naming
- Packages: lowercase, single word (`user`, `order`)
- Interfaces: `-er` suffix when possible (`Reader`, `UserStore`)
- Exported: PascalCase
- Unexported: camelCase

### Error Handling
Always wrap errors with context:
\`\`\`go
if err != nil {
    return fmt.Errorf("failed to get user %d: %w", userID, err)
}
\`\`\`

### Interfaces
Define at point of use, not implementation:
\`\`\`go
// In the consumer package
type UserGetter interface {
    GetUser(ctx context.Context, id int64) (*User, error)
}
\`\`\`

## Architecture

cmd/ ├── server/ # Main entry point internal/ ├── api/ # gRPC handlers ├── domain/ # Business entities ├── service/ # Business logic ├── repository/ # Data access └── pkg/ # Shared utilities

### Context Propagation
Always pass context as first argument:
\`\`\`go
func (s *Service) Process(ctx context.Context, req *Request) error
\`\`\`

## Testing

- Table-driven tests
- Use testify for assertions
- Mock interfaces with mockgen

---

React Component Library

Generated CLAUDE.md

# UIKit - React Component Library

## Quick Reference

| Command | Purpose |
|---------|---------|
| `pnpm dev` | Storybook dev |
| `pnpm test` | Run tests |
| `pnpm build` | Build library |
| `pnpm lint` | ESLint + Stylelint |

## Code Style

### Component Structure
\`\`\`tsx
// Button.tsx
export interface ButtonProps {
  variant?: 'primary' | 'secondary';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', size = 'md', children, ...props }, ref) => {
    return (
      <button ref={ref} className={styles[variant]} {...props}>
        {children}
      </button>
    );
  }
);

Button.displayName = 'Button';
\`\`\`

### File Organization

src/components/Button/ ├── Button.tsx # Component ├── Button.test.tsx # Tests ├── Button.stories.tsx # Storybook ├── Button.module.css # Styles └── index.ts # Export

### Exports
- Named exports only
- Re-export from index.ts
- Types exported separately

## Styling

- CSS Modules for component styles
- Design tokens in CSS variables
- No inline styles

## Testing

- React Testing Library
- Test behavior, not implementation
- Test accessibility with jest-axe

## Documentation

Every component needs:
1. TypeScript types (self-documenting)
2. Storybook stories (visual docs)
3. JSDoc for complex props

Generated .claude/agents/accessibility-reviewer.md

---
name: accessibility-reviewer
description: Review components for accessibility compliance. Use after creating or modifying UI components.
tools: Read, Grep, Glob
model: sonnet
---

You are an accessibility expert reviewing React components.

## Review Checklist
- Semantic HTML elements
- ARIA attributes when needed
- Keyboard navigation support
- Focus management
- Color contrast
- Screen reader compatibility

## Output Format
### Issues Found
- [Issue with severity and fix]

### Recommendations
- [Improvement suggestion]

Hooks Design Patterns Reference

Purpose

Hooks are shell commands that execute at specific events in Claude Code's lifecycle. Use hooks for:

• Automatic code formatting
• Pre-commit validation
• Custom notifications
• Logging and compliance
• File protection

Configuration Location

// .claude/settings.json
{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

Hook Events

Matchers

Common Hook Patterns

Code Formatting (PostToolUse)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read f; [[ \"$f\" == *.ts ]] && npx prettier --write \"$f\"; }"
          }
        ]
      }
    ]
  }
}

Python Formatting

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read f; [[ \"$f\" == *.py ]] && black \"$f\" && isort \"$f\"; }"
          }
        ]
      }
    ]
  }
}

File Protection (PreToolUse)

Block edits to sensitive files:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json,sys; d=json.load(sys.stdin); p=d.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(x in p for x in ['.env','.git/','secrets/']) else 0)\""
          }
        ]
      }
    ]
  }
}

Command Logging (PreToolUse)

Log all bash commands:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

Custom Notifications

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Session Initialization

Install dependencies on session start:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/setup.sh"
          }
        ]
      }
    ]
  }
}

Lint on Edit

Run linter after file modifications:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read f; [[ -f \"$f\" ]] && npm run lint -- \"$f\"; }"
          }
        ]
      }
    ]
  }
}

Exit Codes

Hook Input (stdin)

Hooks receive JSON input via stdin:

{
  "session_id": "abc123",
  "tool_name": "Edit",
  "tool_input": {
    "file_path": "/path/to/file.ts",
    "old_string": "...",
    "new_string": "..."
  }
}

Environment Variables

Project-Specific Scripts

Reference scripts using $CLAUDE_PROJECT_DIR:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh"
          }
        ]
      }
    ]
  }
}

Example script .claude/hooks/format.sh:

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path')

case "$FILE" in
  *.ts|*.tsx) npx prettier --write "$FILE" ;;
  *.py) black "$FILE" && isort "$FILE" ;;
  *.go) gofmt -w "$FILE" ;;
  *.rs) rustfmt "$FILE" ;;
esac

Language-Specific Configurations

TypeScript/JavaScript

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read f; [[ \"$f\" =~ \\.(ts|tsx|js|jsx)$ ]] && npx prettier --write \"$f\" && npx eslint --fix \"$f\"; }"
          }
        ]
      }
    ]
  }
}

Python

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read f; [[ \"$f\" == *.py ]] && black \"$f\" && isort \"$f\" && ruff check --fix \"$f\"; }"
          }
        ]
      }
    ]
  }
}

Go

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read f; [[ \"$f\" == *.go ]] && gofmt -w \"$f\" && goimports -w \"$f\"; }"
          }
        ]
      }
    ]
  }
}

Extraction Patterns

When analyzing legacy code for hooks:

1. Check existing tooling

• Pre-commit hooks
• Git hooks
• CI/CD formatting steps

2. Identify formatting tools

• Prettier, ESLint (JS/TS)
• Black, isort, ruff (Python)
• gofmt, goimports (Go)

3. Find validation rules

• Protected files/directories
• Required checks before commit
• Lint rules

4. Note team practices

• Auto-formatting expectations
• Logging requirements
• Notification preferences

MCP Servers Configuration Patterns

Purpose

MCP (Model Context Protocol) servers connect Claude Code to external tools and data sources. Consider MCP servers when:

• Project uses external APIs/services frequently
• Team has internal tools that could benefit Claude
• Database queries are common operations
• External data sources need integration

Configuration Location

MCP servers are configured in Claude Code settings:

• User-level: ~/.claude/settings.json
• Project-level: .claude/settings.json

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Common MCP Server Patterns

Database Access

For projects with frequent database operations:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${POSTGRES_URL}"
      }
    }
  }
}

Filesystem Access

For projects needing broader file access:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

GitHub Integration

For GitHub-heavy workflows:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Slack Integration

For team communication:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_TOKEN}"
      }
    }
  }
}

Memory/Knowledge Base

For persistent context across sessions:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

When to Add MCP Servers

Security Considerations

1. Environment Variables - Never hardcode secrets in settings 2. Minimal Permissions - Only enable needed capabilities 3. Project vs User - Project MCP configs are shared via git 4. Token Scoping - Use minimal-scope tokens

Environment Variable Pattern

Use ${VAR_NAME} syntax for sensitive values:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "CONNECTION_STRING": "${DATABASE_URL}"
      }
    }
  }
}

Then set in .env or shell:

export DATABASE_URL="postgres://user:pass@host:5432/db"

Custom MCP Servers

For project-specific tools, create custom MCP servers:

{
  "mcpServers": {
    "internal-api": {
      "command": "node",
      "args": [".claude/mcp/internal-api-server.js"],
      "env": {
        "API_KEY": "${INTERNAL_API_KEY}"
      }
    }
  }
}

MCP Permission Rules

Control which MCP tools are allowed:

{
  "permissions": {
    "allow": [
      "mcp__github",
      "mcp__postgres__query"
    ],
    "deny": [
      "mcp__postgres__execute"
    ]
  }
}

Extraction Patterns

When analyzing legacy code for MCP needs:

1. Check for API integrations

• REST API calls
• GraphQL queries
• Third-party services

2. Identify data sources

• Database connections
• External data files
• Cloud storage

3. Find team tools

• Internal dashboards
• Deployment tools
• Monitoring systems

4. Note common operations

• Frequent queries
• Repeated API calls
• Data transformations

Skills & MCP 资源检索源

为AI-ready项目推荐的资源发现渠道，帮助团队找到现成的skills和MCP servers。

Skills 检索源

聚合市场 & 目录

GitHub Awesome Lists

成体系技能仓库（可直接搬用）

工具 & 文档

---

MCP 检索源

官方资源

市场 & 目录

GitHub Awesome Lists

企业文档

---

推荐使用策略

对于新手团队

1. 先从 SkillHub.club 或 Claude Skills Hub 发现评分高的skills 2. 查看 Official Claude Skills Docs 理解结构 3. 从 GitHub成体系仓库 直接复制相关skills

对于进阶团队

1. 用 SkillsMP 做长尾挖掘 2. 配置 MCP servers 连接外部工具 3. 用 skill-creator 创建定制skills

对于企业团队

1. 参考 MCP Registry 自建内部registry 2. 用 SkillHub Desktop 统一管理 3. 配置组织级MCP策略

Rules Patterns Reference

Purpose

.claude/rules/ provides modular, path-specific instructions that supplement CLAUDE.md. Use rules for:

• Language-specific guidelines
• Module-specific conventions
• Team-specific workflows
• Conditional instructions

Structure

.claude/rules/
├── code-style.md       # General coding style
├── testing.md          # Testing conventions
├── api-design.md       # API patterns
├── security.md         # Security requirements
├── frontend/
│   ├── react.md        # React-specific rules
│   └── styles.md       # CSS conventions
└── backend/
    ├── api.md          # Backend API rules
    └── database.md     # Database conventions

Rule File Template

Unconditional Rule (applies to all files)

# Code Style Rules

## Naming Conventions
- Use camelCase for variables and functions
- Use PascalCase for classes and types
- Use UPPER_SNAKE_CASE for constants

## Comments
- Document public APIs with JSDoc
- Avoid obvious comments
- Explain "why" not "what"

Conditional Rule (applies to specific paths)

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

## Request Validation
- Validate all input with Zod schemas
- Return typed responses
- Use standard error format

## Security
- Authenticate all endpoints
- Check authorization
- Sanitize user input

Path Patterns

Brace Expansion

---
paths:
  - "src/**/*.{ts,tsx}"
  - "{src,lib}/**/*.ts"
---

Common Rule Files

Code Style (code-style.md)

# Code Style

## TypeScript
- Enable strict mode
- Prefer `const` over `let`
- Use explicit return types for public functions
- Avoid `any`, use `unknown` if needed

## Formatting
- 2-space indentation
- Single quotes for strings
- Trailing commas in multiline
- No semicolons (per project preference)

## Imports
1. External packages (alphabetical)
2. Internal modules (alphabetical)
3. Relative imports (by distance)

Testing (testing.md)

# Testing Rules

## Test Organization
- Unit tests: `*.test.ts` alongside source
- Integration: `tests/integration/`
- E2E: `tests/e2e/`

## Naming
- Describe behavior: `should [expected behavior] when [condition]`
- Group by function/component

## Coverage Requirements
- Minimum 80% coverage for new code
- Critical paths must have integration tests

API Design (api-design.md)

---
paths:
  - "src/api/**/*"
  - "src/routes/**/*"
---

# API Design Rules

## Endpoint Structure
- REST: `/api/v1/[resource]/[id]/[action]`
- Use plural nouns for resources

## Response Format
\`\`\`json
{
  "success": boolean,
  "data": object | null,
  "error": { "code": string, "message": string } | null
}
\`\`\`

## Status Codes
- 200: Success
- 201: Created
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Server Error

## Validation
- Use Zod schemas for all inputs
- Return detailed validation errors

Security (security.md)

# Security Rules

## Input Validation
- Never trust user input
- Validate and sanitize all inputs
- Use parameterized queries

## Authentication
- Use secure session management
- Implement rate limiting
- Log authentication events

## Secrets
- Never commit secrets
- Use environment variables
- Rotate credentials regularly

## Dependencies
- Keep dependencies updated
- Review security advisories
- Use lockfiles

React Components (frontend/react.md)

---
paths:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
---

# React Rules

## Component Structure
1. Imports
2. Types/Interfaces
3. Component function
4. Styles (if co-located)

## Hooks
- Custom hooks in `src/hooks/`
- Prefix with `use`
- Document dependencies

## State Management
- Local state: useState
- Server state: React Query
- Global state: Context/Zustand

## Performance
- Memoize expensive computations
- Use `memo` for pure components
- Lazy load routes

Database (backend/database.md)

---
paths:
  - "src/db/**/*"
  - "src/models/**/*"
  - "prisma/**/*"
---

# Database Rules

## Queries
- Use ORM for standard operations
- Raw SQL for complex queries
- Always use transactions for multi-step operations

## Migrations
- One migration per change
- Always write down migrations
- Test migrations locally first

## Naming
- Tables: snake_case, plural
- Columns: snake_case
- Foreign keys: `[table]_id`

## Indexes
- Primary keys: automatic
- Foreign keys: always index
- Query patterns: create indexes

User-Level Rules

Personal rules in ~/.claude/rules/:

~/.claude/rules/
├── preferences.md      # Personal coding style
└── workflows.md        # Personal workflows

Extraction Patterns

When analyzing legacy code for rules:

1. Check existing configs

• .eslintrc, .prettierrc
• tsconfig.json strict settings
• .editorconfig

2. Analyze code patterns

• Common coding conventions
• Import organization
• Error handling patterns

3. Identify module boundaries

• API vs frontend vs shared
• Test organization
• Module-specific conventions

4. Document team standards

• Code review requirements
• Merge criteria
• Documentation expectations

Skills Design Patterns Reference

Purpose

Skills give Claude specialized knowledge for specific tasks. Create project-specific skills when:

• There are complex domain-specific workflows
• Certain tasks require consistent procedures
• Team knowledge needs to be codified

Skill Structure

.claude/skills/
└── skill-name/
    ├── SKILL.md         # Required: main instructions
    ├── scripts/         # Optional: executable code
    ├── references/      # Optional: detailed docs
    └── assets/          # Optional: templates/files

When to Create Skills

Good Candidates

1. API Integration Patterns - Custom API workflows 2. Database Operations - Complex query patterns, migrations 3. Deployment Procedures - Release workflows 4. Code Generation - Project-specific generators 5. Testing Strategies - Complex test scenarios 6. Documentation - Doc generation patterns

Not Suitable for Skills

1. Simple, one-off tasks 2. Generic coding knowledge 3. Information that changes frequently

SKILL.md Template

---
name: skill-name
description: What this skill does and when to use it. Use when [specific triggers]. Handles [specific tasks].
---

# Skill Name

## Quick Start
[Minimal example to get started]

## Workflow
1. [Step 1]
2. [Step 2]
3. [Step 3]

## Patterns

### Pattern 1: [Name]
[Description and example]

### Pattern 2: [Name]
[Description and example]

## Scripts
- `scripts/script-name.py`: [What it does]

## References
- [reference-name.md](references/reference-name.md): [When to read]

Common Project Skills

API Skill

---
name: api-patterns
description: Project API design patterns. Use when creating/modifying API endpoints, handling requests, or working with API responses.
---

# API Patterns

## Endpoint Structure
All endpoints follow: `/api/v1/[resource]/[action]`

## Request Validation
Use Zod schemas in `src/schemas/`:
\`\`\`typescript
const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1)
});
\`\`\`

## Response Format
\`\`\`json
{
  "success": true,
  "data": { ... },
  "error": null
}
\`\`\`

## Error Handling
Use `ApiError` class from `src/lib/errors`:
\`\`\`typescript
throw new ApiError(400, "VALIDATION_ERROR", "Invalid input");
\`\`\`

Database Skill

---
name: database-patterns
description: Database operations and query patterns. Use when writing queries, creating migrations, or working with data models.
---

# Database Patterns

## Schema Reference
See [references/schema.md](references/schema.md) for full schema.

## Common Queries
### User lookup
\`\`\`sql
SELECT * FROM users WHERE id = $1 AND deleted_at IS NULL;
\`\`\`

## Migration Pattern
1. Create migration: `npm run migrate:create [name]`
2. Write up/down functions
3. Test locally: `npm run migrate:dev`
4. Apply: `npm run migrate:prod`

Testing Skill

---
name: testing-patterns
description: Testing strategies and patterns. Use when writing tests, setting up test data, or debugging test failures.
---

# Testing Patterns

## Test Organization
- Unit tests: `*.test.ts` next to source
- Integration: `tests/integration/`
- E2E: `tests/e2e/`

## Fixtures
Use factories in `tests/factories/`:
\`\`\`typescript
import { createUser } from '@/tests/factories';
const user = await createUser({ role: 'admin' });
\`\`\`

## Mocking Patterns
\`\`\`typescript
vi.mock('@/lib/email', () => ({
  sendEmail: vi.fn().mockResolvedValue({ sent: true })
}));
\`\`\`

Deployment Skill

---
name: deployment-guide
description: Deployment procedures and release workflow. Use when deploying, creating releases, or troubleshooting deployments.
---

# Deployment Guide

## Pre-Deployment Checklist
- [ ] All tests pass
- [ ] Version bumped
- [ ] Changelog updated
- [ ] PR approved

## Deployment Steps
1. Merge to main
2. Tag release: `git tag v[version]`
3. Push tag: `git push --tags`
4. Monitor CI/CD pipeline
5. Verify deployment

## Rollback
\`\`\`bash
./scripts/rollback.sh [previous-version]
\`\`\`

Extraction Patterns

When analyzing legacy code for skills:

1. Identify repeated patterns

• Common query patterns
• API response handling
• Error handling workflows

2. Find domain knowledge

• Business logic rules
• Data validation rules
• Calculation formulas

3. Document complex workflows

• Multi-step procedures
• Decision trees
• State machines

4. Extract tool-specific knowledge

• Build tool configurations
• Test framework patterns
• Deployment procedures

Progressive Disclosure

Keep SKILL.md concise (<500 lines). Split into references:

## Quick Start
[Essential info here]

## Advanced Topics
- **Complex Queries**: See [references/queries.md](references/queries.md)
- **Error Codes**: See [references/errors.md](references/errors.md)
- **Performance**: See [references/performance.md](references/performance.md)