mirror of
https://github.com/duthaho/claudekit.git
synced 2026-06-11 12:44:56 +03:00
feat: add verification methodology and writing plans skills
This commit is contained in:
duthaho
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,590 @@
|
||||
---
|
||||
title: Creating Custom Commands
|
||||
description: Learn how to create custom slash commands for your project-specific workflows.
|
||||
---
|
||||
|
||||
# Creating Custom Commands
|
||||
|
||||
Custom commands let you automate project-specific workflows with simple slash commands. This guide shows you how to create commands that integrate seamlessly with Claude Kit.
|
||||
|
||||
## Command File Structure
|
||||
|
||||
Commands are markdown files in `.claude/commands/`:
|
||||
|
||||
```
|
||||
.claude/commands/
|
||||
├── your-command.md # /your-command
|
||||
├── deploy-prod.md # /deploy-prod
|
||||
└── weekly-report.md # /weekly-report
|
||||
```
|
||||
|
||||
The filename (without `.md`) becomes the command name.
|
||||
|
||||
## Command Template
|
||||
|
||||
Here's the complete template for a command file:
|
||||
|
||||
```markdown
|
||||
# /command-name - Short Description
|
||||
|
||||
## Purpose
|
||||
|
||||
Brief description of what this command does and why it exists.
|
||||
|
||||
## Usage
|
||||
|
||||
\`\`\`
|
||||
/command-name [arguments]
|
||||
\`\`\`
|
||||
|
||||
## Arguments
|
||||
|
||||
- `$ARGUMENTS`: Description of what arguments this command accepts
|
||||
|
||||
---
|
||||
|
||||
Execute workflow for: **$ARGUMENTS**
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: First Step
|
||||
|
||||
Description of what happens in this phase.
|
||||
|
||||
1. **Task 1**
|
||||
- Details about task 1
|
||||
- What to check or do
|
||||
|
||||
2. **Task 2**
|
||||
- Details about task 2
|
||||
- Expected outcomes
|
||||
|
||||
### Phase 2: Second Step
|
||||
|
||||
Description of next phase.
|
||||
|
||||
1. **Task 1**
|
||||
- Details
|
||||
- Actions
|
||||
|
||||
## Output
|
||||
|
||||
Describe what the command should produce:
|
||||
|
||||
\`\`\`markdown
|
||||
## [Command Name] Complete
|
||||
|
||||
### Summary
|
||||
[What was done]
|
||||
|
||||
### Results
|
||||
- Item 1
|
||||
- Item 2
|
||||
|
||||
### Next Steps
|
||||
1. Next action
|
||||
2. Another action
|
||||
\`\`\`
|
||||
|
||||
## Example
|
||||
|
||||
**Input**: `/command-name example input`
|
||||
|
||||
**Output**: Description of what happens with this example
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | Description | Example |
|
||||
|------|-------------|---------|
|
||||
| `--flag-name` | What this flag does | `--flag-name=value` |
|
||||
|
||||
<!-- CUSTOMIZATION POINT -->
|
||||
## Variations
|
||||
|
||||
Optional section for project-specific variations.
|
||||
```
|
||||
|
||||
## Command Anatomy
|
||||
|
||||
### 1. Header Section
|
||||
|
||||
```markdown
|
||||
# /deploy - Deploy Application
|
||||
|
||||
## Purpose
|
||||
|
||||
Deploy the application to specified environment with pre-deployment checks,
|
||||
database migrations, and post-deployment verification.
|
||||
```
|
||||
|
||||
The header includes:
|
||||
|
||||
- **Title**: Command name and one-line description
|
||||
- **Purpose**: Detailed explanation of what and why
|
||||
|
||||
### 2. Usage Section
|
||||
|
||||
```markdown
|
||||
## Usage
|
||||
|
||||
\`\`\`
|
||||
/deploy [environment] [--skip-tests]
|
||||
\`\`\`
|
||||
|
||||
## Arguments
|
||||
|
||||
- `environment`: Target environment (staging, production)
|
||||
- `--skip-tests`: Skip running tests before deployment
|
||||
```
|
||||
|
||||
Define:
|
||||
|
||||
- How to invoke the command
|
||||
- What arguments it accepts
|
||||
- Optional flags
|
||||
|
||||
### 3. Separator Line
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
||||
Deploy to **$ARGUMENTS** environment:
|
||||
```
|
||||
|
||||
The `---` separator is important:
|
||||
|
||||
- Everything above is documentation
|
||||
- Everything below is the instruction Claude executes
|
||||
- Use `$ARGUMENTS` to inject user input
|
||||
|
||||
### 4. Workflow Section
|
||||
|
||||
```markdown
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Pre-deployment Checks
|
||||
|
||||
1. **Verify Environment**
|
||||
- Check environment exists
|
||||
- Verify credentials
|
||||
- Confirm deployment is allowed
|
||||
|
||||
2. **Run Tests**
|
||||
- Execute full test suite
|
||||
- Check code coverage
|
||||
- Fail if tests don't pass
|
||||
```
|
||||
|
||||
Break down the command into:
|
||||
|
||||
- Logical phases
|
||||
- Numbered steps within phases
|
||||
- Clear success criteria
|
||||
|
||||
### 5. Output Section
|
||||
|
||||
```markdown
|
||||
## Output
|
||||
|
||||
\`\`\`markdown
|
||||
## Deployment Complete
|
||||
|
||||
### Environment
|
||||
Production
|
||||
|
||||
### Changes Deployed
|
||||
- API v2.3.1
|
||||
- Database migration: add_user_preferences
|
||||
- Updated 15 files
|
||||
|
||||
### Verification
|
||||
- Health check: ✓ Passed
|
||||
- Smoke tests: ✓ Passed
|
||||
|
||||
### Rollback Command
|
||||
/rollback production v2.3.0
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
Show what the successful output should look like.
|
||||
|
||||
### 6. Examples Section
|
||||
|
||||
```markdown
|
||||
## Example
|
||||
|
||||
**Input**: `/deploy production`
|
||||
|
||||
**Output**:
|
||||
1. Runs test suite (2 min)
|
||||
2. Builds production bundle (1 min)
|
||||
3. Deploys to production servers
|
||||
4. Runs smoke tests
|
||||
5. Reports deployment status
|
||||
```
|
||||
|
||||
Provide concrete examples of usage.
|
||||
|
||||
### 7. Flags Section
|
||||
|
||||
```markdown
|
||||
## Flags
|
||||
|
||||
| Flag | Description | Example |
|
||||
|------|-------------|---------|
|
||||
| `--skip-tests` | Skip pre-deployment tests | `/deploy staging --skip-tests` |
|
||||
| `--force` | Force deployment without confirmation | `/deploy prod --force` |
|
||||
| `--rollback` | Rollback to previous version | `/deploy prod --rollback` |
|
||||
```
|
||||
|
||||
Document all available flags.
|
||||
|
||||
## Complete Example: Custom Deploy Command
|
||||
|
||||
Here's a real-world example:
|
||||
|
||||
```markdown
|
||||
# /deploy - Deploy Application
|
||||
|
||||
## Purpose
|
||||
|
||||
Deploy the application to specified environment with automated checks,
|
||||
database migrations, and verification steps.
|
||||
|
||||
## Usage
|
||||
|
||||
\`\`\`
|
||||
/deploy [environment]
|
||||
\`\`\`
|
||||
|
||||
## Arguments
|
||||
|
||||
- `environment`: Target environment (staging, production)
|
||||
|
||||
---
|
||||
|
||||
Deploy to **$ARGUMENTS** environment:
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Pre-deployment Checks
|
||||
|
||||
1. **Verify Environment Configuration**
|
||||
- Check `.env.[environment]` file exists
|
||||
- Verify required secrets are set
|
||||
- Confirm environment is accessible
|
||||
|
||||
2. **Run Test Suite**
|
||||
```bash
|
||||
pnpm test
|
||||
pnpm test:e2e
|
||||
```
|
||||
- All tests must pass
|
||||
- Coverage must be >= 80%
|
||||
|
||||
3. **Check for Breaking Changes**
|
||||
- Review CHANGELOG.md
|
||||
- Identify migration requirements
|
||||
- Confirm database backup exists
|
||||
|
||||
### Phase 2: Build
|
||||
|
||||
1. **Build Production Bundle**
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
- Verify build completes without errors
|
||||
- Check bundle size
|
||||
- Validate output directory
|
||||
|
||||
2. **Run Database Migrations**
|
||||
```bash
|
||||
pnpm migrate:$ARGUMENTS
|
||||
```
|
||||
- Apply pending migrations
|
||||
- Verify migration success
|
||||
- Create rollback script
|
||||
|
||||
### Phase 3: Deploy
|
||||
|
||||
1. **Deploy to Environment**
|
||||
```bash
|
||||
pnpm deploy:$ARGUMENTS
|
||||
```
|
||||
- Upload built assets
|
||||
- Update environment variables
|
||||
- Restart services
|
||||
|
||||
2. **Health Checks**
|
||||
- Wait for services to start (30s)
|
||||
- Verify API health endpoint
|
||||
- Check database connectivity
|
||||
|
||||
### Phase 4: Verification
|
||||
|
||||
1. **Run Smoke Tests**
|
||||
```bash
|
||||
pnpm smoke:$ARGUMENTS
|
||||
```
|
||||
- Test critical user paths
|
||||
- Verify external integrations
|
||||
- Check error rates
|
||||
|
||||
2. **Monitor Deployment**
|
||||
- Check application logs for errors
|
||||
- Monitor performance metrics
|
||||
- Verify no spike in error rate
|
||||
|
||||
### Phase 5: Documentation
|
||||
|
||||
1. **Update Deployment Log**
|
||||
- Record deployment time
|
||||
- Note version deployed
|
||||
- List any manual steps taken
|
||||
|
||||
2. **Notify Team**
|
||||
- Post to Slack #deployments channel
|
||||
- Include deployment summary
|
||||
- Provide rollback instructions
|
||||
|
||||
## Output
|
||||
|
||||
\`\`\`markdown
|
||||
## Deployment Complete: $ARGUMENTS
|
||||
|
||||
### Version
|
||||
v2.3.1 (commit: abc1234)
|
||||
|
||||
### Deployment Time
|
||||
2024-01-15 14:30 UTC (Duration: 4m 32s)
|
||||
|
||||
### Changes Deployed
|
||||
- Feature: User profile redesign
|
||||
- Fix: Payment processing timeout
|
||||
- Database: Migration #045 (add_user_preferences)
|
||||
|
||||
### Verification Results
|
||||
- Health Check: ✓ Passed
|
||||
- Smoke Tests: ✓ All passed (12/12)
|
||||
- Error Rate: 0.01% (normal)
|
||||
|
||||
### Rollback Command
|
||||
If issues arise, rollback with:
|
||||
\`/rollback $ARGUMENTS v2.3.0\`
|
||||
|
||||
### Monitoring
|
||||
- Dashboard: https://monitoring.example.com
|
||||
- Logs: https://logs.example.com
|
||||
\`\`\`
|
||||
|
||||
## Example
|
||||
|
||||
**Input**: `/deploy production`
|
||||
|
||||
**Output**:
|
||||
1. Runs full test suite (3 min)
|
||||
2. Builds production bundle (2 min)
|
||||
3. Applies database migrations (30s)
|
||||
4. Deploys to production cluster (1 min)
|
||||
5. Runs smoke tests (1 min)
|
||||
6. Posts deployment notification to Slack
|
||||
7. Provides rollback command
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | Description | Example |
|
||||
|------|-------------|---------|
|
||||
| `--skip-tests` | Skip test suite (not recommended for production) | `--skip-tests` |
|
||||
| `--skip-migrations` | Skip database migrations | `--skip-migrations` |
|
||||
| `--dry-run` | Simulate deployment without executing | `--dry-run` |
|
||||
| `--force` | Skip confirmation prompts | `--force` |
|
||||
|
||||
### Flag Usage
|
||||
|
||||
```bash
|
||||
/deploy staging --skip-tests # Deploy to staging without tests
|
||||
/deploy production --dry-run # Simulate production deployment
|
||||
/deploy production --skip-migrations # Deploy without DB changes
|
||||
```
|
||||
|
||||
<!-- CUSTOMIZATION POINT -->
|
||||
## Project-Specific Variations
|
||||
|
||||
Modify the workflow based on your deployment strategy:
|
||||
|
||||
- Add CDN cache invalidation steps
|
||||
- Include blue-green deployment logic
|
||||
- Add feature flag configuration
|
||||
- Include monitoring alert setup
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Keep Commands Focused
|
||||
|
||||
Each command should do ONE thing well:
|
||||
|
||||
```markdown
|
||||
# Good: Focused commands
|
||||
/deploy [env] # Just deployment
|
||||
/migrate [env] # Just migrations
|
||||
/rollback [env] # Just rollback
|
||||
|
||||
# Bad: Doing too much
|
||||
/deploy-and-test-and-notify [env]
|
||||
```
|
||||
|
||||
### 2. Use Clear Phase Names
|
||||
|
||||
```markdown
|
||||
# Good: Clear phases
|
||||
### Phase 1: Pre-deployment Checks
|
||||
### Phase 2: Build and Test
|
||||
### Phase 3: Deploy
|
||||
|
||||
# Bad: Vague phases
|
||||
### Phase 1: Setup
|
||||
### Phase 2: Main stuff
|
||||
### Phase 3: Finish
|
||||
```
|
||||
|
||||
### 3. Provide Verification Steps
|
||||
|
||||
```markdown
|
||||
## Workflow
|
||||
|
||||
### Phase 2: Build
|
||||
|
||||
1. **Build Application**
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
|
||||
**Verification**:
|
||||
- Check `dist/` folder exists
|
||||
- Verify no build errors in output
|
||||
- Confirm bundle size < 500KB
|
||||
```
|
||||
|
||||
### 4. Include Error Handling
|
||||
|
||||
```markdown
|
||||
### Phase 3: Deploy
|
||||
|
||||
1. **Deploy to Server**
|
||||
- Upload build artifacts
|
||||
|
||||
**If deployment fails**:
|
||||
- Check server connectivity
|
||||
- Verify deployment credentials
|
||||
- Review server logs at `/var/log/app.log`
|
||||
- Consider using `--force` flag
|
||||
```
|
||||
|
||||
### 5. Add Real Examples
|
||||
|
||||
```markdown
|
||||
## Example
|
||||
|
||||
**Scenario**: Deploy new feature to staging
|
||||
|
||||
**Input**: `/deploy staging`
|
||||
|
||||
**What happens**:
|
||||
1. ✓ Tests pass (2m 15s)
|
||||
2. ✓ Build succeeds (45s)
|
||||
3. ✓ Migrations applied (2 migrations)
|
||||
4. ✓ Deployment complete (30s)
|
||||
5. ✓ Smoke tests pass (5/5)
|
||||
|
||||
**Output**: Deployment summary with rollback command
|
||||
```
|
||||
|
||||
## Common Command Patterns
|
||||
|
||||
### Pattern 1: Multi-Step Workflow
|
||||
|
||||
```markdown
|
||||
# /release - Create Release
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Prepare
|
||||
1. Verify clean working directory
|
||||
2. Pull latest changes
|
||||
3. Run full test suite
|
||||
|
||||
### Phase 2: Version
|
||||
1. Bump version number
|
||||
2. Update CHANGELOG.md
|
||||
3. Commit version changes
|
||||
|
||||
### Phase 3: Release
|
||||
1. Create git tag
|
||||
2. Push to remote
|
||||
3. Trigger CI/CD pipeline
|
||||
|
||||
### Phase 4: Verify
|
||||
1. Wait for CI build
|
||||
2. Verify release artifacts
|
||||
3. Post release notes
|
||||
```
|
||||
|
||||
### Pattern 2: Interactive Workflow
|
||||
|
||||
```markdown
|
||||
# /onboard - Onboard New Team Member
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Environment Setup
|
||||
1. **Ask for GitHub username**
|
||||
- Add to organization
|
||||
- Add to relevant teams
|
||||
|
||||
2. **Ask for preferred IDE**
|
||||
- Provide setup instructions
|
||||
- Share configuration files
|
||||
```
|
||||
|
||||
### Pattern 3: Conditional Workflow
|
||||
|
||||
```markdown
|
||||
# /optimize - Optimize Performance
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Analyze
|
||||
1. Run performance profiler
|
||||
2. Identify bottlenecks
|
||||
|
||||
**If database is bottleneck**:
|
||||
- Go to Phase 2: Database Optimization
|
||||
|
||||
**If API is bottleneck**:
|
||||
- Go to Phase 3: API Optimization
|
||||
```
|
||||
|
||||
## Testing Your Command
|
||||
|
||||
After creating a command, test it:
|
||||
|
||||
1. **Invoke it**: `/your-command test input`
|
||||
2. **Verify behavior**: Check that Claude follows the workflow
|
||||
3. **Test flags**: Try each flag combination
|
||||
4. **Check output**: Ensure output matches template
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Create Custom Modes](/claudekit/customization/creating-modes/) — Define behavioral patterns
|
||||
- [Create Custom Skills](/claudekit/customization/creating-skills/) — Add knowledge modules
|
||||
- [Configure CLAUDE.md](/claudekit/customization/claude-md/) — Set project standards
|
||||
|
||||
## Examples to Study
|
||||
|
||||
Check these built-in commands for inspiration:
|
||||
|
||||
- `/feature` — Complex multi-phase workflow
|
||||
- `/fix` — Debugging workflow with error handling
|
||||
- `/ship` — Git workflow automation
|
||||
- `/tdd` — Methodology-driven development
|
||||
@@ -0,0 +1,665 @@
|
||||
---
|
||||
title: Creating Custom Modes
|
||||
description: Learn how to create custom behavioral modes for different work contexts.
|
||||
---
|
||||
|
||||
# Creating Custom Modes
|
||||
|
||||
Modes change how Claude behaves, thinks, and communicates. This guide shows you how to create custom modes for your specific work contexts.
|
||||
|
||||
## What Are Modes?
|
||||
|
||||
Modes are behavioral configurations that adjust:
|
||||
|
||||
- **Communication style** — Verbose vs. concise, formal vs. casual
|
||||
- **Problem-solving approach** — Exploratory vs. direct, sequential vs. parallel
|
||||
- **Output format** — Detailed explanations vs. code-only, structured vs. free-form
|
||||
|
||||
Think of modes as "personality presets" for different types of work.
|
||||
|
||||
## Mode File Structure
|
||||
|
||||
Modes are markdown files in `.claude/modes/`:
|
||||
|
||||
```
|
||||
.claude/modes/
|
||||
├── your-mode.md # /mode your-mode
|
||||
├── pair-programming.md # /mode pair-programming
|
||||
└── emergency-debug.md # /mode emergency-debug
|
||||
```
|
||||
|
||||
The filename (without `.md`) becomes the mode name.
|
||||
|
||||
## Mode Template
|
||||
|
||||
Here's the complete template for a mode file:
|
||||
|
||||
```markdown
|
||||
# Mode Name
|
||||
|
||||
## Description
|
||||
|
||||
Brief description of what this mode does and when to use it.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Scenario 1
|
||||
- Scenario 2
|
||||
- Scenario 3
|
||||
|
||||
---
|
||||
|
||||
## Behavior
|
||||
|
||||
### Communication
|
||||
- How to communicate in this mode
|
||||
- What tone to use
|
||||
- Level of verbosity
|
||||
|
||||
### Problem Solving
|
||||
- How to approach problems
|
||||
- What to prioritize
|
||||
- What to avoid
|
||||
|
||||
### Output Format
|
||||
- What format to use for responses
|
||||
- How to structure information
|
||||
- What to include/exclude
|
||||
|
||||
---
|
||||
|
||||
## Activation
|
||||
|
||||
\`\`\`
|
||||
Use mode: mode-name
|
||||
\`\`\`
|
||||
|
||||
Or use command flag:
|
||||
\`\`\`
|
||||
/command --mode=mode-name [args]
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
## Example Behaviors
|
||||
|
||||
### Before [Action]
|
||||
\`\`\`
|
||||
Example of behavior in this mode
|
||||
\`\`\`
|
||||
|
||||
### [Another Scenario]
|
||||
\`\`\`
|
||||
Example of different behavior
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
## Combines Well With
|
||||
|
||||
- Related commands or modes
|
||||
- Complementary workflows
|
||||
```
|
||||
|
||||
## Mode Anatomy
|
||||
|
||||
### 1. Header and Description
|
||||
|
||||
```markdown
|
||||
# Pair Programming Mode
|
||||
|
||||
## Description
|
||||
|
||||
Interactive development mode that simulates pair programming with
|
||||
continuous feedback, explanations, and collaborative problem-solving.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Learning new codebase or technology
|
||||
- Working through complex problems
|
||||
- When you want to understand the "why" behind decisions
|
||||
- Teaching or mentoring scenarios
|
||||
```
|
||||
|
||||
Define:
|
||||
|
||||
- Mode name (clear and descriptive)
|
||||
- What it does (2-3 sentences)
|
||||
- When to activate it
|
||||
|
||||
### 2. Behavior Section
|
||||
|
||||
```markdown
|
||||
## Behavior
|
||||
|
||||
### Communication
|
||||
- Explain reasoning behind every decision
|
||||
- Ask clarifying questions before implementing
|
||||
- Use "we" language (collaborative tone)
|
||||
- Provide alternatives when multiple approaches exist
|
||||
|
||||
### Problem Solving
|
||||
- Think out loud while working
|
||||
- Break down complex problems step-by-step
|
||||
- Suggest improvements to existing code
|
||||
- Point out potential issues before they become problems
|
||||
|
||||
### Output Format
|
||||
- Show code with inline explanations
|
||||
- Include "why" comments
|
||||
- Provide learning opportunities
|
||||
- Offer refactoring suggestions
|
||||
```
|
||||
|
||||
This is the core of the mode — it tells Claude HOW to behave.
|
||||
|
||||
### 3. Activation Instructions
|
||||
|
||||
```markdown
|
||||
## Activation
|
||||
|
||||
\`\`\`
|
||||
Use mode: pair-programming
|
||||
\`\`\`
|
||||
|
||||
Or use command flag:
|
||||
\`\`\`
|
||||
/feature --mode=pair-programming "add user auth"
|
||||
/fix --mode=pair-programming "bug in payment"
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
Show both ways to activate the mode.
|
||||
|
||||
### 4. Example Behaviors
|
||||
|
||||
```markdown
|
||||
## Example Behaviors
|
||||
|
||||
### Before Writing Code
|
||||
\`\`\`
|
||||
Let me explain my approach before we code:
|
||||
|
||||
1. We'll add authentication middleware to the router
|
||||
2. This will check for a valid JWT token
|
||||
3. We should also handle token expiration
|
||||
|
||||
Does this approach make sense? Any concerns?
|
||||
\`\`\`
|
||||
|
||||
### During Implementation
|
||||
\`\`\`typescript
|
||||
// Let's add the auth middleware
|
||||
// We're using JWT because it's stateless and scales well
|
||||
export const authMiddleware = async (req, res, next) => {
|
||||
// First, we extract the token from the Authorization header
|
||||
const token = req.headers.authorization?.split(' ')[1];
|
||||
|
||||
// We should validate it exists before proceeding
|
||||
if (!token) {
|
||||
return res.status(401).json({ error: 'No token provided' });
|
||||
}
|
||||
|
||||
// Now let's verify it...
|
||||
// What error handling do you prefer here?
|
||||
\`\`\`
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
Provide concrete examples of how the mode changes behavior.
|
||||
|
||||
### 5. Integration Suggestions
|
||||
|
||||
```markdown
|
||||
## Combines Well With
|
||||
|
||||
- `/feature` command — Collaborative feature development
|
||||
- `/refactor` command — Understanding refactoring decisions
|
||||
- `deep-research` mode — When learning requires research
|
||||
```
|
||||
|
||||
Suggest complementary commands and modes.
|
||||
|
||||
## Complete Example: Emergency Debug Mode
|
||||
|
||||
Here's a real-world example:
|
||||
|
||||
```markdown
|
||||
# Emergency Debug Mode
|
||||
|
||||
## Description
|
||||
|
||||
Fast, focused debugging mode for production issues. Prioritizes speed,
|
||||
minimal output, and getting systems operational over perfect solutions.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Production is down
|
||||
- Critical bug affecting users
|
||||
- Time-sensitive issues
|
||||
- Emergency hotfixes
|
||||
- When you need to ship a fix NOW
|
||||
|
||||
---
|
||||
|
||||
## Behavior
|
||||
|
||||
### Communication
|
||||
- No pleasantries or explanations
|
||||
- Direct commands and code only
|
||||
- Skip "why" unless asked
|
||||
- Use short, imperative sentences
|
||||
|
||||
### Problem Solving
|
||||
- Jump straight to most likely cause
|
||||
- Apply quick fixes over perfect solutions
|
||||
- Defer refactoring to later
|
||||
- Focus on symptom relief first
|
||||
- Add TODO comments for proper fixes
|
||||
|
||||
### Output Format
|
||||
- Code blocks without surrounding prose
|
||||
- Bullet points over paragraphs
|
||||
- Commands to run, not explanations
|
||||
- Immediate actionable steps
|
||||
|
||||
### Speed Over Perfection
|
||||
- Quick fixes are acceptable
|
||||
- Technical debt is acceptable
|
||||
- Tests can be added later
|
||||
- Documentation can wait
|
||||
- Focus: Get it working NOW
|
||||
|
||||
---
|
||||
|
||||
## Activation
|
||||
|
||||
\`\`\`
|
||||
Use mode: emergency-debug
|
||||
\`\`\`
|
||||
|
||||
Or use command flag:
|
||||
\`\`\`
|
||||
/fix --mode=emergency-debug "production API down"
|
||||
/deploy --mode=emergency-debug "hotfix-123"
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
## Example Behaviors
|
||||
|
||||
### Problem Report
|
||||
**User**: "Production API returning 500 errors"
|
||||
|
||||
**Response**:
|
||||
\`\`\`bash
|
||||
# Check logs
|
||||
tail -f /var/log/api/error.log
|
||||
|
||||
# Common causes:
|
||||
1. Database connection
|
||||
2. Memory leak
|
||||
3. External API timeout
|
||||
|
||||
# Quick check:
|
||||
curl -v https://api.example.com/health
|
||||
\`\`\`
|
||||
|
||||
### Immediate Fix
|
||||
\`\`\`typescript
|
||||
// Quick fix: Add timeout to prevent hanging
|
||||
const response = await fetch(url, {
|
||||
signal: AbortSignal.timeout(5000) // 5s timeout
|
||||
});
|
||||
|
||||
// TODO: Investigate why external API is slow
|
||||
// TODO: Add proper retry logic
|
||||
// TODO: Add monitoring for this endpoint
|
||||
\`\`\`
|
||||
|
||||
### Deployment
|
||||
\`\`\`bash
|
||||
# Skip tests for emergency deploy
|
||||
git add .
|
||||
git commit -m "hotfix: add API timeout"
|
||||
git push origin hotfix/api-timeout
|
||||
|
||||
# Deploy immediately
|
||||
./deploy.sh production --skip-tests --force
|
||||
|
||||
# Monitor for errors
|
||||
watch -n 2 'curl -s https://api.example.com/health'
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
## Post-Emergency Checklist
|
||||
|
||||
After crisis is resolved, create follow-up tasks:
|
||||
|
||||
\`\`\`markdown
|
||||
## TODO: Clean up emergency fix
|
||||
|
||||
- [ ] Add tests for timeout handling
|
||||
- [ ] Investigate root cause of slow API
|
||||
- [ ] Implement proper retry logic
|
||||
- [ ] Add monitoring/alerts
|
||||
- [ ] Document incident
|
||||
- [ ] Schedule post-mortem
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
## Combines Well With
|
||||
|
||||
- `/fix` command — Emergency bug fixes
|
||||
- `/deploy` command — Rapid deployment
|
||||
- `token-efficient` mode — Fast, minimal output
|
||||
- `--format=ultra` flag — Code-only responses
|
||||
|
||||
---
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- Feature development
|
||||
- Refactoring work
|
||||
- Code review
|
||||
- Learning new patterns
|
||||
- Non-urgent bugs
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Define Clear Boundaries
|
||||
|
||||
```markdown
|
||||
## When to Use
|
||||
- Specific scenario A
|
||||
- Specific scenario B
|
||||
|
||||
## When NOT to Use
|
||||
- Different scenario X
|
||||
- Different scenario Y
|
||||
```
|
||||
|
||||
Help users know when to activate the mode.
|
||||
|
||||
### 2. Show Behavior Changes with Examples
|
||||
|
||||
```markdown
|
||||
## Example Behaviors
|
||||
|
||||
### Standard Mode
|
||||
\`\`\`
|
||||
Let me implement the user authentication feature. First, I'll
|
||||
explain the architecture I'm proposing...
|
||||
\`\`\`
|
||||
|
||||
### This Mode
|
||||
\`\`\`typescript
|
||||
// Auth middleware
|
||||
export const auth = (req, res, next) => {
|
||||
const token = req.headers.authorization?.split(' ')[1];
|
||||
if (!token) return res.status(401).send();
|
||||
// ...
|
||||
}
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
Contrast with default behavior to show the difference.
|
||||
|
||||
### 3. Be Specific About Communication Style
|
||||
|
||||
```markdown
|
||||
### Communication
|
||||
- Use active voice: "Run this command" not "You could run this command"
|
||||
- No hedging: "This fixes it" not "This should probably fix it"
|
||||
- Short sentences: Average 10 words
|
||||
- No adjectives unless critical
|
||||
```
|
||||
|
||||
Precise instructions produce consistent behavior.
|
||||
|
||||
### 4. Address Multiple Dimensions
|
||||
|
||||
Cover all three behavioral dimensions:
|
||||
|
||||
```markdown
|
||||
### Communication
|
||||
[How to talk]
|
||||
|
||||
### Problem Solving
|
||||
[How to think]
|
||||
|
||||
### Output Format
|
||||
[How to structure responses]
|
||||
```
|
||||
|
||||
### 5. Provide Output Format Examples
|
||||
|
||||
```markdown
|
||||
### Output Format
|
||||
|
||||
\`\`\`markdown
|
||||
## Problem: [Issue]
|
||||
|
||||
### Root Cause
|
||||
[One sentence]
|
||||
|
||||
### Fix
|
||||
\`\`\`[code]\`\`\`
|
||||
|
||||
### Test
|
||||
\`\`\`[command]\`\`\`
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
## Common Mode Patterns
|
||||
|
||||
### Pattern 1: Verbosity Spectrum
|
||||
|
||||
```markdown
|
||||
# Ultra-Verbose Mode
|
||||
|
||||
### Communication
|
||||
- Explain every decision in detail
|
||||
- Provide historical context
|
||||
- Include multiple examples
|
||||
- Add learning resources
|
||||
|
||||
# Ultra-Concise Mode
|
||||
|
||||
### Communication
|
||||
- Code only, no prose
|
||||
- One-line comments max
|
||||
- Assume expert knowledge
|
||||
- Skip obvious steps
|
||||
```
|
||||
|
||||
### Pattern 2: Interaction Style
|
||||
|
||||
```markdown
|
||||
# Interactive Mode
|
||||
|
||||
### Communication
|
||||
- Ask questions before proceeding
|
||||
- Validate each step
|
||||
- Present options for user choice
|
||||
- Collaborative decision-making
|
||||
|
||||
# Autonomous Mode
|
||||
|
||||
### Communication
|
||||
- Make decisions independently
|
||||
- Move through phases without stopping
|
||||
- Report results at end
|
||||
- Minimal back-and-forth
|
||||
```
|
||||
|
||||
### Pattern 3: Focus Area
|
||||
|
||||
```markdown
|
||||
# Security-First Mode
|
||||
|
||||
### Problem Solving
|
||||
- Security is top priority
|
||||
- Flag any potential vulnerability
|
||||
- Suggest secure alternatives
|
||||
- Reference OWASP guidelines
|
||||
|
||||
# Performance-First Mode
|
||||
|
||||
### Problem Solving
|
||||
- Optimize for speed
|
||||
- Minimize resource usage
|
||||
- Benchmark all changes
|
||||
- Profile before/after
|
||||
```
|
||||
|
||||
### Pattern 4: Workflow Style
|
||||
|
||||
```markdown
|
||||
# Exploratory Mode
|
||||
|
||||
### Problem Solving
|
||||
- Generate multiple alternatives
|
||||
- Discuss trade-offs
|
||||
- Delay final decisions
|
||||
- Map solution space
|
||||
|
||||
# Execution Mode
|
||||
|
||||
### Problem Solving
|
||||
- Follow established patterns
|
||||
- Use proven solutions
|
||||
- Move quickly to implementation
|
||||
- Avoid bikeshedding
|
||||
```
|
||||
|
||||
## Advanced Mode Features
|
||||
|
||||
### Combining Modes
|
||||
|
||||
Modes can reference other modes:
|
||||
|
||||
```markdown
|
||||
# Deep Security Audit Mode
|
||||
|
||||
Combines:
|
||||
- `security-first` mode — Security focus
|
||||
- `deep-research` mode — Thorough analysis
|
||||
- `review` mode — Critical perspective
|
||||
|
||||
With modifications:
|
||||
- Even more thorough than base modes
|
||||
- Document every finding
|
||||
- Include remediation steps
|
||||
```
|
||||
|
||||
### Conditional Behavior
|
||||
|
||||
```markdown
|
||||
### Problem Solving
|
||||
|
||||
**If problem is well-defined:**
|
||||
- Jump straight to solution
|
||||
- Implement immediately
|
||||
|
||||
**If problem is vague:**
|
||||
- Ask clarifying questions
|
||||
- Propose multiple approaches
|
||||
- Wait for direction
|
||||
```
|
||||
|
||||
### Time-Based Behavior
|
||||
|
||||
```markdown
|
||||
### Communication
|
||||
|
||||
**First message:**
|
||||
- Explain mode activation
|
||||
- Set expectations
|
||||
- Confirm approach
|
||||
|
||||
**Subsequent messages:**
|
||||
- Follow mode strictly
|
||||
- Minimal meta-commentary
|
||||
```
|
||||
|
||||
## Testing Your Mode
|
||||
|
||||
After creating a mode, test it:
|
||||
|
||||
1. **Activate it**: `/mode your-mode`
|
||||
2. **Try various commands**: `/feature`, `/fix`, `/review`
|
||||
3. **Verify behavior changes**: Check communication style, output format
|
||||
4. **Test edge cases**: Complex problems, simple problems
|
||||
5. **Compare to default**: Is the difference clear?
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### Documentation Mode
|
||||
|
||||
```markdown
|
||||
# Documentation Mode
|
||||
|
||||
## When to Use
|
||||
- Writing docs
|
||||
- Explaining code
|
||||
- Creating tutorials
|
||||
|
||||
### Communication
|
||||
- Clear, simple language
|
||||
- Define all terms
|
||||
- Assume beginner audience
|
||||
- Include examples for everything
|
||||
```
|
||||
|
||||
### Code Review Mode
|
||||
|
||||
```markdown
|
||||
# Code Review Mode
|
||||
|
||||
## When to Use
|
||||
- Reviewing PRs
|
||||
- Security audits
|
||||
- Quality checks
|
||||
|
||||
### Problem Solving
|
||||
- Critical analysis
|
||||
- Look for issues
|
||||
- Suggest improvements
|
||||
- Flag anti-patterns
|
||||
```
|
||||
|
||||
### Teaching Mode
|
||||
|
||||
```markdown
|
||||
# Teaching Mode
|
||||
|
||||
## When to Use
|
||||
- Learning new tech
|
||||
- Understanding patterns
|
||||
- Mentoring
|
||||
|
||||
### Communication
|
||||
- Explain "why" not just "how"
|
||||
- Provide context
|
||||
- Use analogies
|
||||
- Check understanding
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Create Custom Commands](/claudekit/customization/creating-commands/) — Build workflow automation
|
||||
- [Create Custom Skills](/claudekit/customization/creating-skills/) — Add knowledge modules
|
||||
- [Configure CLAUDE.md](/claudekit/customization/claude-md/) — Set project standards
|
||||
|
||||
## Examples to Study
|
||||
|
||||
Check these built-in modes for inspiration:
|
||||
|
||||
- `brainstorm` — Exploratory, question-driven
|
||||
- `token-efficient` — Minimal output for cost savings
|
||||
- `deep-research` — Thorough analysis with citations
|
||||
- `implementation` — Code-focused execution
|
||||
@@ -0,0 +1,760 @@
|
||||
---
|
||||
title: Creating Custom Skills
|
||||
description: Learn how to create custom skill modules to extend Claude's knowledge for your tech stack.
|
||||
---
|
||||
|
||||
# Creating Custom Skills
|
||||
|
||||
Skills are knowledge modules that give Claude expertise in specific technologies, frameworks, methodologies, or your project-specific patterns. This guide shows you how to create custom skills.
|
||||
|
||||
## What Are Skills?
|
||||
|
||||
Skills are focused knowledge modules that provide:
|
||||
|
||||
- **Best practices** for languages, frameworks, tools
|
||||
- **Code patterns** and examples
|
||||
- **Common pitfalls** to avoid
|
||||
- **Project-specific conventions** and APIs
|
||||
|
||||
Skills are automatically loaded based on context and can be referenced explicitly in commands.
|
||||
|
||||
## Skill File Structure
|
||||
|
||||
Skills are `SKILL.md` files organized by category:
|
||||
|
||||
```
|
||||
.claude/skills/
|
||||
├── languages/
|
||||
│ ├── python/SKILL.md
|
||||
│ └── rust/SKILL.md
|
||||
├── frameworks/
|
||||
│ ├── react/SKILL.md
|
||||
│ └── svelte/SKILL.md
|
||||
├── databases/
|
||||
│ └── mysql/SKILL.md
|
||||
├── testing/
|
||||
│ └── rspec/SKILL.md
|
||||
├── methodology/
|
||||
│ └── your-workflow/SKILL.md
|
||||
└── custom/
|
||||
├── your-api/SKILL.md
|
||||
└── internal-tools/SKILL.md
|
||||
```
|
||||
|
||||
## Skill Categories
|
||||
|
||||
Organize skills into these standard categories:
|
||||
|
||||
| Category | What Goes Here | Examples |
|
||||
|----------|----------------|----------|
|
||||
| `languages/` | Programming language best practices | python, rust, go |
|
||||
| `frameworks/` | Web frameworks and libraries | svelte, rails, vue |
|
||||
| `databases/` | Database-specific patterns | mysql, cassandra |
|
||||
| `testing/` | Testing frameworks | rspec, mocha |
|
||||
| `devops/` | Infrastructure and deployment | kubernetes, terraform |
|
||||
| `frontend/` | Frontend tools and libraries | tailwind, alpine |
|
||||
| `security/` | Security frameworks | owasp, security-headers |
|
||||
| `api/` | API design and documentation | graphql, grpc |
|
||||
| `methodology/` | Development methodologies | your-tdd, your-review-process |
|
||||
| `custom/` | Project-specific knowledge | internal-api, company-standards |
|
||||
|
||||
## Skill Template
|
||||
|
||||
Here's the complete template for a skill file:
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
|
||||
## Description
|
||||
|
||||
Brief description of what this skill covers and when it's relevant.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Context 1 where this skill applies
|
||||
- Context 2 where this skill applies
|
||||
- Context 3 where this skill applies
|
||||
|
||||
---
|
||||
|
||||
## Core Patterns
|
||||
|
||||
### Pattern 1 Name
|
||||
|
||||
Description of the pattern.
|
||||
|
||||
\`\`\`[language]
|
||||
// Code example showing the pattern
|
||||
\`\`\`
|
||||
|
||||
**When to use:**
|
||||
- Scenario A
|
||||
- Scenario B
|
||||
|
||||
**Avoid:**
|
||||
- Anti-pattern A
|
||||
- Anti-pattern B
|
||||
|
||||
### Pattern 2 Name
|
||||
|
||||
Another pattern with examples.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Practice Name**
|
||||
- What to do
|
||||
- Why it matters
|
||||
- Example
|
||||
|
||||
2. **Another Practice**
|
||||
- Details
|
||||
- Examples
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Pitfall 1**: Description
|
||||
- **Why it's bad**: Explanation
|
||||
- **Solution**: How to avoid
|
||||
|
||||
- **Pitfall 2**: Description
|
||||
- **Why it's bad**: Explanation
|
||||
- **Solution**: How to avoid
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Skill Anatomy
|
||||
|
||||
### 1. Header and Description
|
||||
|
||||
```markdown
|
||||
# Svelte
|
||||
|
||||
## Description
|
||||
|
||||
Modern reactive framework for building web applications. Focuses on
|
||||
compile-time optimization, minimal runtime, and reactive declarations.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Building modern web applications
|
||||
- Writing component-based UIs
|
||||
- When Svelte is in the project's tech stack
|
||||
```
|
||||
|
||||
Clear, concise overview of what the skill covers.
|
||||
|
||||
### 2. Core Patterns
|
||||
|
||||
```markdown
|
||||
## Core Patterns
|
||||
|
||||
### Reactive Declarations
|
||||
|
||||
Svelte automatically tracks dependencies and re-runs reactive statements.
|
||||
|
||||
\`\`\`svelte
|
||||
<script>
|
||||
let count = 0;
|
||||
|
||||
// Reactive declaration - runs when count changes
|
||||
$: doubled = count * 2;
|
||||
|
||||
// Reactive statement - runs when count changes
|
||||
$: {
|
||||
console.log(`Count is ${count}`);
|
||||
console.log(`Doubled is ${doubled}`);
|
||||
}
|
||||
</script>
|
||||
|
||||
<button on:click={() => count++}>
|
||||
Count: {count}, Doubled: {doubled}
|
||||
</button>
|
||||
\`\`\`
|
||||
|
||||
**When to use:**
|
||||
- Derived values that depend on reactive state
|
||||
- Side effects that should run on state changes
|
||||
- Complex computed values
|
||||
|
||||
**Avoid:**
|
||||
- Over-using reactive statements for simple transformations
|
||||
- Creating circular dependencies between reactive declarations
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
Show actual code patterns users will write.
|
||||
|
||||
### 3. Best Practices
|
||||
|
||||
```markdown
|
||||
## Best Practices
|
||||
|
||||
1. **Keep Components Small**
|
||||
- Aim for < 200 lines per component
|
||||
- Extract reusable logic into modules
|
||||
- Use composition over inheritance
|
||||
|
||||
\`\`\`svelte
|
||||
<!-- Good: Small, focused component -->
|
||||
<UserCard {user} />
|
||||
|
||||
<!-- Avoid: Massive component doing everything -->
|
||||
<UserDashboard {user} {posts} {comments} {settings} />
|
||||
\`\`\`
|
||||
|
||||
2. **Use Stores for Shared State**
|
||||
- Don't prop-drill through multiple levels
|
||||
- Use writable stores for app-wide state
|
||||
- Use derived stores for computed values
|
||||
|
||||
\`\`\`javascript
|
||||
// stores.js
|
||||
import { writable, derived } from 'svelte/store';
|
||||
|
||||
export const users = writable([]);
|
||||
export const activeUsers = derived(
|
||||
users,
|
||||
$users => $users.filter(u => u.active)
|
||||
);
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
Actionable advice with examples.
|
||||
|
||||
### 4. Common Pitfalls
|
||||
|
||||
```markdown
|
||||
## Common Pitfalls
|
||||
|
||||
- **Mutating Arrays/Objects Directly**
|
||||
- **Why it's bad**: Svelte can't detect mutations
|
||||
- **Solution**: Use assignment to trigger reactivity
|
||||
|
||||
\`\`\`javascript
|
||||
// ❌ Wrong - won't trigger reactivity
|
||||
items.push(newItem);
|
||||
|
||||
// ✅ Right - triggers reactivity
|
||||
items = [...items, newItem];
|
||||
\`\`\`
|
||||
|
||||
- **Memory Leaks with Subscriptions**
|
||||
- **Why it's bad**: Unsubscribed stores leak memory
|
||||
- **Solution**: Use $ auto-subscription or onDestroy
|
||||
|
||||
\`\`\`svelte
|
||||
<script>
|
||||
import { onDestroy } from 'svelte';
|
||||
import { myStore } from './stores';
|
||||
|
||||
// ✅ Auto-unsubscribes
|
||||
$: value = $myStore;
|
||||
|
||||
// ✅ Manual cleanup
|
||||
const unsubscribe = myStore.subscribe(value => {
|
||||
// ...
|
||||
});
|
||||
onDestroy(unsubscribe);
|
||||
</script>
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
Real issues developers face with solutions.
|
||||
|
||||
## Complete Example: Internal API Skill
|
||||
|
||||
Here's a project-specific skill example:
|
||||
|
||||
```markdown
|
||||
# Internal API Standards
|
||||
|
||||
## Description
|
||||
|
||||
Best practices and conventions for working with our internal REST API.
|
||||
Covers authentication, error handling, pagination, and response formats.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Making API requests to internal services
|
||||
- Building new API endpoints
|
||||
- Reviewing API-related code
|
||||
|
||||
---
|
||||
|
||||
## Core Patterns
|
||||
|
||||
### Authentication
|
||||
|
||||
All API requests require JWT authentication.
|
||||
|
||||
\`\`\`typescript
|
||||
import { apiClient } from '@/lib/api';
|
||||
|
||||
// Client automatically includes auth token
|
||||
const response = await apiClient.get('/users');
|
||||
|
||||
// Manual auth header (if needed)
|
||||
const response = await fetch('/api/users', {
|
||||
headers: {
|
||||
'Authorization': `Bearer ${getAuthToken()}`,
|
||||
'Content-Type': 'application/json'
|
||||
}
|
||||
});
|
||||
\`\`\`
|
||||
|
||||
**Required headers:**
|
||||
- `Authorization: Bearer {token}`
|
||||
- `Content-Type: application/json`
|
||||
|
||||
### Error Handling
|
||||
|
||||
API returns structured errors following this format:
|
||||
|
||||
\`\`\`typescript
|
||||
interface APIError {
|
||||
error: {
|
||||
code: string; // Machine-readable error code
|
||||
message: string; // Human-readable message
|
||||
details?: object; // Additional context
|
||||
field?: string; // Field that caused error (validation)
|
||||
}
|
||||
}
|
||||
|
||||
// Example error response
|
||||
{
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "Email is required",
|
||||
"field": "email"
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**Handle errors consistently:**
|
||||
|
||||
\`\`\`typescript
|
||||
try {
|
||||
const user = await apiClient.post('/users', data);
|
||||
} catch (error) {
|
||||
if (error.code === 'VALIDATION_ERROR') {
|
||||
// Show field error
|
||||
setFieldError(error.field, error.message);
|
||||
} else {
|
||||
// Show generic error
|
||||
showNotification(error.message, 'error');
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### Pagination
|
||||
|
||||
List endpoints support cursor-based pagination.
|
||||
|
||||
\`\`\`typescript
|
||||
interface PaginatedResponse<T> {
|
||||
data: T[];
|
||||
pagination: {
|
||||
next_cursor: string | null;
|
||||
has_more: boolean;
|
||||
}
|
||||
}
|
||||
|
||||
// First page
|
||||
const response = await apiClient.get('/users?limit=20');
|
||||
|
||||
// Next page
|
||||
const response = await apiClient.get(
|
||||
`/users?limit=20&cursor=${response.pagination.next_cursor}`
|
||||
);
|
||||
\`\`\`
|
||||
|
||||
**Pagination parameters:**
|
||||
- `limit`: Number of items (max: 100, default: 20)
|
||||
- `cursor`: Cursor from previous response
|
||||
|
||||
### Filtering and Sorting
|
||||
|
||||
Use query parameters for filtering and sorting.
|
||||
|
||||
\`\`\`typescript
|
||||
// Filter by status
|
||||
GET /users?status=active
|
||||
|
||||
// Sort by field
|
||||
GET /users?sort=created_at&order=desc
|
||||
|
||||
// Multiple filters
|
||||
GET /users?status=active&role=admin&sort=name
|
||||
|
||||
// Search
|
||||
GET /users?q=search+term
|
||||
\`\`\`
|
||||
|
||||
**Standard query parameters:**
|
||||
- `status`: Filter by status field
|
||||
- `q`: Full-text search
|
||||
- `sort`: Field to sort by
|
||||
- `order`: Sort direction (`asc` or `desc`)
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use the API Client**
|
||||
- Don't make raw fetch calls
|
||||
- API client handles auth, retries, errors
|
||||
- Provides TypeScript types
|
||||
|
||||
\`\`\`typescript
|
||||
// ✅ Good
|
||||
import { apiClient } from '@/lib/api';
|
||||
const users = await apiClient.get('/users');
|
||||
|
||||
// ❌ Avoid
|
||||
const response = await fetch('/api/users');
|
||||
const users = await response.json();
|
||||
\`\`\`
|
||||
|
||||
2. **Handle Loading States**
|
||||
- Show loading indicators for async operations
|
||||
- Handle errors gracefully
|
||||
- Provide feedback on success
|
||||
|
||||
\`\`\`typescript
|
||||
const [loading, setLoading] = useState(false);
|
||||
const [error, setError] = useState(null);
|
||||
|
||||
async function loadUsers() {
|
||||
setLoading(true);
|
||||
setError(null);
|
||||
try {
|
||||
const users = await apiClient.get('/users');
|
||||
setUsers(users.data);
|
||||
} catch (err) {
|
||||
setError(err.message);
|
||||
} finally {
|
||||
setLoading(false);
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
3. **Validate Before Sending**
|
||||
- Validate data client-side before API call
|
||||
- Reduces unnecessary API requests
|
||||
- Provides immediate feedback
|
||||
|
||||
\`\`\`typescript
|
||||
async function createUser(data) {
|
||||
// Client-side validation
|
||||
if (!data.email || !data.name) {
|
||||
throw new Error('Email and name are required');
|
||||
}
|
||||
|
||||
if (!isValidEmail(data.email)) {
|
||||
throw new Error('Invalid email format');
|
||||
}
|
||||
|
||||
// API call only if validation passes
|
||||
return apiClient.post('/users', data);
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
4. **Use TypeScript Types**
|
||||
- Import types from `@/types/api`
|
||||
- Type your API responses
|
||||
- Catch type errors at compile time
|
||||
|
||||
\`\`\`typescript
|
||||
import type { User, PaginatedResponse } from '@/types/api';
|
||||
|
||||
const response = await apiClient.get<PaginatedResponse<User>>('/users');
|
||||
// response.data is typed as User[]
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Not Handling 401 Responses**
|
||||
- **Why it's bad**: Users get stuck with expired tokens
|
||||
- **Solution**: API client auto-redirects to login on 401
|
||||
|
||||
\`\`\`typescript
|
||||
// API client handles this automatically
|
||||
// No manual 401 handling needed
|
||||
\`\`\`
|
||||
|
||||
- **Forgetting to Paginate**
|
||||
- **Why it's bad**: Large responses slow down the app
|
||||
- **Solution**: Always use pagination for list endpoints
|
||||
|
||||
\`\`\`typescript
|
||||
// ❌ Wrong - loads all users
|
||||
const users = await apiClient.get('/users');
|
||||
|
||||
// ✅ Right - loads 20 users with pagination
|
||||
const response = await apiClient.get('/users?limit=20');
|
||||
\`\`\`
|
||||
|
||||
- **Hardcoding API URLs**
|
||||
- **Why it's bad**: Breaks when environment changes
|
||||
- **Solution**: Use environment-specific config
|
||||
|
||||
\`\`\`typescript
|
||||
// ❌ Wrong
|
||||
fetch('https://api.example.com/users');
|
||||
|
||||
// ✅ Right - uses env-specific base URL
|
||||
apiClient.get('/users');
|
||||
\`\`\`
|
||||
|
||||
- **Not Handling Rate Limits**
|
||||
- **Why it's bad**: Can hit rate limits on bulk operations
|
||||
- **Solution**: API client includes retry with exponential backoff
|
||||
|
||||
\`\`\`typescript
|
||||
// API client handles 429 automatically
|
||||
// Retries with exponential backoff
|
||||
const users = await apiClient.get('/users');
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
## Error Codes Reference
|
||||
|
||||
| Code | Meaning | Action |
|
||||
|------|---------|--------|
|
||||
| `VALIDATION_ERROR` | Invalid input | Show field error |
|
||||
| `NOT_FOUND` | Resource doesn't exist | Show 404 message |
|
||||
| `UNAUTHORIZED` | Not authenticated | Redirect to login |
|
||||
| `FORBIDDEN` | Insufficient permissions | Show permission error |
|
||||
| `RATE_LIMITED` | Too many requests | Retry after delay |
|
||||
| `SERVER_ERROR` | Internal error | Show generic error |
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Making Requests
|
||||
|
||||
\`\`\`typescript
|
||||
// GET
|
||||
const users = await apiClient.get('/users');
|
||||
|
||||
// POST
|
||||
const user = await apiClient.post('/users', { name: 'John' });
|
||||
|
||||
// PUT
|
||||
const user = await apiClient.put('/users/123', { name: 'Jane' });
|
||||
|
||||
// PATCH
|
||||
const user = await apiClient.patch('/users/123', { status: 'active' });
|
||||
|
||||
// DELETE
|
||||
await apiClient.delete('/users/123');
|
||||
\`\`\`
|
||||
|
||||
### With Query Parameters
|
||||
|
||||
\`\`\`typescript
|
||||
const users = await apiClient.get('/users', {
|
||||
params: {
|
||||
status: 'active',
|
||||
limit: 20,
|
||||
sort: 'name'
|
||||
}
|
||||
});
|
||||
\`\`\`
|
||||
|
||||
### With Custom Headers
|
||||
|
||||
\`\`\`typescript
|
||||
const data = await apiClient.get('/export', {
|
||||
headers: {
|
||||
'Accept': 'text/csv'
|
||||
}
|
||||
});
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
## Best Practices for Writing Skills
|
||||
|
||||
### 1. Keep Skills Focused
|
||||
|
||||
Each skill should cover ONE topic thoroughly:
|
||||
|
||||
```markdown
|
||||
# Good: Focused skills
|
||||
- languages/python/SKILL.md
|
||||
- testing/pytest/SKILL.md
|
||||
- security/owasp/SKILL.md
|
||||
|
||||
# Bad: Too broad
|
||||
- everything-python/SKILL.md
|
||||
```
|
||||
|
||||
### 2. Use Real Code Examples
|
||||
|
||||
```markdown
|
||||
# Good: Real, runnable code
|
||||
\`\`\`python
|
||||
@pytest.fixture
|
||||
def user():
|
||||
return User(id=1, name="Test")
|
||||
|
||||
def test_user_creation(user):
|
||||
assert user.id == 1
|
||||
\`\`\`
|
||||
|
||||
# Bad: Pseudo-code
|
||||
\`\`\`
|
||||
create a fixture
|
||||
use the fixture in a test
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 3. Show What NOT to Do
|
||||
|
||||
```markdown
|
||||
## Common Pitfalls
|
||||
|
||||
- **Using == for null checks**
|
||||
\`\`\`python
|
||||
# ❌ Wrong
|
||||
if value == None:
|
||||
|
||||
# ✅ Right
|
||||
if value is None:
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 4. Link to Official Documentation
|
||||
|
||||
```markdown
|
||||
## Further Reading
|
||||
|
||||
- [Official Svelte Tutorial](https://svelte.dev/tutorial)
|
||||
- [Svelte API Reference](https://svelte.dev/docs)
|
||||
- [Svelte Society Recipes](https://sveltesociety.dev/recipes)
|
||||
```
|
||||
|
||||
### 5. Keep It Scannable
|
||||
|
||||
Use clear headings, bullet points, and code blocks:
|
||||
|
||||
```markdown
|
||||
## Best Practices
|
||||
|
||||
1. **Clear Heading**
|
||||
- Bullet point
|
||||
- Another point
|
||||
|
||||
2. **Another Practice**
|
||||
\`\`\`code
|
||||
example
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
## Skill Size Guidelines
|
||||
|
||||
| Skill Complexity | Lines | Sections |
|
||||
|------------------|-------|----------|
|
||||
| Simple | 50-100 | 2-3 core patterns |
|
||||
| Standard | 100-200 | 3-5 patterns + pitfalls |
|
||||
| Comprehensive | 200-400 | 5+ patterns + examples |
|
||||
|
||||
Aim for **100-200 lines** for most skills.
|
||||
|
||||
## Testing Your Skill
|
||||
|
||||
After creating a skill, test it:
|
||||
|
||||
1. **Reference it**: Mention the technology in a command
|
||||
2. **Verify knowledge**: Check that Claude applies the patterns
|
||||
3. **Test edge cases**: See if pitfalls are avoided
|
||||
4. **Check examples**: Ensure code examples are used
|
||||
|
||||
## Common Skill Types
|
||||
|
||||
### Language Skills
|
||||
|
||||
Focus on syntax, idioms, and best practices:
|
||||
|
||||
```markdown
|
||||
# Go
|
||||
|
||||
## Core Patterns
|
||||
|
||||
### Error Handling
|
||||
### Goroutines and Channels
|
||||
### Interfaces
|
||||
### Defer, Panic, Recover
|
||||
|
||||
## Best Practices
|
||||
## Common Pitfalls
|
||||
```
|
||||
|
||||
### Framework Skills
|
||||
|
||||
Focus on framework-specific patterns:
|
||||
|
||||
```markdown
|
||||
# Rails
|
||||
|
||||
## Core Patterns
|
||||
|
||||
### Models and ActiveRecord
|
||||
### Controllers and RESTful Routes
|
||||
### Views and Partials
|
||||
### Background Jobs
|
||||
|
||||
## Best Practices
|
||||
## Common Pitfalls
|
||||
```
|
||||
|
||||
### Methodology Skills
|
||||
|
||||
Focus on processes and workflows:
|
||||
|
||||
```markdown
|
||||
# Code Review Process
|
||||
|
||||
## Description
|
||||
Our team's code review standards and checklist.
|
||||
|
||||
## Core Patterns
|
||||
|
||||
### Review Checklist
|
||||
### Giving Feedback
|
||||
### Receiving Feedback
|
||||
|
||||
## Best Practices
|
||||
```
|
||||
|
||||
## Organizing Custom Skills
|
||||
|
||||
For project-specific knowledge, use `custom/`:
|
||||
|
||||
```
|
||||
.claude/skills/custom/
|
||||
├── api-standards/SKILL.md # Your API conventions
|
||||
├── deployment/SKILL.md # Deployment procedures
|
||||
├── testing-standards/SKILL.md # Testing requirements
|
||||
└── security-checklist/SKILL.md # Security review items
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Create Custom Commands](/claudekit/customization/creating-commands/) — Build workflow automation
|
||||
- [Create Custom Modes](/claudekit/customization/creating-modes/) — Define behavioral patterns
|
||||
- [Configure CLAUDE.md](/claudekit/customization/claude-md/) — Set project standards
|
||||
|
||||
## Examples to Study
|
||||
|
||||
Check these built-in skills for inspiration:
|
||||
|
||||
- `languages/python/SKILL.md` — Language best practices
|
||||
- `testing/pytest/SKILL.md` — Testing framework patterns
|
||||
- `methodology/test-driven-development/SKILL.md` — Development process
|
||||
- `security/owasp/SKILL.md` — Security guidelines
|
||||
@@ -0,0 +1,236 @@
|
||||
---
|
||||
title: Customization Overview
|
||||
description: Learn how to customize Claude Kit with your own commands, modes, skills, and project settings.
|
||||
---
|
||||
|
||||
# Customization Overview
|
||||
|
||||
Claude Kit is designed to be fully customizable. You can create your own commands, modes, and skills, and configure Claude's behavior for your specific project needs.
|
||||
|
||||
## What Can You Customize?
|
||||
|
||||
### 1. Commands
|
||||
|
||||
Create custom slash commands for your team's specific workflows:
|
||||
|
||||
```bash
|
||||
/deploy-staging # Your deployment workflow
|
||||
/audit-deps # Custom dependency audit
|
||||
/release-notes # Generate release notes your way
|
||||
```
|
||||
|
||||
[Learn how to create commands →](/claudekit/customization/creating-commands/)
|
||||
|
||||
### 2. Modes
|
||||
|
||||
Define behavioral modes for different work contexts:
|
||||
|
||||
```bash
|
||||
/mode pair-programming # Your pair programming style
|
||||
/mode documentation # Documentation-focused mode
|
||||
/mode production-debug # Emergency debugging mode
|
||||
```
|
||||
|
||||
[Learn how to create modes →](/claudekit/customization/creating-modes/)
|
||||
|
||||
### 3. Skills
|
||||
|
||||
Add knowledge modules for your tech stack:
|
||||
|
||||
```bash
|
||||
.claude/skills/
|
||||
├── languages/rust/ # Rust best practices
|
||||
├── frameworks/svelte/ # Svelte patterns
|
||||
└── custom/your-api/ # Your internal API docs
|
||||
```
|
||||
|
||||
[Learn how to create skills →](/claudekit/customization/creating-skills/)
|
||||
|
||||
### 4. CLAUDE.md Configuration
|
||||
|
||||
Configure project-specific behavior, conventions, and agent overrides:
|
||||
|
||||
- Tech stack and architecture
|
||||
- Code conventions
|
||||
- Testing standards
|
||||
- Security requirements
|
||||
- Agent behavior overrides
|
||||
|
||||
[CLAUDE.md reference →](/claudekit/customization/claude-md/)
|
||||
|
||||
## Customization Levels
|
||||
|
||||
Claude Kit supports three levels of customization:
|
||||
|
||||
| Level | What to Change | When to Use |
|
||||
|-------|----------------|-------------|
|
||||
| **Configuration** | Edit `CLAUDE.md` | Set project conventions, tech stack, standards |
|
||||
| **Composition** | Add modes and skills | Extend behavior without coding |
|
||||
| **Extension** | Create commands | Build custom workflows |
|
||||
|
||||
## Quick Start Examples
|
||||
|
||||
### Example 1: Add a Custom Command
|
||||
|
||||
Create `.claude/commands/deploy.md`:
|
||||
|
||||
```markdown
|
||||
# /deploy - Deploy Application
|
||||
|
||||
## Usage
|
||||
/deploy [environment]
|
||||
|
||||
---
|
||||
|
||||
Deploy to **$ARGUMENTS** environment:
|
||||
|
||||
1. Run tests
|
||||
2. Build production bundle
|
||||
3. Deploy to environment
|
||||
4. Verify deployment
|
||||
```
|
||||
|
||||
[Full command creation guide →](/claudekit/customization/creating-commands/)
|
||||
|
||||
### Example 2: Configure for Your Stack
|
||||
|
||||
Edit `.claude/CLAUDE.md`:
|
||||
|
||||
```markdown
|
||||
## Tech Stack
|
||||
|
||||
- **Backend**: Ruby on Rails
|
||||
- **Frontend**: Vue.js
|
||||
- **Database**: MySQL
|
||||
- **Testing**: RSpec, Cypress
|
||||
```
|
||||
|
||||
[Full CLAUDE.md guide →](/claudekit/customization/claude-md/)
|
||||
|
||||
### Example 3: Add a Custom Skill
|
||||
|
||||
Create `.claude/skills/custom/internal-api/SKILL.md`:
|
||||
|
||||
```markdown
|
||||
# Internal API Standards
|
||||
|
||||
## Authentication
|
||||
All endpoints require JWT bearer tokens...
|
||||
|
||||
## Error Handling
|
||||
Use standard error format...
|
||||
```
|
||||
|
||||
[Full skill creation guide →](/claudekit/customization/creating-skills/)
|
||||
|
||||
## File Structure
|
||||
|
||||
Claude Kit customizations live in your `.claude` folder:
|
||||
|
||||
```
|
||||
.claude/
|
||||
├── CLAUDE.md # Main configuration
|
||||
├── commands/ # Custom commands
|
||||
│ ├── deploy.md
|
||||
│ └── your-command.md
|
||||
├── modes/ # Custom modes
|
||||
│ ├── your-mode.md
|
||||
│ └── another-mode.md
|
||||
└── skills/ # Custom skills
|
||||
├── custom/
|
||||
│ └── your-skill/
|
||||
│ └── SKILL.md
|
||||
└── overrides/
|
||||
└── language/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Start Small
|
||||
|
||||
Don't try to customize everything at once:
|
||||
|
||||
1. **First**: Configure `CLAUDE.md` for your project
|
||||
2. **Then**: Add a mode or two for your common workflows
|
||||
3. **Finally**: Create custom commands for repeated tasks
|
||||
|
||||
### Document Your Customizations
|
||||
|
||||
Add comments to your custom files explaining:
|
||||
|
||||
- Why the customization exists
|
||||
- When to use it
|
||||
- What it does differently
|
||||
|
||||
### Share Customizations
|
||||
|
||||
Custom commands and modes are project-specific, so they should be:
|
||||
|
||||
- Committed to version control
|
||||
- Documented in your project README
|
||||
- Shared with your team
|
||||
|
||||
### Keep Skills Focused
|
||||
|
||||
Each skill should:
|
||||
|
||||
- Cover one specific topic
|
||||
- Be 50-200 lines
|
||||
- Include practical examples
|
||||
- Reference official docs
|
||||
|
||||
## Common Customization Patterns
|
||||
|
||||
### Pattern 1: Strict TDD Workflow
|
||||
|
||||
Add to `CLAUDE.md`:
|
||||
|
||||
```markdown
|
||||
## Tester Agent
|
||||
- **TDD Required**: Always write tests first
|
||||
- **Coverage Minimum**: 90%
|
||||
- **Test Type**: Integration tests for all endpoints
|
||||
```
|
||||
|
||||
### Pattern 2: Security-First Reviews
|
||||
|
||||
Create `.claude/modes/security-audit.md`:
|
||||
|
||||
```markdown
|
||||
# Security Audit Mode
|
||||
|
||||
Focus exclusively on security issues:
|
||||
- Authentication/authorization
|
||||
- Input validation
|
||||
- XSS/CSRF protection
|
||||
- Secrets management
|
||||
```
|
||||
|
||||
### Pattern 3: Custom Git Workflow
|
||||
|
||||
Create `.claude/commands/finish-feature.md`:
|
||||
|
||||
```markdown
|
||||
# /finish-feature - Complete Feature
|
||||
|
||||
1. Squash commits
|
||||
2. Update changelog
|
||||
3. Create PR with template
|
||||
4. Assign reviewers
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
Choose what to customize:
|
||||
|
||||
- [Create Custom Commands](/claudekit/customization/creating-commands/) — Build workflow automation
|
||||
- [Create Custom Modes](/claudekit/customization/creating-modes/) — Define behavioral patterns
|
||||
- [Create Custom Skills](/claudekit/customization/creating-skills/) — Add knowledge modules
|
||||
- [Configure CLAUDE.md](/claudekit/customization/claude-md/) — Set project standards
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Check the [example commands](https://github.com/yourusername/claudekit/tree/main/.claude/commands) in the repo
|
||||
- Look at [built-in modes](https://github.com/yourusername/claudekit/tree/main/.claude/modes) for patterns
|
||||
- Review [existing skills](https://github.com/yourusername/claudekit/tree/main/.claude/skills) for structure
|
||||
Reference in New Issue
Block a user