Initial commit
This commit is contained in:
Zhongwei Li
11
.claude-plugin/plugin.json
Normal file
11
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"name": "claude-code-metaskill",
|
||||
"description": "Documentation Skills for all Claude Code features - automatically loads relevant docs when you mention slash commands, sub-agents, hooks, plugins, MCP, output styles, and more",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Reggie Chan"
|
||||
},
|
||||
"skills": [
|
||||
"./skills"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# claude-code-metaskill
|
||||
|
||||
Documentation Skills for all Claude Code features - automatically loads relevant docs when you mention slash commands, sub-agents, hooks, plugins, MCP, output styles, and more
|
||||
125
plugin.lock.json
Normal file
125
plugin.lock.json
Normal file
@@ -0,0 +1,125 @@
|
||||
{
|
||||
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||
"pluginId": "gh:reggiechan74/claude-plugins:plugins/claude-code-metaskill",
|
||||
"normalized": {
|
||||
"repo": null,
|
||||
"ref": "refs/tags/v20251128.0",
|
||||
"commit": "f284cc216a29e0514ed7428489848b79286e7d7b",
|
||||
"treeHash": "240cab90eed40746b2e3eec3a97a54310413ab8d66762a326f112391ec19d866",
|
||||
"generatedAt": "2025-11-28T10:27:56.575748Z",
|
||||
"toolVersion": "publish_plugins.py@0.2.0"
|
||||
},
|
||||
"origin": {
|
||||
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||
"branch": "master",
|
||||
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||
},
|
||||
"manifest": {
|
||||
"name": "claude-code-metaskill",
|
||||
"description": "Documentation Skills for all Claude Code features - automatically loads relevant docs when you mention slash commands, sub-agents, hooks, plugins, MCP, output styles, and more",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"content": {
|
||||
"files": [
|
||||
{
|
||||
"path": "README.md",
|
||||
"sha256": "03c54d26f8cf33012ffe2a4a5a91e0a6a170eaf9d81a8f02c0ba827083f8bd0b"
|
||||
},
|
||||
{
|
||||
"path": ".claude-plugin/plugin.json",
|
||||
"sha256": "faae74b2920c292fcc415dd2ab1c738e1a5bda1586faf27073fac833a566f30d"
|
||||
},
|
||||
{
|
||||
"path": "skills/ide/SKILL.md",
|
||||
"sha256": "999c9d8334abb3205b9c28784c028b17eb188d92cf06e040f0a8bd0f80ae489b"
|
||||
},
|
||||
{
|
||||
"path": "skills/configuration/SKILL.md",
|
||||
"sha256": "bbac9e89d322f32d178e815cd73ec6810f694520ed0c54068b8e0839d998b143"
|
||||
},
|
||||
{
|
||||
"path": "skills/memory/SKILL.md",
|
||||
"sha256": "bec40334e9a06bc1aad5d3c630b32800a1826e48c469454f9b146c28b5c732b1"
|
||||
},
|
||||
{
|
||||
"path": "skills/plugins/SKILL.md",
|
||||
"sha256": "41a605f2331dbbfd574bcaa4fc4478f6ab9e8387b198707691a475cb35761826"
|
||||
},
|
||||
{
|
||||
"path": "skills/git-workflow/SKILL.md",
|
||||
"sha256": "9e087020b67f85e9491de6ed64c87a4ab70bd60e796c46ae52cbf9adb9fc233a"
|
||||
},
|
||||
{
|
||||
"path": "skills/output-styles/SKILL.md",
|
||||
"sha256": "7ae265206df627fbf977d75e343d06b0a0a506a1997c6d8517f0893eb4971e58"
|
||||
},
|
||||
{
|
||||
"path": "skills/interactive-mode/SKILL.md",
|
||||
"sha256": "5dd4f3ade90352035cd1c3ac4a88497e0f35b0b2194938848882225926720b55"
|
||||
},
|
||||
{
|
||||
"path": "skills/agent-skills/SKILL.md",
|
||||
"sha256": "51bded3ab574028489646655ab4728a78ff4931dcc9b7aff21a3b35b2b33629c"
|
||||
},
|
||||
{
|
||||
"path": "skills/sub-agents/SKILL.md",
|
||||
"sha256": "7d800add507eeea486682be335e4fa48a7b51b1fc1ad9b9536f9163373ef1bc1"
|
||||
},
|
||||
{
|
||||
"path": "skills/troubleshooting/SKILL.md",
|
||||
"sha256": "985099d6e6f940ef895fab46f962965c71009afcf912b95ddaf9256eb56f1f87"
|
||||
},
|
||||
{
|
||||
"path": "skills/mcp-tool/SKILL.md",
|
||||
"sha256": "2424dc3cbc4ffe46570da2293ffea954e163818caa52704d8c309ab4c00df2cf"
|
||||
},
|
||||
{
|
||||
"path": "skills/getting-started/SKILL.md",
|
||||
"sha256": "e3f4f10d2ae84619f180f93811e117133b9be9f5f98609af4698cea94082f904"
|
||||
},
|
||||
{
|
||||
"path": "skills/deployment/SKILL.md",
|
||||
"sha256": "42a4c1c9da5a8c14d86d6a177ea06971823265173bebb30c88d1cd500da9818b"
|
||||
},
|
||||
{
|
||||
"path": "skills/hooks/SKILL.md",
|
||||
"sha256": "f5cc131e299dcfa7b4eb37c6f3de45c0948f6b7c8ffc356bd3fedfaa9ca4c540"
|
||||
},
|
||||
{
|
||||
"path": "skills/slash-commands/SKILL.md",
|
||||
"sha256": "1130dfe6ccdc422aa208b8ab26ada983bd7f573bd7f2fa391449bb7fca79a1ab"
|
||||
},
|
||||
{
|
||||
"path": "skills/headless/SKILL.md",
|
||||
"sha256": "7b33d4be6cdc26af0d87ad50c8b2a78e04b06ef9d0775c130b944ce351c7afc6"
|
||||
},
|
||||
{
|
||||
"path": "skills/administration/SKILL.md",
|
||||
"sha256": "714e8b4e3bd0cf7c18f8be172d53cccb6147f468b88467aa3d43a72a9071a086"
|
||||
},
|
||||
{
|
||||
"path": "skills/checkpointing/SKILL.md",
|
||||
"sha256": "89ae3e03790a1d28efe6173cac0c360efdfb0759c1bd431decb045da2d424d88"
|
||||
},
|
||||
{
|
||||
"path": "skills/ci-cd/SKILL.md",
|
||||
"sha256": "d1010a89d145ebc3739632c77474287d19ba940e003d1f553f65c297b51d3101"
|
||||
},
|
||||
{
|
||||
"path": "skills/cli-reference/SKILL.md",
|
||||
"sha256": "46dc3d0ad5799b3ea959cf525630b81f97f60677829307ea63d8a05aed5de47f"
|
||||
},
|
||||
{
|
||||
"path": "skills/overview/SKILL.md",
|
||||
"sha256": "d03fc829f00ef32da6ed97044cd72783c0f82dd83092dd0208a3082413e9fabd"
|
||||
}
|
||||
],
|
||||
"dirSha256": "240cab90eed40746b2e3eec3a97a54310413ab8d66762a326f112391ec19d866"
|
||||
},
|
||||
"security": {
|
||||
"scannedAt": null,
|
||||
"scannerVersion": null,
|
||||
"flags": []
|
||||
}
|
||||
}
|
||||
322
skills/administration/SKILL.md
Normal file
322
skills/administration/SKILL.md
Normal file
@@ -0,0 +1,322 @@
|
||||
---
|
||||
name: administration
|
||||
description: How to monitor usage, track costs, configure analytics, and measure ROI for Claude Code. Use when user asks about monitoring, telemetry, metrics, costs, analytics, or OpenTelemetry.
|
||||
---
|
||||
|
||||
# Claude Code Administration
|
||||
|
||||
## Monitoring Overview
|
||||
|
||||
Claude Code supports **OpenTelemetry (OTel) for metrics and events**. The system exports time series data via standard metrics protocol and events through logs/events protocol.
|
||||
|
||||
### Quick Setup
|
||||
|
||||
Enable telemetry:
|
||||
```bash
|
||||
export CLAUDE_CODE_ENABLE_TELEMETRY=1
|
||||
```
|
||||
|
||||
Configure exporters (optional, pick what you need):
|
||||
```bash
|
||||
# Metrics
|
||||
export OTEL_METRICS_EXPORTER=otlp # Options: otlp, prometheus, console
|
||||
|
||||
# Logs
|
||||
export OTEL_LOGS_EXPORTER=otlp # Options: otlp, console
|
||||
```
|
||||
|
||||
### Export Intervals
|
||||
|
||||
Default intervals:
|
||||
- **Metrics**: 60 seconds
|
||||
- **Logs**: 5 seconds
|
||||
|
||||
Customize intervals:
|
||||
```bash
|
||||
export OTEL_METRIC_EXPORT_INTERVAL=30000 # milliseconds
|
||||
export OTEL_LOGS_EXPORT_INTERVAL=10000 # milliseconds
|
||||
```
|
||||
|
||||
## Available Metrics
|
||||
|
||||
Claude Code tracks eight core metrics:
|
||||
|
||||
### 1. Session Counter
|
||||
CLI sessions started
|
||||
|
||||
**Use for:** Tracking adoption and active users
|
||||
|
||||
### 2. Lines of Code
|
||||
Code additions/removals tracked by type
|
||||
|
||||
**Use for:** Measuring productivity and code generation volume
|
||||
|
||||
### 3. Pull Requests
|
||||
Creation count
|
||||
|
||||
**Use for:** Tracking automated PR generation
|
||||
|
||||
### 4. Commits
|
||||
Git commits via Claude Code
|
||||
|
||||
**Use for:** Measuring development activity
|
||||
|
||||
### 5. Cost Usage
|
||||
Session costs in USD (model-segmented)
|
||||
|
||||
**Use for:** Budget tracking and cost allocation
|
||||
|
||||
**Important:** Cost metrics are approximations. For official billing data, refer to your API provider (Claude Console, AWS Bedrock, or Google Cloud Vertex).
|
||||
|
||||
### 6. Token Usage
|
||||
Tokens consumed (input/output/cache types)
|
||||
|
||||
**Use for:** Understanding API usage patterns and optimizing costs
|
||||
|
||||
### 7. Code Edit Tool Decisions
|
||||
Accept/reject counts per tool
|
||||
|
||||
**Use for:** Understanding user trust and automation acceptance
|
||||
|
||||
### 8. Active Time
|
||||
Actual usage duration in seconds
|
||||
|
||||
**Use for:** Measuring engagement and productivity time
|
||||
|
||||
## Metric Segmentation
|
||||
|
||||
Segment metrics by:
|
||||
- `user.account_uuid` - Individual user tracking
|
||||
- `organization.id` - Team/organization grouping
|
||||
- `session.id` - Session-specific analysis
|
||||
- `model` - Model usage breakdown
|
||||
- `app.version` - Version tracking
|
||||
|
||||
## Events & Logging
|
||||
|
||||
Five event types are exported:
|
||||
|
||||
### 1. User Prompt Events
|
||||
Prompt submissions (content redacted by default)
|
||||
|
||||
**Enable prompt logging:**
|
||||
```bash
|
||||
export OTEL_LOG_USER_PROMPTS=1
|
||||
```
|
||||
|
||||
**Use for:** Understanding user interaction patterns
|
||||
|
||||
### 2. Tool Result Events
|
||||
Tool execution completion with success status and duration
|
||||
|
||||
**Use for:** Monitoring tool performance and reliability
|
||||
|
||||
### 3. API Request Events
|
||||
Claude API calls with cost and token data
|
||||
|
||||
**Use for:** Detailed cost analysis and API usage tracking
|
||||
|
||||
### 4. API Error Events
|
||||
Failed requests with HTTP status codes
|
||||
|
||||
**Use for:** Troubleshooting and reliability monitoring
|
||||
|
||||
### 5. Tool Decision Events
|
||||
User accept/reject actions with decision source
|
||||
|
||||
**Use for:** Understanding automation trust and user preferences
|
||||
|
||||
## Cost Monitoring
|
||||
|
||||
### Cost Tracking Setup
|
||||
|
||||
Monitor costs by model and user:
|
||||
```bash
|
||||
export CLAUDE_CODE_ENABLE_TELEMETRY=1
|
||||
export OTEL_METRICS_EXPORTER=prometheus
|
||||
```
|
||||
|
||||
### Cost Analysis
|
||||
|
||||
View costs segmented by:
|
||||
- Model (Sonnet vs Haiku)
|
||||
- User/account
|
||||
- Session
|
||||
- Time period
|
||||
|
||||
### Budget Alerts
|
||||
|
||||
Implement budget monitoring:
|
||||
1. Export cost metrics to your monitoring system
|
||||
2. Set up alerts for cost thresholds
|
||||
3. Review high-cost sessions
|
||||
4. Optimize model selection and usage patterns
|
||||
|
||||
## Analytics & ROI
|
||||
|
||||
### ROI Measurement Guide
|
||||
|
||||
Reference the [Claude Code ROI Measurement Guide](https://github.com/anthropics/claude-code-monitoring-guide) for:
|
||||
- Docker configurations
|
||||
- Productivity report templates
|
||||
- ROI calculation methods
|
||||
- Team analytics dashboards
|
||||
|
||||
### Key Metrics for ROI
|
||||
|
||||
**Productivity Metrics:**
|
||||
- Lines of code generated per hour
|
||||
- Time saved vs manual coding
|
||||
- PRs created automatically
|
||||
- Issues resolved automatically
|
||||
|
||||
**Quality Metrics:**
|
||||
- Code review findings
|
||||
- Test coverage improvements
|
||||
- Bug reduction rate
|
||||
- Technical debt reduction
|
||||
|
||||
**Adoption Metrics:**
|
||||
- Active users
|
||||
- Session frequency
|
||||
- Feature usage patterns
|
||||
- User satisfaction scores
|
||||
|
||||
## Monitoring Backend Setup
|
||||
|
||||
### Prometheus Setup
|
||||
|
||||
```yaml
|
||||
# prometheus.yml
|
||||
scrape_configs:
|
||||
- job_name: 'claude-code'
|
||||
static_configs:
|
||||
- targets: ['localhost:9464']
|
||||
```
|
||||
|
||||
Start with Prometheus exporter:
|
||||
```bash
|
||||
export OTEL_METRICS_EXPORTER=prometheus
|
||||
claude
|
||||
```
|
||||
|
||||
### Grafana Dashboard
|
||||
|
||||
Create dashboards to visualize:
|
||||
- Cost over time
|
||||
- Token usage trends
|
||||
- Session counts
|
||||
- User activity
|
||||
- Tool acceptance rates
|
||||
|
||||
### Custom Analytics
|
||||
|
||||
Export to your own backend:
|
||||
```bash
|
||||
export OTEL_EXPORTER_OTLP_ENDPOINT=https://your-backend.com
|
||||
export OTEL_EXPORTER_OTLP_HEADERS="api-key=your-key"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Enable Monitoring Early
|
||||
Set up telemetry from day one to establish baselines
|
||||
|
||||
### 2. Segment by Team/Project
|
||||
Use organization and user IDs for proper attribution
|
||||
|
||||
### 3. Monitor Costs Regularly
|
||||
Review cost metrics weekly to identify trends
|
||||
|
||||
### 4. Track Adoption
|
||||
Monitor active users and session frequency
|
||||
|
||||
### 5. Measure Quality Impact
|
||||
Track bug rates and code review findings
|
||||
|
||||
### 6. Set Alert Thresholds
|
||||
Configure alerts for:
|
||||
- Unusual cost spikes
|
||||
- Error rate increases
|
||||
- Low adoption indicators
|
||||
|
||||
### 7. Review Metrics with Teams
|
||||
Share analytics to demonstrate value and identify improvements
|
||||
|
||||
### 8. Optimize Based on Data
|
||||
Use metrics to:
|
||||
- Identify high-value use cases
|
||||
- Optimize model selection
|
||||
- Improve automation acceptance
|
||||
- Reduce costs
|
||||
|
||||
## Privacy Considerations
|
||||
|
||||
**User Prompts:**
|
||||
- Disabled by default
|
||||
- Enable only with user consent: `OTEL_LOG_USER_PROMPTS=1`
|
||||
- Consider data retention policies
|
||||
|
||||
**Sensitive Data:**
|
||||
- Avoid logging sensitive information
|
||||
- Implement data filtering
|
||||
- Review compliance requirements
|
||||
|
||||
**Access Control:**
|
||||
- Restrict metrics access appropriately
|
||||
- Use secure connections for exporters
|
||||
- Encrypt data in transit and at rest
|
||||
|
||||
## Troubleshooting Monitoring
|
||||
|
||||
### Metrics Not Appearing
|
||||
|
||||
1. Verify telemetry is enabled: `CLAUDE_CODE_ENABLE_TELEMETRY=1`
|
||||
2. Check exporter configuration
|
||||
3. Verify backend connectivity
|
||||
4. Review export intervals
|
||||
5. Check for error logs
|
||||
|
||||
### High Costs
|
||||
|
||||
1. Review token usage by model
|
||||
2. Identify high-usage sessions
|
||||
3. Check for inefficient prompts
|
||||
4. Consider using Haiku for simple tasks
|
||||
5. Implement cost controls
|
||||
|
||||
### Low Adoption
|
||||
|
||||
1. Review active user metrics
|
||||
2. Identify barriers to usage
|
||||
3. Provide training and documentation
|
||||
4. Gather user feedback
|
||||
5. Highlight success stories
|
||||
|
||||
## Example Monitoring Stack
|
||||
|
||||
```bash
|
||||
# docker-compose.yml for full monitoring stack
|
||||
version: '3.8'
|
||||
services:
|
||||
prometheus:
|
||||
image: prom/prometheus
|
||||
volumes:
|
||||
- ./prometheus.yml:/etc/prometheus/prometheus.yml
|
||||
ports:
|
||||
- "9090:9090"
|
||||
|
||||
grafana:
|
||||
image: grafana/grafana
|
||||
ports:
|
||||
- "3000:3000"
|
||||
environment:
|
||||
- GF_SECURITY_ADMIN_PASSWORD=admin
|
||||
```
|
||||
|
||||
Configure Claude Code:
|
||||
```bash
|
||||
export CLAUDE_CODE_ENABLE_TELEMETRY=1
|
||||
export OTEL_METRICS_EXPORTER=prometheus
|
||||
export OTEL_EXPORTER_PROMETHEUS_PORT=9464
|
||||
```
|
||||
256
skills/agent-skills/SKILL.md
Normal file
256
skills/agent-skills/SKILL.md
Normal file
@@ -0,0 +1,256 @@
|
||||
---
|
||||
name: agent-skills
|
||||
description: Complete guide to Agent Skills - modular capabilities that extend Claude's functionality. Use when user asks about creating Skills, Skill structure, progressive disclosure, or custom capabilities for Claude.
|
||||
---
|
||||
|
||||
# Agent Skills
|
||||
|
||||
## What Are Agent Skills?
|
||||
|
||||
Agent Skills are modular capabilities that extend Claude's functionality by packaging instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant. They transform Claude from a general-purpose assistant into a domain specialist.
|
||||
|
||||
## Key Benefits
|
||||
|
||||
- **Specialize Claude**: Tailor capabilities for specific task domains
|
||||
- **Reduce repetition**: Create once, reuse across conversations automatically
|
||||
- **Compose capabilities**: Combine multiple Skills for complex workflows
|
||||
|
||||
## How Skills Work
|
||||
|
||||
Skills operate within Claude's virtual machine environment with filesystem access. They use **progressive disclosure**—loading information in stages as needed rather than consuming context upfront.
|
||||
|
||||
### Three Loading Levels
|
||||
|
||||
**Level 1 - Metadata (Always loaded)**
|
||||
YAML frontmatter provides discovery information (~100 tokens per Skill):
|
||||
```yaml
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extract text, fill forms, merge documents
|
||||
---
|
||||
```
|
||||
|
||||
**Level 2 - Instructions (Loaded when triggered)**
|
||||
Main SKILL.md body contains procedural guidance (under 5k tokens). Claude reads this file only when the Skill matches the user's request.
|
||||
|
||||
**Level 3 - Resources (Loaded as needed)**
|
||||
Additional files (FORMS.md, scripts, reference materials) are accessed only when referenced—effectively unlimited content without token penalty.
|
||||
|
||||
## Where Skills Are Available
|
||||
|
||||
- **Claude API**: Pre-built and custom Skills via `skill_id` parameter
|
||||
- **Claude Code**: Filesystem-based custom Skills in `.claude/skills/`
|
||||
- **Claude Agent SDK**: Custom Skills through configuration
|
||||
- **Claude.ai**: Pre-built Skills built-in; custom Skills uploadable by users
|
||||
|
||||
## Pre-Built Agent Skills
|
||||
|
||||
Anthropic provides ready-to-use Skills:
|
||||
- **PowerPoint (pptx)**: Create and edit presentations
|
||||
- **Excel (xlsx)**: Build spreadsheets with data analysis
|
||||
- **Word (docx)**: Generate formatted documents
|
||||
- **PDF (pdf)**: Create formatted PDF reports
|
||||
|
||||
## Skill Structure Requirements
|
||||
|
||||
Every Skill needs a `SKILL.md` file with YAML frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: your-skill-name
|
||||
description: What this does and when to use it
|
||||
---
|
||||
|
||||
# Your Skill Name
|
||||
|
||||
## Instructions
|
||||
[Step-by-step guidance]
|
||||
|
||||
## Examples
|
||||
[Concrete usage examples]
|
||||
```
|
||||
|
||||
**Requirements**:
|
||||
- `name`: Maximum 64 characters, lowercase letters/numbers/hyphens only
|
||||
- `description`: Non-empty, maximum 1024 characters
|
||||
|
||||
## Storage Locations in Claude Code
|
||||
|
||||
1. **Personal Skills**: `~/.claude/skills/skill-name/`
|
||||
2. **Project Skills**: `.claude/skills/skill-name/` (shared via git)
|
||||
3. **Plugin Skills**: bundled with installed plugins
|
||||
|
||||
## Supporting Files
|
||||
|
||||
Skills can include additional resources:
|
||||
- Reference documentation
|
||||
- Example files
|
||||
- Script utilities
|
||||
- Templates
|
||||
|
||||
Claude loads these progressively based on context.
|
||||
|
||||
## Tool Access Control
|
||||
|
||||
Use `allowed-tools` frontmatter to restrict Claude's capabilities when using a Skill:
|
||||
```yaml
|
||||
allowed-tools: Read, Grep, Glob
|
||||
```
|
||||
|
||||
This limits tool usage without requiring permission prompts.
|
||||
|
||||
### Available Tools
|
||||
|
||||
**Tools That Require Permission:**
|
||||
- **Bash** - Execute shell commands
|
||||
- **Edit** - Make targeted file edits
|
||||
- **NotebookEdit** - Modify Jupyter notebook cells
|
||||
- **SlashCommand** - Run custom slash commands
|
||||
- **WebFetch** - Fetch content from URLs
|
||||
- **WebSearch** - Perform web searches
|
||||
- **Write** - Create or overwrite files
|
||||
|
||||
**Tools That Don't Require Permission:**
|
||||
- **Glob** - Find files by pattern matching
|
||||
- **Grep** - Search for patterns in files
|
||||
- **NotebookRead** - Read Jupyter notebooks
|
||||
- **Read** - Read file contents
|
||||
- **Task** - Run sub-agents
|
||||
- **TodoWrite** - Manage task lists
|
||||
|
||||
### Example Tool Configurations
|
||||
|
||||
**Read-only Skill:**
|
||||
```yaml
|
||||
allowed-tools: Read, Grep, Glob
|
||||
```
|
||||
|
||||
**Analysis Skill with web access:**
|
||||
```yaml
|
||||
allowed-tools: Read, Grep, Glob, WebFetch
|
||||
```
|
||||
|
||||
**Code generation Skill:**
|
||||
```yaml
|
||||
allowed-tools: Read, Glob, Grep, Write, Edit, Bash
|
||||
```
|
||||
|
||||
**Research Skill:**
|
||||
```yaml
|
||||
allowed-tools: Read, WebFetch, WebSearch, TodoWrite
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Core Principles
|
||||
|
||||
**Conciseness**: Context windows are shared resources. Only include information Claude doesn't already possess. Challenge each piece: "Does Claude really need this?"
|
||||
|
||||
**Degrees of Freedom**: Match specificity to task fragility:
|
||||
- High freedom (text): Multiple valid approaches exist
|
||||
- Medium freedom (pseudocode): Preferred patterns with variation allowed
|
||||
- Low freedom (exact scripts): Operations are fragile or consistency-critical
|
||||
|
||||
**Multi-Model Testing**: Verify Skills work across Haiku, Sonnet, and Opus since effectiveness depends on the underlying model.
|
||||
|
||||
### Skill Structure
|
||||
|
||||
**Frontmatter Requirements**:
|
||||
- `name`: 64 characters max, lowercase letters/numbers/hyphens only
|
||||
- `description`: Non-empty, 1024 characters max, specific about what and when to use
|
||||
|
||||
**Naming**: Use gerund form ("processing-pdfs") for clarity and consistency across skill collections.
|
||||
|
||||
**Descriptions**: Write in third person, be specific with key terms, explain both functionality and use cases. Avoid vague descriptions like "helps with documents."
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
Keep SKILL.md under 500 lines. Bundle additional content (reference files, examples, domain-specific guides) that Claude loads only when needed. Structure as:
|
||||
- SKILL.md (overview, navigation)
|
||||
- Reference files (one level deep from SKILL.md)
|
||||
- Scripts directory (utility scripts executed, not loaded)
|
||||
|
||||
### Workflows & Feedback Loops
|
||||
|
||||
- Use checklists for complex multi-step processes
|
||||
- Implement validation loops: run validator → fix errors → repeat
|
||||
- Provide templates for strict output requirements
|
||||
- Include input/output examples for style guidance
|
||||
|
||||
### Content Guidelines
|
||||
|
||||
Avoid time-sensitive information. Use consistent terminology throughout ("API endpoint" not mixed with "URL" or "route").
|
||||
|
||||
### Code & Scripts
|
||||
|
||||
- Handle errors explicitly rather than punting to Claude
|
||||
- Justify all configuration values (no "magic numbers")
|
||||
- Provide utility scripts for reliability and token efficiency
|
||||
- Use forward slashes in paths (Unix-style)
|
||||
- Implement validation steps for critical operations
|
||||
- Include verifiable intermediate outputs (plan files)
|
||||
|
||||
## Evaluation & Testing
|
||||
|
||||
Create evaluations before extensive documentation. Build three representative scenarios, establish baselines, write minimal instructions addressing identified gaps, then iterate based on results.
|
||||
|
||||
**Iterative Development**: Work with one Claude instance ("Claude A") to design Skills tested by other instances ("Claude B"), observing real behavior and refining accordingly.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- Windows-style paths (`\`)
|
||||
- Offering excessive options without defaults
|
||||
- Deeply nested file references
|
||||
- Assuming tools are pre-installed
|
||||
- Time-sensitive constraints in documentation
|
||||
|
||||
## Critical Success Factors
|
||||
|
||||
**Description Specificity**: Vague descriptions prevent discovery. Include both functionality and usage triggers with concrete terminology users would mention.
|
||||
|
||||
**File Paths**: Use Unix-style forward slashes consistently.
|
||||
|
||||
**YAML Validation**: Ensure proper opening/closing `---` delimiters and correct indentation (spaces only).
|
||||
|
||||
## Team Distribution
|
||||
|
||||
Recommended approach: distribute via plugins. Alternative: commit Skills to project repositories; team members automatically access them after pulling changes.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
Only use Skills from trusted sources. Malicious Skills could direct Claude to misuse tools or expose data. Thoroughly audit all bundled files, scripts, and external resource references before deploying.
|
||||
|
||||
## Key Limitations
|
||||
|
||||
- **No cross-surface sync**: Skills uploaded to one platform aren't automatically available elsewhere
|
||||
- **No network access**: Skills cannot make external API calls
|
||||
- **Pre-installed packages only**: Cannot install new packages during execution
|
||||
- **Sharing varies**: Claude.ai (individual), API (workspace-wide), Claude Code (personal/project-based)
|
||||
|
||||
## Skills vs Slash Commands
|
||||
|
||||
**Use slash commands for**: Simple, frequently-used prompts that fit in one file.
|
||||
|
||||
**Use Skills for**: Complex capabilities requiring multiple files, scripts, or organizational structure.
|
||||
|
||||
Key difference: Commands require explicit invocation; Skills are discovered automatically based on context.
|
||||
|
||||
## Checklist for Effective Skills
|
||||
|
||||
**Quality**:
|
||||
- Specific description with use cases
|
||||
- Under 500 lines
|
||||
- Proper progressive disclosure
|
||||
- Consistent terminology
|
||||
|
||||
**Code**:
|
||||
- Error handling
|
||||
- Justified constants
|
||||
- Documented scripts
|
||||
- Forward-slash paths
|
||||
- Validation workflows
|
||||
|
||||
**Testing**:
|
||||
- Three evaluations created
|
||||
- Tested across models
|
||||
- Real-world scenarios validated
|
||||
435
skills/checkpointing/SKILL.md
Normal file
435
skills/checkpointing/SKILL.md
Normal file
@@ -0,0 +1,435 @@
|
||||
---
|
||||
name: checkpointing
|
||||
description: How checkpointing works for tracking file changes and rewinding to previous states. Use when user asks about checkpoints, rewinding, rollback, undo, or restoring previous states.
|
||||
---
|
||||
|
||||
# Claude Code Checkpointing
|
||||
|
||||
## Overview
|
||||
|
||||
Claude Code includes an automatic checkpointing system that tracks file edits and allows users to recover from unwanted changes during development sessions.
|
||||
|
||||
## How Checkpointing Works
|
||||
|
||||
### Automatic Tracking
|
||||
|
||||
The system captures code states before each modification.
|
||||
|
||||
**Key features:**
|
||||
- Every user prompt creates a new checkpoint
|
||||
- Checkpoints persist across resumed conversations
|
||||
- Automatic cleanup occurs after 30 days (configurable)
|
||||
|
||||
### What Gets Tracked
|
||||
|
||||
**Tracked:**
|
||||
- Direct file edits via Edit tool
|
||||
- File creations via Write tool
|
||||
- File modifications by Claude
|
||||
|
||||
**Not tracked:**
|
||||
- Files modified by bash commands (`rm`, `mv`, `cp`)
|
||||
- Manual file modifications outside Claude Code
|
||||
- Changes from concurrent sessions (unless they affect files the current session modified)
|
||||
|
||||
## Rewinding Changes
|
||||
|
||||
### Access Rewind Menu
|
||||
|
||||
**Keyboard shortcut:**
|
||||
Press `Esc` twice (quickly)
|
||||
|
||||
**Slash command:**
|
||||
```
|
||||
/rewind
|
||||
```
|
||||
|
||||
### Restoration Options
|
||||
|
||||
When you open the rewind menu, you have three options:
|
||||
|
||||
#### 1. Conversation Only
|
||||
**Keeps:** All code changes
|
||||
**Reverts:** Conversation history to selected checkpoint
|
||||
|
||||
**Use when:**
|
||||
- You want to start conversation over
|
||||
- Code changes are good
|
||||
- You want to try different approach in conversation
|
||||
|
||||
#### 2. Code Only
|
||||
**Keeps:** Conversation history
|
||||
**Reverts:** Files to selected checkpoint
|
||||
|
||||
**Use when:**
|
||||
- Recent changes broke something
|
||||
- Want to undo code changes
|
||||
- Conversation context is valuable
|
||||
|
||||
#### 3. Both Code and Conversation
|
||||
**Reverts:** Everything to selected checkpoint (full rollback)
|
||||
|
||||
**Use when:**
|
||||
- Complete do-over needed
|
||||
- Both code and conversation went wrong
|
||||
- Want to return to known good state
|
||||
|
||||
### Selecting a Checkpoint
|
||||
|
||||
Checkpoints are displayed with:
|
||||
- Timestamp
|
||||
- User prompt that created it
|
||||
- Files affected
|
||||
- Changes summary
|
||||
|
||||
Navigate with arrow keys and select with Enter.
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Testing Different Approaches
|
||||
|
||||
**Scenario:** Try multiple implementation strategies without losing starting point.
|
||||
|
||||
```
|
||||
# Approach 1
|
||||
"implement feature using strategy A"
|
||||
# Review, not ideal
|
||||
|
||||
# Rewind
|
||||
Esc Esc → Select checkpoint → Code only
|
||||
|
||||
# Approach 2
|
||||
"implement feature using strategy B"
|
||||
# Better!
|
||||
```
|
||||
|
||||
### Quick Bug Recovery
|
||||
|
||||
**Scenario:** Recent changes introduced a bug.
|
||||
|
||||
```
|
||||
# Make changes
|
||||
"refactor the authentication module"
|
||||
# Oops, broke login
|
||||
|
||||
# Rewind
|
||||
Esc Esc → Select checkpoint before refactor → Code only
|
||||
|
||||
# Try again differently
|
||||
"refactor authentication but keep existing login flow"
|
||||
```
|
||||
|
||||
### Iterative Development
|
||||
|
||||
**Scenario:** Preserve working states while iterating.
|
||||
|
||||
```
|
||||
# Working state 1
|
||||
"add basic user validation"
|
||||
# Works ✓
|
||||
|
||||
# Iterate
|
||||
"add more complex validation rules"
|
||||
# Issues found
|
||||
|
||||
# Return to working state
|
||||
Esc Esc → Code only
|
||||
|
||||
# Try different iteration
|
||||
"add regex-based validation"
|
||||
```
|
||||
|
||||
### Conversation Reset
|
||||
|
||||
**Scenario:** Conversation got confused or went off track.
|
||||
|
||||
```
|
||||
# Good code changes made
|
||||
"add user profile endpoint"
|
||||
"add user settings endpoint"
|
||||
|
||||
# Conversation gets confusing
|
||||
# Want to restart conversation but keep code
|
||||
|
||||
# Rewind conversation only
|
||||
Esc Esc → Conversation only → Select early checkpoint
|
||||
|
||||
# Fresh conversation start with code intact
|
||||
```
|
||||
|
||||
## Important Limitations
|
||||
|
||||
### Bash Command Changes Not Tracked
|
||||
|
||||
**Not captured:**
|
||||
```
|
||||
!rm file.txt
|
||||
!mv old.txt new.txt
|
||||
!cp source.txt dest.txt
|
||||
!git checkout -b new-branch
|
||||
```
|
||||
|
||||
**Why:** Bash commands run outside Claude's file tracking system.
|
||||
|
||||
**Workaround:**
|
||||
- Use Claude's Edit/Write tools instead when possible
|
||||
- Manually track bash file operations
|
||||
- Use git for version control of important changes
|
||||
|
||||
### External Changes Not Tracked
|
||||
|
||||
**Not captured:**
|
||||
- Manual edits in your text editor
|
||||
- IDE refactorings
|
||||
- File system operations outside Claude Code
|
||||
- Changes from other tools
|
||||
|
||||
**Workaround:**
|
||||
- Use git to track all changes
|
||||
- Create manual checkpoints with git commits
|
||||
- Be aware of what Claude modified vs what you modified
|
||||
|
||||
### Concurrent Session Caveats
|
||||
|
||||
**Limited tracking:**
|
||||
If multiple Claude Code sessions modify the same files, only changes from the current session are tracked for checkpointing.
|
||||
|
||||
**Best practice:**
|
||||
Use one Claude Code session at a time per project.
|
||||
|
||||
## Not a Version Control Replacement
|
||||
|
||||
### Checkpointing vs Git
|
||||
|
||||
| Feature | Checkpointing | Git |
|
||||
|---------|--------------|-----|
|
||||
| **Scope** | Session-level | Repository-wide |
|
||||
| **Duration** | 30 days | Permanent |
|
||||
| **Granularity** | Per prompt | Per commit |
|
||||
| **Collaboration** | Single user | Team |
|
||||
| **Purpose** | Session recovery | Version control |
|
||||
| **Bash tracking** | No | Yes |
|
||||
|
||||
### Use Both Together
|
||||
|
||||
**Git for:**
|
||||
- Permanent history
|
||||
- Collaboration
|
||||
- Branch management
|
||||
- All file changes (including bash)
|
||||
- Release management
|
||||
|
||||
**Checkpointing for:**
|
||||
- Quick session rollback
|
||||
- Trying different approaches
|
||||
- Recovering from mistakes
|
||||
- Conversation management
|
||||
- Rapid iteration
|
||||
|
||||
**Recommended workflow:**
|
||||
```
|
||||
# Regular git commits for milestones
|
||||
git commit -m "Working authentication"
|
||||
|
||||
# Use checkpointing for rapid iteration
|
||||
"try optimization A"
|
||||
Esc Esc → rewind if not good
|
||||
"try optimization B"
|
||||
Esc Esc → rewind if not good
|
||||
"try optimization C"
|
||||
# This one works!
|
||||
|
||||
# Commit the winner
|
||||
git add .
|
||||
git commit -m "Optimized authentication"
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Checkpoint Retention
|
||||
|
||||
**Default:** 30 days
|
||||
|
||||
**Configure retention:**
|
||||
Edit `.claude/settings.json`:
|
||||
```json
|
||||
{
|
||||
"checkpointRetentionDays": 60
|
||||
}
|
||||
```
|
||||
|
||||
### Disable Checkpointing
|
||||
|
||||
**Not recommended**, but possible:
|
||||
```json
|
||||
{
|
||||
"enableCheckpointing": false
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Review Before Rewinding
|
||||
|
||||
**Look at:**
|
||||
- What checkpoint contains
|
||||
- What will be lost
|
||||
- What will be kept
|
||||
|
||||
**Avoid:**
|
||||
- Blindly selecting checkpoints
|
||||
- Rewinding without understanding impact
|
||||
|
||||
### 2. Use Descriptive Prompts
|
||||
|
||||
**Good (easy to identify):**
|
||||
```
|
||||
"add email validation to user registration"
|
||||
"refactor database queries for performance"
|
||||
```
|
||||
|
||||
**Bad (hard to identify):**
|
||||
```
|
||||
"make changes"
|
||||
"fix it"
|
||||
```
|
||||
|
||||
Checkpoints show your prompts, so descriptive prompts make checkpoint selection easier.
|
||||
|
||||
### 3. Combine with Git
|
||||
|
||||
```
|
||||
# Checkpoint for rapid iteration
|
||||
Try approach → rewind → try approach → rewind
|
||||
|
||||
# Git for confirmed changes
|
||||
git add .
|
||||
git commit -m "Final implementation"
|
||||
```
|
||||
|
||||
### 4. Rewind Code, Not Conversation
|
||||
|
||||
**Often better:**
|
||||
Rewind code only and keep conversation history.
|
||||
|
||||
**Why:**
|
||||
- Maintains context
|
||||
- Claude learns from mistakes
|
||||
- Can explain what went wrong
|
||||
- Better for iterative improvement
|
||||
|
||||
### 5. Regular Git Commits
|
||||
|
||||
Don't rely solely on checkpoints:
|
||||
```
|
||||
# After significant progress
|
||||
git add .
|
||||
git commit -m "Checkpoint: working user authentication"
|
||||
|
||||
# Continue with Claude Code
|
||||
# Checkpointing handles rapid iteration
|
||||
# Git handles permanent milestones
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Checkpoint Not Showing Expected State
|
||||
|
||||
**Possible causes:**
|
||||
- Changes made via bash commands (not tracked)
|
||||
- External file modifications
|
||||
- Concurrent session changes
|
||||
- Checkpoint expired (>30 days)
|
||||
|
||||
**Solution:**
|
||||
- Use git for those scenarios
|
||||
- Check git history: `git log`
|
||||
- Review git diff: `git diff`
|
||||
|
||||
### Can't Find Recent Checkpoint
|
||||
|
||||
**Check:**
|
||||
- Are you in the right directory?
|
||||
- Is this the same session?
|
||||
- Did checkpoint expire?
|
||||
|
||||
**Solution:**
|
||||
- Use `/rewind` command instead of Esc Esc
|
||||
- Check session history
|
||||
- Verify working directory
|
||||
|
||||
### Rewind Not Working
|
||||
|
||||
**Check:**
|
||||
- Are files write-protected?
|
||||
- Do you have filesystem permissions?
|
||||
- Are files open in another program?
|
||||
|
||||
**Solution:**
|
||||
- Close files in editors
|
||||
- Check file permissions
|
||||
- Ensure no file locks
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### Refactoring Safely
|
||||
|
||||
```
|
||||
# Current working state
|
||||
git commit -m "Pre-refactor checkpoint"
|
||||
|
||||
# Try refactoring
|
||||
"refactor user controller for better error handling"
|
||||
|
||||
# Test
|
||||
!npm test
|
||||
|
||||
# If tests fail
|
||||
Esc Esc → Code only → Return to pre-refactor
|
||||
|
||||
# Try different approach
|
||||
"refactor user controller with focus on backward compatibility"
|
||||
|
||||
# If tests pass
|
||||
git commit -m "Refactored user controller"
|
||||
```
|
||||
|
||||
### Feature Experimentation
|
||||
|
||||
```
|
||||
# Baseline working
|
||||
git commit -m "Baseline"
|
||||
|
||||
# Experiment 1
|
||||
"add feature using approach A"
|
||||
# Review, note pros/cons
|
||||
|
||||
# Rewind
|
||||
Esc Esc → Code only
|
||||
|
||||
# Experiment 2
|
||||
"add feature using approach B"
|
||||
# Compare, choose better
|
||||
|
||||
# If experiment 2 is better
|
||||
git commit -m "Added feature using approach B"
|
||||
|
||||
# If neither was good
|
||||
Esc Esc → Code only → Back to baseline
|
||||
```
|
||||
|
||||
### Conversation Management
|
||||
|
||||
```
|
||||
# Making good progress
|
||||
"implement auth"
|
||||
"add user roles"
|
||||
"add permissions"
|
||||
|
||||
# Conversation gets complex/confused
|
||||
Esc Esc → Conversation only → Select first checkpoint
|
||||
|
||||
# Start fresh conversation
|
||||
"explain the architecture we just built"
|
||||
# Code intact, conversation reset
|
||||
```
|
||||
151
skills/ci-cd/SKILL.md
Normal file
151
skills/ci-cd/SKILL.md
Normal file
@@ -0,0 +1,151 @@
|
||||
---
|
||||
name: ci-cd
|
||||
description: How to use Claude Code with GitHub Actions and GitLab CI/CD for automated workflows. Use when user asks about CI/CD integration, GitHub Actions, GitLab pipelines, or automated development workflows.
|
||||
---
|
||||
|
||||
# Claude Code CI/CD Integration
|
||||
|
||||
## Overview
|
||||
|
||||
Claude Code integrates with CI/CD platforms to enable AI-powered automation within development workflows. By mentioning `@claude` in pull requests, merge requests, or issues, you can leverage Claude to analyze code, create PRs/MRs, implement features, and fix bugs while adhering to project standards.
|
||||
|
||||
## GitHub Actions
|
||||
|
||||
### Key Capabilities
|
||||
|
||||
**Core Features:**
|
||||
- Instant PR creation with complete code changes from descriptions
|
||||
- Automated issue-to-code implementation
|
||||
- Adherence to project guidelines via `CLAUDE.md` files
|
||||
- Secure execution on GitHub runners
|
||||
|
||||
### Setup Methods
|
||||
|
||||
**Quick Installation:**
|
||||
Run `/install-github-app` in Claude Code for guided setup and secret configuration. This approach is limited to direct Claude API users.
|
||||
|
||||
**Manual Setup Requirements:**
|
||||
1. Install the Claude GitHub app with read/write permissions for Contents, Issues, and Pull Requests
|
||||
2. Add `ANTHROPIC_API_KEY` to repository secrets
|
||||
3. Copy the workflow file from official examples into `.github/workflows/`
|
||||
|
||||
### Configuration
|
||||
|
||||
**Example Workflow:**
|
||||
```yaml
|
||||
- uses: anthropics/claude-code-action@v1
|
||||
with:
|
||||
prompt: "Your instructions"
|
||||
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
claude_args: "--max-turns 5"
|
||||
```
|
||||
|
||||
**Version Migration (v1.0):**
|
||||
- Replace `mode` configuration (now auto-detected)
|
||||
- Change `direct_prompt` to `prompt`
|
||||
- Move CLI options into `claude_args` parameter
|
||||
|
||||
### Common Use Cases
|
||||
|
||||
**In comments:**
|
||||
```
|
||||
@claude implement this feature
|
||||
@claude fix the TypeError in the dashboard
|
||||
@claude how should I handle authentication?
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
**Project Guidelines:** Create a `CLAUDE.md` file defining coding standards and review criteria that Claude will follow.
|
||||
|
||||
**Security:** Always use GitHub Secrets rather than hardcoding credentials. Store API keys as `ANTHROPIC_API_KEY`.
|
||||
|
||||
**Cost Management:** Configure `--max-turns` limits and use specific commands to minimize unnecessary API calls.
|
||||
|
||||
### Enterprise Deployment
|
||||
|
||||
AWS Bedrock and Google Vertex AI integration requires:
|
||||
- OIDC configuration for authentication
|
||||
- Service account setup with appropriate permissions
|
||||
- Repository secrets for credentials
|
||||
|
||||
Both approaches eliminate need for static credentials through temporary token rotation.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
**No Response:** Verify GitHub app installation, workflow enablement, and use of `@claude` (not `/claude`).
|
||||
|
||||
**CI Not Running:** Confirm app usage instead of default Actions user and verify webhook trigger configuration.
|
||||
|
||||
**Authentication Issues:** Validate API key permissions and confirm secret naming in workflows.
|
||||
|
||||
## GitLab CI/CD
|
||||
|
||||
### Overview
|
||||
Claude Code integrates with GitLab CI/CD to enable AI-powered development workflows. The integration is currently in beta and maintained by GitLab.
|
||||
|
||||
### Key Capabilities
|
||||
- **Automated MR Creation**: Describe what you need, and Claude proposes a complete MR with changes and explanation
|
||||
- **Issue-to-Code**: Transform issue descriptions into working implementations
|
||||
- **Code Review & Iteration**: Respond to follow-up comments to refine proposed changes
|
||||
- **Bug Fixes**: Identify and resolve issues identified through tests or comments
|
||||
|
||||
### Quick Setup
|
||||
|
||||
**1. Add CI/CD Variable:**
|
||||
Store `ANTHROPIC_API_KEY` as a masked variable in **Settings → CI/CD → Variables**
|
||||
|
||||
**2. Configure .gitlab-ci.yml:**
|
||||
Add a Claude job stage that:
|
||||
- Uses Node.js Alpine image
|
||||
- Installs Claude Code CLI via npm
|
||||
- Executes Claude with appropriate prompts
|
||||
- Allows tools: Bash, Read, Edit, Write, and mcp__gitlab
|
||||
|
||||
**3. Trigger Methods:**
|
||||
- Manual pipeline runs
|
||||
- Merge request events
|
||||
- Web/API triggers when comments mention `@claude`
|
||||
|
||||
### Provider Options
|
||||
|
||||
**Claude API (SaaS):** Use `ANTHROPIC_API_KEY`
|
||||
|
||||
**AWS Bedrock:** Configure OIDC authentication with:
|
||||
- `AWS_ROLE_TO_ASSUME` variable
|
||||
- `AWS_REGION` variable
|
||||
- IAM role with Bedrock permissions
|
||||
|
||||
**Google Vertex AI:** Set up Workload Identity Federation with:
|
||||
- `GCP_WORKLOAD_IDENTITY_PROVIDER`
|
||||
- `GCP_SERVICE_ACCOUNT`
|
||||
- `CLOUD_ML_REGION`
|
||||
|
||||
### Best Practices
|
||||
|
||||
- **CLAUDE.md**: Define project conventions and coding standards for Claude to follow
|
||||
- **Security**: Never commit credentials; use masked CI/CD variables and OIDC where possible
|
||||
- **Performance**: Keep guidelines concise; provide clear issue descriptions to minimize iterations
|
||||
- **Governance**: All changes flow through MRs for review; branch protection rules apply
|
||||
|
||||
### Cost Considerations
|
||||
- GitLab runner compute minutes consumed by Claude jobs
|
||||
- Anthropic API token usage (varies by task complexity and codebase size)
|
||||
- Optimize by using specific commands and setting appropriate timeouts
|
||||
|
||||
### Use Case Examples
|
||||
|
||||
**Convert Issues to MRs:** Comment `@claude implement this feature based on the issue description`
|
||||
|
||||
**Get Implementation Help:** In MR discussions: `@claude suggest a concrete approach to [task]`
|
||||
|
||||
**Fix Bugs:** `@claude fix the [error type] in [component]`
|
||||
|
||||
## General CI/CD Best Practices
|
||||
|
||||
1. **Define clear guidelines** in `CLAUDE.md` for consistent behavior
|
||||
2. **Use secrets management** for all credentials
|
||||
3. **Set cost controls** with turn limits and specific prompts
|
||||
4. **Review all changes** - Claude creates PRs/MRs for human approval
|
||||
5. **Monitor usage** to track API consumption and optimize workflows
|
||||
6. **Test in non-production** environments first
|
||||
368
skills/cli-reference/SKILL.md
Normal file
368
skills/cli-reference/SKILL.md
Normal file
@@ -0,0 +1,368 @@
|
||||
---
|
||||
name: cli-reference
|
||||
description: Complete CLI command reference for Claude Code including flags, options, and usage patterns. Use when user asks about command-line options, flags, CLI usage, or command syntax.
|
||||
---
|
||||
|
||||
# Claude Code CLI Reference
|
||||
|
||||
## CLI Commands
|
||||
|
||||
### Interactive Mode
|
||||
|
||||
**Start interactive REPL:**
|
||||
```bash
|
||||
claude
|
||||
```
|
||||
|
||||
**Start with initial prompt:**
|
||||
```bash
|
||||
claude "query"
|
||||
```
|
||||
|
||||
### Non-Interactive Mode
|
||||
|
||||
**Query via SDK, then exit:**
|
||||
```bash
|
||||
claude -p "query"
|
||||
claude --print "query"
|
||||
```
|
||||
|
||||
**Process piped content:**
|
||||
```bash
|
||||
cat file | claude -p "query"
|
||||
echo "content" | claude -p "analyze this"
|
||||
```
|
||||
|
||||
**Continue most recent conversation:**
|
||||
```bash
|
||||
claude -c
|
||||
claude --continue
|
||||
```
|
||||
|
||||
**Continue via SDK:**
|
||||
```bash
|
||||
claude -c -p "query"
|
||||
```
|
||||
|
||||
**Resume session by ID:**
|
||||
```bash
|
||||
claude -r "<session-id>" "query"
|
||||
claude --resume "<session-id>" "query"
|
||||
```
|
||||
|
||||
### Maintenance
|
||||
|
||||
**Update to latest version:**
|
||||
```bash
|
||||
claude update
|
||||
```
|
||||
|
||||
**Configure MCP servers:**
|
||||
```bash
|
||||
claude mcp
|
||||
```
|
||||
|
||||
**Check installation health:**
|
||||
```bash
|
||||
claude --doctor
|
||||
```
|
||||
|
||||
**Migrate installer:**
|
||||
```bash
|
||||
claude migrate-installer
|
||||
```
|
||||
|
||||
## Key CLI Flags
|
||||
|
||||
### Essential Flags
|
||||
|
||||
| Flag | Short | Purpose | Example |
|
||||
|------|-------|---------|---------|
|
||||
| `--print` | `-p` | Print response without interactive mode | `claude -p "task"` |
|
||||
| `--continue` | `-c` | Continue most recent conversation | `claude -c "follow up"` |
|
||||
| `--resume` | `-r` | Resume session by ID | `claude -r abc123 "task"` |
|
||||
| `--help` | `-h` | Show help information | `claude --help` |
|
||||
| `--version` | `-v` | Show version | `claude --version` |
|
||||
|
||||
### Configuration Flags
|
||||
|
||||
| Flag | Purpose | Example |
|
||||
|------|---------|---------|
|
||||
| `--add-dir` | Add working directories for access | `claude --add-dir /path/to/dir` |
|
||||
| `--agents` | Define custom subagents dynamically via JSON | `claude --agents '[{...}]'` |
|
||||
| `--model` | Set model with alias or full name | `claude --model opus` |
|
||||
| `--max-turns` | Limit agentic turns in non-interactive mode | `claude --max-turns 5` |
|
||||
| `--permission-mode` | Begin in specified permission mode | `claude --permission-mode acceptAll` |
|
||||
| `--allowedTools` | Specify permitted tools | `claude --allowedTools "Bash,Read"` |
|
||||
|
||||
### Output & Format Flags
|
||||
|
||||
| Flag | Purpose | Example |
|
||||
|------|---------|---------|
|
||||
| `--output-format` | Specify format (text, json, stream-json) | `claude -p --output-format json` |
|
||||
| `--input-format` | Specify input format | `claude --input-format stream-json` |
|
||||
| `--verbose` | Enable detailed logging for debugging | `claude --verbose` |
|
||||
| `--debug` | Enable debug mode | `claude --debug` |
|
||||
|
||||
### Advanced Flags
|
||||
|
||||
| Flag | Purpose | Example |
|
||||
|------|---------|---------|
|
||||
| `--mcp-config` | Load MCP servers from JSON file | `claude --mcp-config servers.json` |
|
||||
| `--append-system-prompt` | Append text to system prompt | `claude --append-system-prompt "Be concise"` |
|
||||
| `--compact` | Start with compacted context | `claude --compact` |
|
||||
| `--no-cache` | Disable prompt caching | `claude --no-cache` |
|
||||
|
||||
## Agents Flag Format
|
||||
|
||||
Custom subagents require JSON with:
|
||||
- `description`: Purpose of the subagent
|
||||
- `prompt`: System prompt for the subagent
|
||||
- `tools` (optional): Array of allowed tools
|
||||
- `model` (optional): Model to use
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
claude --agents '[{
|
||||
"description": "Code reviewer",
|
||||
"prompt": "Review code for quality and security",
|
||||
"tools": ["Read", "Grep", "Glob"],
|
||||
"model": "sonnet"
|
||||
}]'
|
||||
```
|
||||
|
||||
## Permission Modes
|
||||
|
||||
| Mode | Description |
|
||||
|------|-------------|
|
||||
| `ask` | Ask for permission for each operation (default) |
|
||||
| `acceptAll` | Accept all operations automatically |
|
||||
| `acceptEdits` | Auto-accept file edits, ask for bash |
|
||||
| `acceptCommands` | Auto-accept bash, ask for edits |
|
||||
| `denyAll` | Deny all operations |
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
claude --permission-mode acceptEdits -p "refactor the code"
|
||||
```
|
||||
|
||||
## Model Aliases
|
||||
|
||||
| Alias | Full Model Name |
|
||||
|-------|----------------|
|
||||
| `sonnet` | claude-sonnet-4-5-20250929 |
|
||||
| `opus` | claude-opus-4-5-20250514 |
|
||||
| `haiku` | claude-haiku-4-5-20250815 |
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
claude --model opus "complex reasoning task"
|
||||
claude --model haiku -p "simple query"
|
||||
```
|
||||
|
||||
## Output Formats
|
||||
|
||||
### Text (Default)
|
||||
|
||||
Plain text output suitable for reading:
|
||||
```bash
|
||||
claude -p "explain this code"
|
||||
```
|
||||
|
||||
### JSON
|
||||
|
||||
Structured output with metadata:
|
||||
```bash
|
||||
claude -p --output-format json "analyze project"
|
||||
```
|
||||
|
||||
**JSON structure:**
|
||||
```json
|
||||
{
|
||||
"type": "result",
|
||||
"subtype": "success",
|
||||
"total_cost_usd": 0.003,
|
||||
"duration_ms": 1234,
|
||||
"num_turns": 6,
|
||||
"result": "Response text...",
|
||||
"session_id": "abc123"
|
||||
}
|
||||
```
|
||||
|
||||
### Stream JSON
|
||||
|
||||
JSONL format for real-time processing:
|
||||
```bash
|
||||
claude -p --output-format stream-json --input-format stream-json
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Key environment variables affecting CLI behavior:
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `ANTHROPIC_API_KEY` | API authentication |
|
||||
| `CLAUDE_CODE_USE_BEDROCK` | Use AWS Bedrock |
|
||||
| `CLAUDE_CODE_USE_VERTEX` | Use Google Vertex AI |
|
||||
| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enable telemetry |
|
||||
| `DISABLE_PROMPT_CACHING` | Disable caching |
|
||||
| `MAX_THINKING_TOKENS` | Enable extended thinking |
|
||||
| `BASH_MAX_OUTPUT_LENGTH` | Limit bash output |
|
||||
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Max output tokens |
|
||||
|
||||
## Common Usage Patterns
|
||||
|
||||
### Quick Query
|
||||
```bash
|
||||
claude -p "what does this project do?"
|
||||
```
|
||||
|
||||
### Automated Task
|
||||
```bash
|
||||
claude -p "run tests and fix failures" \
|
||||
--allowedTools "Bash,Read,Edit,Write" \
|
||||
--max-turns 10 \
|
||||
--permission-mode acceptAll
|
||||
```
|
||||
|
||||
### Resume Previous Work
|
||||
```bash
|
||||
claude -c "continue the refactoring"
|
||||
```
|
||||
|
||||
### Custom Configuration
|
||||
```bash
|
||||
claude \
|
||||
--model sonnet \
|
||||
--permission-mode acceptEdits \
|
||||
--verbose \
|
||||
--add-dir /path/to/project
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
```bash
|
||||
claude -p "review PR changes" \
|
||||
--output-format json \
|
||||
--allowedTools "Read,Bash" \
|
||||
--max-turns 5
|
||||
```
|
||||
|
||||
### MCP with Custom Servers
|
||||
```bash
|
||||
claude --mcp-config mcp-servers.json -p "fetch user data"
|
||||
```
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | Success |
|
||||
| 1 | General error |
|
||||
| 2 | Configuration error |
|
||||
| 130 | Interrupted (Ctrl+C) |
|
||||
|
||||
## Tips & Tricks
|
||||
|
||||
### Piping Input
|
||||
|
||||
```bash
|
||||
# Pipe file content
|
||||
cat script.py | claude -p "explain this code"
|
||||
|
||||
# Pipe command output
|
||||
git diff | claude -p "review these changes"
|
||||
|
||||
# Pipe from multiple sources
|
||||
cat file1.txt file2.txt | claude -p "summarize"
|
||||
```
|
||||
|
||||
### Chaining Commands
|
||||
|
||||
```bash
|
||||
# With AND operator
|
||||
claude -p "task 1" && claude -p "task 2"
|
||||
|
||||
# With OR operator
|
||||
claude -p "task" || echo "Failed"
|
||||
```
|
||||
|
||||
### Background Execution
|
||||
|
||||
```bash
|
||||
# Run in background
|
||||
claude -p "long task" &
|
||||
|
||||
# With output redirection
|
||||
claude -p "task" > output.txt 2>&1 &
|
||||
```
|
||||
|
||||
### Parsing JSON Output
|
||||
|
||||
```bash
|
||||
# Extract specific field with jq
|
||||
claude -p "task" --output-format json | jq -r '.result'
|
||||
|
||||
# Get session ID
|
||||
SESSION=$(claude -p "task" --output-format json | jq -r '.session_id')
|
||||
|
||||
# Check cost
|
||||
claude -p "task" --output-format json | jq '.total_cost_usd'
|
||||
```
|
||||
|
||||
### Using with Scripts
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# Check if task succeeded
|
||||
RESULT=$(claude -p "run tests" --output-format json)
|
||||
STATUS=$(echo "$RESULT" | jq -r '.subtype')
|
||||
|
||||
if [ "$STATUS" = "success" ]; then
|
||||
echo "Tests passed"
|
||||
else
|
||||
echo "Tests failed"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Debugging
|
||||
|
||||
### Enable Verbose Output
|
||||
|
||||
```bash
|
||||
claude --verbose -p "task"
|
||||
```
|
||||
|
||||
### Enable Debug Mode
|
||||
|
||||
```bash
|
||||
claude --debug
|
||||
```
|
||||
|
||||
### Check Version
|
||||
|
||||
```bash
|
||||
claude --version
|
||||
```
|
||||
|
||||
### View Help
|
||||
|
||||
```bash
|
||||
claude --help
|
||||
claude -h
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use specific flags** for automation and scripts
|
||||
2. **Enable JSON output** for programmatic parsing
|
||||
3. **Set max-turns** to prevent runaway operations
|
||||
4. **Configure permissions** appropriately for security
|
||||
5. **Use model aliases** for readability
|
||||
6. **Pipe stderr to logs** for error tracking
|
||||
7. **Check exit codes** in scripts
|
||||
8. **Use --allowedTools** to restrict capabilities
|
||||
9. **Set timeouts** for long-running tasks
|
||||
10. **Test with --verbose** before production use
|
||||
271
skills/configuration/SKILL.md
Normal file
271
skills/configuration/SKILL.md
Normal file
@@ -0,0 +1,271 @@
|
||||
---
|
||||
name: configuration
|
||||
description: How to configure Claude Code settings, permissions, environment variables, and project-level configurations. Use when user asks about settings.json, configuration, permissions, or Claude Code setup.
|
||||
---
|
||||
|
||||
# Claude Code Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
Claude Code provides hierarchical configuration through `settings.json` files at multiple levels. You can manage settings globally, per-project, or through enterprise policies.
|
||||
|
||||
## Configuration File Locations
|
||||
|
||||
**User-level settings**: `~/.claude/settings.json` (applies to all projects)
|
||||
|
||||
**Project-level settings**:
|
||||
- `.claude/settings.json` (shared with team via source control)
|
||||
- `.claude/settings.local.json` (personal, not committed)
|
||||
|
||||
**Enterprise managed policies**:
|
||||
- macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`
|
||||
- Linux/WSL: `/etc/claude-code/managed-settings.json`
|
||||
- Windows: `C:\ProgramData\ClaudeCode\managed-settings.json`
|
||||
|
||||
## Key Configuration Options
|
||||
|
||||
| Setting | Purpose | Example |
|
||||
|---------|---------|---------|
|
||||
| `permissions` | Control tool access and file restrictions | `{"allow": ["Bash(npm run test:*)"], "deny": ["Read(.env)"]}` |
|
||||
| `env` | Environment variables for sessions | `{"FOO": "bar"}` |
|
||||
| `model` | Override default model | `"claude-sonnet-4-5-20250929"` |
|
||||
| `outputStyle` | Adjust system prompt behavior | `"Explanatory"` |
|
||||
| `hooks` | Custom commands before/after tool use | `{"PreToolUse": {"Bash": "echo 'Running..'"}}` |
|
||||
|
||||
## Permission Configuration
|
||||
|
||||
Restrict file and command access through the `permissions` object:
|
||||
|
||||
**Deny patterns** block sensitive files:
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"deny": [
|
||||
"Read(.env)",
|
||||
"Read(./secrets/**)",
|
||||
"Bash(curl:*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Allow patterns** explicitly permit actions:
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(npm run lint)",
|
||||
"Bash(npm run test:*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Ask patterns** require confirmation:
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"ask": [
|
||||
"Bash(git push:*)",
|
||||
"Write(src/**)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Sandbox Settings
|
||||
|
||||
Enable process isolation (macOS/Linux):
|
||||
|
||||
```json
|
||||
{
|
||||
"sandbox": {
|
||||
"enabled": true,
|
||||
"excludedCommands": ["docker"],
|
||||
"network": {
|
||||
"allowUnixSockets": ["~/.ssh/agent-socket"],
|
||||
"allowLocalBinding": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Settings Precedence (High to Low)
|
||||
|
||||
1. Enterprise managed policies
|
||||
2. Command-line arguments
|
||||
3. Local project settings (`.claude/settings.local.json`)
|
||||
4. Shared project settings (`.claude/settings.json`)
|
||||
5. User settings (`~/.claude/settings.json`)
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Key variables for controlling Claude Code behavior:
|
||||
|
||||
- `ANTHROPIC_API_KEY` - API authentication
|
||||
- `BASH_MAX_OUTPUT_LENGTH` - Limit bash output size
|
||||
- `DISABLE_TELEMETRY` - Opt out of analytics
|
||||
- `MAX_THINKING_TOKENS` - Enable extended thinking
|
||||
- `CLAUDE_CODE_USE_BEDROCK` - Use AWS Bedrock
|
||||
- `DISABLE_PROMPT_CACHING` - Turn off caching globally
|
||||
|
||||
## Available Tools
|
||||
|
||||
Claude Code can access these tools (subject to permissions):
|
||||
- Bash
|
||||
- Edit, Read, Write
|
||||
- WebFetch, WebSearch
|
||||
- Glob, Grep
|
||||
- NotebookEdit
|
||||
- Task
|
||||
|
||||
## Plugin Management
|
||||
|
||||
Configure plugins via `enabledPlugins`:
|
||||
|
||||
```json
|
||||
{
|
||||
"enabledPlugins": {
|
||||
"formatter@company-tools": true,
|
||||
"deployer@company-tools": false
|
||||
},
|
||||
"extraKnownMarketplaces": {
|
||||
"company-tools": {
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "company/claude-plugins"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Access plugin management interactively with `/plugin` command.
|
||||
|
||||
## Excluding Sensitive Files
|
||||
|
||||
Prevent Claude from accessing confidential data:
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"deny": [
|
||||
"Read(.env)",
|
||||
"Read(.env.*)",
|
||||
"Read(./secrets/**)",
|
||||
"Read(**/credentials.json)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Files matching deny patterns become completely invisible to Claude Code.
|
||||
|
||||
## Common Configuration Examples
|
||||
|
||||
### Development Team Setup
|
||||
|
||||
**.claude/settings.json** (committed to repo):
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(npm run *)",
|
||||
"Bash(git status:*)",
|
||||
"Bash(git diff:*)"
|
||||
],
|
||||
"deny": [
|
||||
"Read(.env*)",
|
||||
"Bash(git push:*)"
|
||||
],
|
||||
"ask": [
|
||||
"Write(src/**)"
|
||||
]
|
||||
},
|
||||
"env": {
|
||||
"NODE_ENV": "development"
|
||||
},
|
||||
"extraKnownMarketplaces": {
|
||||
"team-tools": {
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "your-org/claude-plugins"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Personal Overrides
|
||||
|
||||
**.claude/settings.local.json** (not committed):
|
||||
```json
|
||||
{
|
||||
"model": "claude-opus-4-5-20250514",
|
||||
"env": {
|
||||
"CUSTOM_VAR": "my-value"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Enterprise Security Policy
|
||||
|
||||
**/etc/claude-code/managed-settings.json**:
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"deny": [
|
||||
"Read(/etc/passwd)",
|
||||
"Read(~/.ssh/**)",
|
||||
"Bash(rm:*)",
|
||||
"Bash(sudo:*)"
|
||||
]
|
||||
},
|
||||
"sandbox": {
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Managing Settings
|
||||
|
||||
**View current settings**: Check the files in `.claude/` directory
|
||||
|
||||
**Edit project settings**: Create or modify `.claude/settings.json`
|
||||
|
||||
**Edit user settings**: Modify `~/.claude/settings.json`
|
||||
|
||||
**Interactive configuration**: Some settings can be managed via slash commands like `/permissions`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use project settings** for team-shared configuration
|
||||
2. **Use local settings** for personal preferences
|
||||
3. **Commit shared settings** to source control
|
||||
4. **Document settings** with comments (use `//` in JSON5-compatible editors)
|
||||
5. **Review permissions** regularly for security
|
||||
6. **Test settings** before enforcing team-wide
|
||||
7. **Use deny patterns** for sensitive files
|
||||
8. **Enable sandbox** for additional security
|
||||
9. **Set environment variables** for consistent environments
|
||||
10. **Configure marketplaces** for team plugin distribution
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Settings not applying:**
|
||||
- Check file locations and names
|
||||
- Verify JSON syntax
|
||||
- Review precedence order
|
||||
- Check for conflicting settings at different levels
|
||||
|
||||
**Permission errors:**
|
||||
- Review deny/allow patterns
|
||||
- Check pattern syntax (glob patterns supported)
|
||||
- Verify file paths are correct
|
||||
- Test patterns incrementally
|
||||
|
||||
**Plugin issues:**
|
||||
- Verify marketplace configuration
|
||||
- Check plugin names and versions
|
||||
- Ensure plugins are enabled in `enabledPlugins`
|
||||
- Review plugin-specific settings
|
||||
244
skills/deployment/SKILL.md
Normal file
244
skills/deployment/SKILL.md
Normal file
@@ -0,0 +1,244 @@
|
||||
---
|
||||
name: deployment
|
||||
description: How to deploy Claude Code with Amazon Bedrock, Google Vertex AI, and other cloud providers. Use when user asks about AWS Bedrock, GCP Vertex AI, cloud deployment, or enterprise deployment.
|
||||
---
|
||||
|
||||
# Claude Code Deployment
|
||||
|
||||
## Overview
|
||||
|
||||
Claude Code supports deployment through multiple providers beyond the direct Claude API, including Amazon Bedrock and Google Vertex AI for enterprise cloud deployment.
|
||||
|
||||
## Amazon Bedrock Integration
|
||||
|
||||
### Overview
|
||||
Claude Code integrates with Amazon Bedrock to enable deployment through AWS infrastructure using Claude models available in your AWS account.
|
||||
|
||||
### Prerequisites
|
||||
- Active AWS account with Bedrock access enabled
|
||||
- Access to desired Claude models (e.g., Claude Sonnet 4.5)
|
||||
- AWS CLI installed (optional)
|
||||
- Appropriate IAM permissions
|
||||
|
||||
### Setup Process
|
||||
|
||||
#### 1. Model Access
|
||||
Navigate to the Amazon Bedrock console, access Model access settings, and request Claude model availability in your region.
|
||||
|
||||
#### 2. AWS Credentials Configuration
|
||||
Multiple authentication methods are supported:
|
||||
|
||||
**AWS CLI:**
|
||||
```bash
|
||||
aws configure
|
||||
```
|
||||
|
||||
**Environment variables:**
|
||||
```bash
|
||||
export AWS_ACCESS_KEY_ID=your-key
|
||||
export AWS_SECRET_ACCESS_KEY=your-secret
|
||||
export AWS_SESSION_TOKEN=your-token # Optional
|
||||
```
|
||||
|
||||
**SSO profile:**
|
||||
```bash
|
||||
aws sso login --profile=<name>
|
||||
export AWS_PROFILE=your-profile
|
||||
```
|
||||
|
||||
**Bedrock API keys:**
|
||||
```bash
|
||||
export AWS_BEARER_TOKEN_BEDROCK=your-token
|
||||
```
|
||||
|
||||
#### 3. Claude Code Configuration
|
||||
Enable Bedrock integration:
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_BEDROCK=1
|
||||
export AWS_REGION=us-east-1 # Or preferred region
|
||||
```
|
||||
|
||||
Optional override for Haiku region:
|
||||
```bash
|
||||
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2
|
||||
```
|
||||
|
||||
#### 4. Model Selection
|
||||
Default models include Claude Sonnet 4.5 and Claude Haiku 4.5.
|
||||
|
||||
Customize via:
|
||||
```bash
|
||||
export ANTHROPIC_MODEL='model-id'
|
||||
export ANTHROPIC_SMALL_FAST_MODEL='haiku-model-id'
|
||||
```
|
||||
|
||||
#### 5. Token Configuration
|
||||
Recommended settings:
|
||||
```bash
|
||||
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096
|
||||
export MAX_THINKING_TOKENS=1024
|
||||
```
|
||||
|
||||
### IAM Permissions
|
||||
|
||||
Required actions:
|
||||
- `bedrock:InvokeModel`
|
||||
- `bedrock:InvokeModelWithResponseStream`
|
||||
- `bedrock:ListInferenceProfiles`
|
||||
|
||||
Example IAM policy:
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"bedrock:InvokeModel",
|
||||
"bedrock:InvokeModelWithResponseStream",
|
||||
"bedrock:ListInferenceProfiles"
|
||||
],
|
||||
"Resource": "*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Advanced Features
|
||||
|
||||
Automatic credential refresh supports corporate identity providers through `awsAuthRefresh` and `awsCredentialExport` configuration options.
|
||||
|
||||
### Key Limitations
|
||||
- Login/logout commands disabled (AWS credentials handle authentication)
|
||||
- Uses Bedrock's Invoke API, not Converse API
|
||||
|
||||
## Google Vertex AI Integration
|
||||
|
||||
### Overview
|
||||
Claude Code integrates with Google Vertex AI to enable deployment through Google Cloud Platform. The service supports both global and regional endpoints for model access.
|
||||
|
||||
### Prerequisites
|
||||
- Active GCP account with billing enabled
|
||||
- A project with Vertex AI API access
|
||||
- Google Cloud SDK (`gcloud`) installed
|
||||
- Appropriate quota allocation in your chosen region
|
||||
|
||||
### Setup Process
|
||||
|
||||
#### 1. Enable Vertex AI API
|
||||
Enable the Vertex AI API in your GCP project:
|
||||
```bash
|
||||
gcloud config set project YOUR-PROJECT-ID
|
||||
gcloud services enable aiplatform.googleapis.com
|
||||
```
|
||||
|
||||
#### 2. Request Model Access
|
||||
Navigate to Vertex AI Model Garden to search for and request access to Claude models like Claude Sonnet 4.5.
|
||||
|
||||
**Approval time:** Typically 24-48 hours
|
||||
|
||||
#### 3. Configure GCP Credentials
|
||||
Claude Code uses standard Google Cloud authentication and automatically detects the project ID from environment variables.
|
||||
|
||||
```bash
|
||||
gcloud auth application-default login
|
||||
```
|
||||
|
||||
#### 4. Configure Claude Code
|
||||
Set environment variables:
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_VERTEX=1
|
||||
export CLOUD_ML_REGION=global # Or specify regional endpoints
|
||||
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
|
||||
```
|
||||
|
||||
#### 5. Model Configuration
|
||||
Default models include Claude Sonnet 4.5 as the primary model and Claude Haiku 4.5 as the fast model.
|
||||
|
||||
Customize through environment variables:
|
||||
```bash
|
||||
export ANTHROPIC_MODEL='model-id'
|
||||
export ANTHROPIC_SMALL_FAST_MODEL='haiku-model-id'
|
||||
```
|
||||
|
||||
### Key Features
|
||||
|
||||
**Prompt Caching:**
|
||||
Automatically supported via `cache_control` flags
|
||||
|
||||
**1M Token Context:**
|
||||
Available in beta for Sonnet 4 and 4.5
|
||||
|
||||
**IAM Requirements:**
|
||||
Assign `roles/aiplatform.user` role for necessary permissions:
|
||||
```bash
|
||||
gcloud projects add-iam-policy-binding YOUR-PROJECT-ID \
|
||||
--member="user:email@example.com" \
|
||||
--role="roles/aiplatform.user"
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
**Quota limitations:**
|
||||
- Check quota in GCP Console
|
||||
- Request increases if needed
|
||||
|
||||
**Unsupported models in specific regions:**
|
||||
- Verify model availability in Model Garden
|
||||
- Switch to supported regional endpoints
|
||||
|
||||
**429 rate-limit errors:**
|
||||
- Implement retry logic
|
||||
- Request quota increases
|
||||
- Spread requests across regions
|
||||
|
||||
## Comparison: Bedrock vs Vertex AI vs Claude API
|
||||
|
||||
| Feature | Claude API | AWS Bedrock | Google Vertex AI |
|
||||
|---------|-----------|-------------|------------------|
|
||||
| **Setup Complexity** | Simple | Moderate | Moderate |
|
||||
| **Authentication** | API key | AWS credentials | GCP credentials |
|
||||
| **Regional Options** | Global | AWS regions | GCP regions |
|
||||
| **Billing** | Direct | AWS billing | GCP billing |
|
||||
| **Enterprise Features** | Basic | Advanced | Advanced |
|
||||
| **Compliance** | Standard | AWS compliance | GCP compliance |
|
||||
|
||||
## Best Practices for Enterprise Deployment
|
||||
|
||||
1. **Use OIDC/Workload Identity** for credential management
|
||||
2. **Implement quota monitoring** to avoid service interruptions
|
||||
3. **Set up proper IAM roles** with least privilege access
|
||||
4. **Configure region preferences** based on data residency requirements
|
||||
5. **Enable logging and monitoring** for audit trails
|
||||
6. **Use environment-specific configurations** for dev/staging/prod
|
||||
7. **Implement cost controls** with budget alerts
|
||||
8. **Test failover scenarios** between regions
|
||||
9. **Document credential rotation procedures**
|
||||
10. **Review security policies** regularly
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
Both Bedrock and Vertex AI support automated workflows:
|
||||
|
||||
**GitHub Actions with Bedrock:**
|
||||
```yaml
|
||||
- name: Configure AWS Credentials
|
||||
uses: aws-actions/configure-aws-credentials@v1
|
||||
with:
|
||||
role-to-assume: arn:aws:iam::ACCOUNT:role/ROLE
|
||||
aws-region: us-east-1
|
||||
|
||||
- name: Run Claude Code
|
||||
run: |
|
||||
export CLAUDE_CODE_USE_BEDROCK=1
|
||||
claude -p "task" --output-format json
|
||||
```
|
||||
|
||||
**GitLab CI with Vertex AI:**
|
||||
```yaml
|
||||
script:
|
||||
- gcloud auth activate-service-account --key-file=$GCP_KEY_FILE
|
||||
- export CLAUDE_CODE_USE_VERTEX=1
|
||||
- export ANTHROPIC_VERTEX_PROJECT_ID=$PROJECT_ID
|
||||
- claude -p "task"
|
||||
```
|
||||
411
skills/getting-started/SKILL.md
Normal file
411
skills/getting-started/SKILL.md
Normal file
@@ -0,0 +1,411 @@
|
||||
---
|
||||
name: getting-started
|
||||
description: Quickstart guide for installing and using Claude Code for the first time. Use when user asks about installation, setup, getting started, or basic usage.
|
||||
---
|
||||
|
||||
# Claude Code Quickstart
|
||||
|
||||
## Installation
|
||||
|
||||
### NPM Installation
|
||||
|
||||
**Requirements:** Node.js 18+
|
||||
|
||||
```bash
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
### Native Installer (Beta)
|
||||
|
||||
**Homebrew (macOS):**
|
||||
```bash
|
||||
brew install --cask claude-code
|
||||
```
|
||||
|
||||
**macOS/Linux/WSL:**
|
||||
```bash
|
||||
curl -fsSL https://claude.ai/install.sh | bash
|
||||
```
|
||||
|
||||
**Windows PowerShell:**
|
||||
```powershell
|
||||
irm https://claude.ai/install.ps1 | iex
|
||||
```
|
||||
|
||||
### Verify Installation
|
||||
|
||||
```bash
|
||||
claude --version
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
### First Login
|
||||
|
||||
Start an interactive session and authenticate:
|
||||
```bash
|
||||
claude
|
||||
/login
|
||||
```
|
||||
|
||||
### Authentication Options
|
||||
|
||||
**Claude.ai (Recommended):**
|
||||
- Subscription-based
|
||||
- Easiest setup
|
||||
- Best for individual developers
|
||||
|
||||
**Claude Console:**
|
||||
- API access with prepaid credits
|
||||
- Good for teams and enterprises
|
||||
- Requires API key setup
|
||||
|
||||
**Note:** Credentials are stored securely and you won't need to log in again unless you explicitly log out.
|
||||
|
||||
## Basic Workflow
|
||||
|
||||
### 1. Start a Session
|
||||
|
||||
Navigate to your project directory:
|
||||
```bash
|
||||
cd /path/to/your/project
|
||||
claude
|
||||
```
|
||||
|
||||
### 2. Explore Your Codebase
|
||||
|
||||
Ask natural language questions:
|
||||
```
|
||||
"what does this project do?"
|
||||
"where is the main entry point?"
|
||||
"how does authentication work?"
|
||||
"show me the API endpoints"
|
||||
```
|
||||
|
||||
### 3. Make Code Changes
|
||||
|
||||
Request modifications:
|
||||
```
|
||||
"add a new function to validate email addresses"
|
||||
"refactor the user controller for better error handling"
|
||||
"add unit tests for the authentication module"
|
||||
```
|
||||
|
||||
**Approval process:**
|
||||
- Claude requests approval before modifying files
|
||||
- Review changes in the diff viewer
|
||||
- Approve individually or enable "Accept all" mode
|
||||
|
||||
### 4. Git Operations
|
||||
|
||||
Use conversational prompts:
|
||||
```
|
||||
"what files have I changed?"
|
||||
"commit my changes with a descriptive message"
|
||||
"create a pull request for this feature"
|
||||
```
|
||||
|
||||
## Essential Commands
|
||||
|
||||
### Interactive Mode
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `claude` | Start interactive mode |
|
||||
| `claude "task"` | Run single task then exit |
|
||||
| `/help` | Show available commands |
|
||||
| `/clear` | Clear conversation history |
|
||||
| `/memory` | Edit CLAUDE.md memory files |
|
||||
| `/permissions` | Configure tool permissions |
|
||||
| `/model` | Select AI model |
|
||||
|
||||
### Keyboard Shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Ctrl+C` | Cancel current operation |
|
||||
| `Ctrl+D` | Exit Claude Code |
|
||||
| `Ctrl+L` | Clear screen (keeps history) |
|
||||
| `Esc Esc` | Rewind code/conversation |
|
||||
| `↑`/`↓` | Navigate command history |
|
||||
| `Tab` | Toggle extended thinking |
|
||||
| `?` | Show help |
|
||||
|
||||
## Common First Tasks
|
||||
|
||||
### Understand a Project
|
||||
|
||||
```
|
||||
"Explain the project structure"
|
||||
"What technologies are used here?"
|
||||
"Where should I start if I want to add a new feature?"
|
||||
```
|
||||
|
||||
### Fix Issues
|
||||
|
||||
```
|
||||
"Find and fix any TypeScript errors"
|
||||
"Resolve linting issues"
|
||||
"Fix the failing tests"
|
||||
```
|
||||
|
||||
### Add Features
|
||||
|
||||
```
|
||||
"Add input validation to the signup form"
|
||||
"Create a new API endpoint for user profile updates"
|
||||
"Implement pagination for the product list"
|
||||
```
|
||||
|
||||
### Improve Code
|
||||
|
||||
```
|
||||
"Refactor this component for better readability"
|
||||
"Add error handling to all API calls"
|
||||
"Improve test coverage"
|
||||
```
|
||||
|
||||
## Pro Tips
|
||||
|
||||
### Be Specific
|
||||
|
||||
**❌ Vague:**
|
||||
```
|
||||
"make this better"
|
||||
"fix the code"
|
||||
```
|
||||
|
||||
**✅ Specific:**
|
||||
```
|
||||
"refactor this function to reduce complexity"
|
||||
"fix the null pointer exception in getUserProfile"
|
||||
"add JSDoc comments to all exported functions"
|
||||
```
|
||||
|
||||
### Break Down Complex Tasks
|
||||
|
||||
Instead of:
|
||||
```
|
||||
"Build a complete user management system"
|
||||
```
|
||||
|
||||
Try:
|
||||
```
|
||||
1. "Create a user model with validation"
|
||||
2. "Add CRUD endpoints for users"
|
||||
3. "Implement authentication middleware"
|
||||
4. "Add unit tests for user operations"
|
||||
```
|
||||
|
||||
### Use Context Efficiently
|
||||
|
||||
**Attach relevant files:**
|
||||
```
|
||||
"Review @src/utils/validation.ts for security issues"
|
||||
```
|
||||
|
||||
**Reference specific code:**
|
||||
```
|
||||
"Optimize the database query in getUsersByRole function"
|
||||
```
|
||||
|
||||
### Manage Permissions
|
||||
|
||||
Start cautious, then adjust:
|
||||
1. Begin with manual approval mode
|
||||
2. Review Claude's changes carefully
|
||||
3. Enable auto-accept for trusted operations
|
||||
4. Configure specific permissions via `/permissions`
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Learn More Features
|
||||
|
||||
1. **Custom Commands:** Create slash commands for frequent tasks
|
||||
2. **Memory Files:** Set up CLAUDE.md for project guidelines
|
||||
3. **Subagents:** Configure specialized agents for specific tasks
|
||||
4. **Hooks:** Automate workflows with event-driven scripts
|
||||
5. **Plugins:** Install marketplace plugins for extended functionality
|
||||
|
||||
### Configure Your Workflow
|
||||
|
||||
**Create `.claude/CLAUDE.md`:**
|
||||
```markdown
|
||||
# Project Guidelines
|
||||
|
||||
## Code Style
|
||||
- Use TypeScript strict mode
|
||||
- Prefer functional components
|
||||
- Follow existing naming conventions
|
||||
|
||||
## Testing
|
||||
- Write tests for all new features
|
||||
- Maintain >80% coverage
|
||||
|
||||
## Git
|
||||
- Use conventional commits
|
||||
- Squash before merging
|
||||
```
|
||||
|
||||
**Set up permissions in `.claude/settings.json`:**
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(npm run *)",
|
||||
"Bash(git status:*)"
|
||||
],
|
||||
"deny": [
|
||||
"Read(.env*)",
|
||||
"Bash(rm:*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Explore Advanced Features
|
||||
|
||||
**Headless mode for automation:**
|
||||
```bash
|
||||
claude -p "run tests and fix failures" \
|
||||
--allowedTools "Bash,Read,Edit,Write" \
|
||||
--output-format json
|
||||
```
|
||||
|
||||
**Session management:**
|
||||
```bash
|
||||
# Continue previous session
|
||||
claude --continue "add more tests"
|
||||
|
||||
# Resume specific session
|
||||
claude --resume <session-id> "finish the refactoring"
|
||||
```
|
||||
|
||||
**Custom models:**
|
||||
```bash
|
||||
claude --model opus # For complex reasoning
|
||||
claude --model haiku # For quick tasks
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Daily Development
|
||||
|
||||
```bash
|
||||
# Start your day
|
||||
cd project
|
||||
claude
|
||||
|
||||
# Review changes
|
||||
"what did I change yesterday?"
|
||||
|
||||
# Continue work
|
||||
"finish implementing the user profile feature"
|
||||
|
||||
# Commit
|
||||
"commit my changes with a good message"
|
||||
```
|
||||
|
||||
### Code Review
|
||||
|
||||
```bash
|
||||
# Review PR
|
||||
git diff main | claude -p "review these changes for issues"
|
||||
|
||||
# Address feedback
|
||||
claude
|
||||
"fix the security issue in the authentication handler"
|
||||
```
|
||||
|
||||
### Bug Fixing
|
||||
|
||||
```bash
|
||||
# Start with error
|
||||
claude "fix: TypeError: Cannot read property 'name' of undefined in dashboard"
|
||||
|
||||
# Debug
|
||||
"show me where this error occurs"
|
||||
"explain why this is happening"
|
||||
"fix it and add tests to prevent regression"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Command Not Found
|
||||
|
||||
```bash
|
||||
# Verify installation
|
||||
npm list -g @anthropic-ai/claude-code
|
||||
|
||||
# Check PATH
|
||||
echo $PATH | grep npm
|
||||
|
||||
# Reinstall if needed
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
### Authentication Issues
|
||||
|
||||
```bash
|
||||
# Log out and back in
|
||||
claude
|
||||
/logout
|
||||
/login
|
||||
|
||||
# Or reset auth
|
||||
rm -rf ~/.config/claude-code/auth.json
|
||||
claude
|
||||
/login
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
|
||||
```bash
|
||||
# Clear conversation
|
||||
/clear
|
||||
|
||||
# Compact context
|
||||
/compact
|
||||
|
||||
# Use more specific queries
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
**Within Claude Code:**
|
||||
```
|
||||
/help # Show all commands
|
||||
/bug # Report an issue
|
||||
/doctor # Check installation
|
||||
```
|
||||
|
||||
**External Resources:**
|
||||
- Documentation: https://docs.claude.com/en/docs/claude-code
|
||||
- GitHub: https://github.com/anthropics/claude-code
|
||||
- Issues: https://github.com/anthropics/claude-code/issues
|
||||
|
||||
## Summary
|
||||
|
||||
**Installation:** ~30 seconds
|
||||
```bash
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
claude
|
||||
/login
|
||||
```
|
||||
|
||||
**First task:** Ask about your project
|
||||
```
|
||||
"what does this project do?"
|
||||
```
|
||||
|
||||
**Make changes:** Be specific
|
||||
```
|
||||
"add input validation to the signup form"
|
||||
```
|
||||
|
||||
**Commit:** Use natural language
|
||||
```
|
||||
"commit my changes"
|
||||
```
|
||||
|
||||
That's it! You're ready to use Claude Code for development.
|
||||
169
skills/git-workflow/SKILL.md
Normal file
169
skills/git-workflow/SKILL.md
Normal file
@@ -0,0 +1,169 @@
|
||||
---
|
||||
name: git-workflow
|
||||
description: How Claude Code handles git commits and pull requests, including git safety protocols and best practices. Use when user asks about creating commits, making PRs, git workflows, or git safety.
|
||||
---
|
||||
|
||||
# Git Workflow in Claude Code
|
||||
|
||||
## Overview
|
||||
|
||||
Claude Code provides intelligent git workflow automation with built-in safety protocols. It can create commits, generate pull requests, and manage git operations while following best practices and security guidelines.
|
||||
|
||||
## Git Safety Protocol
|
||||
|
||||
**NEVER:**
|
||||
- Update the git config
|
||||
- Run destructive/irreversible git commands (like push --force, hard reset, etc.) unless explicitly requested
|
||||
- Skip hooks (--no-verify, --no-gpg-sign, etc.) unless explicitly requested
|
||||
- Run force push to main/master (warn the user if they request it)
|
||||
- Commit changes unless the user explicitly asks
|
||||
|
||||
**Avoid git commit --amend** - ONLY use --amend when either:
|
||||
1. User explicitly requested amend OR
|
||||
2. Adding edits from pre-commit hook
|
||||
|
||||
**Before amending:**
|
||||
- ALWAYS check authorship: `git log -1 --format='%an %ae'`
|
||||
- NEVER amend other developers' commits
|
||||
|
||||
## Creating Commits
|
||||
|
||||
### When to Commit
|
||||
Only create commits when the user explicitly requests them. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.
|
||||
|
||||
### Commit Workflow
|
||||
|
||||
**Step 1 - Gather Information (in parallel):**
|
||||
Run these bash commands simultaneously:
|
||||
- `git status` - see all untracked files
|
||||
- `git diff` - see both staged and unstaged changes
|
||||
- `git log` - see recent commit messages to follow the repository's commit message style
|
||||
|
||||
**Step 2 - Analyze and Draft:**
|
||||
- Summarize the nature of changes (new feature, enhancement, bug fix, refactoring, test, docs, etc.)
|
||||
- Do not commit files that likely contain secrets (.env, credentials.json, etc.)
|
||||
- Warn the user if they specifically request to commit those files
|
||||
- Draft a concise (1-2 sentences) commit message that focuses on the "why" rather than the "what"
|
||||
- Ensure it accurately reflects the changes and their purpose
|
||||
|
||||
**Step 3 - Execute Commit (sequentially):**
|
||||
Add relevant untracked files to the staging area, then create the commit with a message ending with:
|
||||
|
||||
```
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
Then run `git status` after the commit completes to verify success.
|
||||
|
||||
**Step 4 - Handle Pre-commit Hooks:**
|
||||
If the commit fails due to pre-commit hook changes, retry ONCE. If it succeeds but files were modified by the hook, verify it's safe to amend:
|
||||
- Check authorship: `git log -1 --format='%an %ae'`
|
||||
- Check not pushed: `git status` shows "Your branch is ahead"
|
||||
- If both true: amend your commit
|
||||
- Otherwise: create NEW commit (never amend other developers' commits)
|
||||
|
||||
### Commit Message Format
|
||||
|
||||
Always pass the commit message via HEREDOC for good formatting:
|
||||
|
||||
```bash
|
||||
git commit -m "$(cat <<'EOF'
|
||||
Commit message here.
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
### Important Notes
|
||||
- NEVER run additional commands to read or explore code, besides git bash commands
|
||||
- NEVER use the TodoWrite or Task tools during git commits
|
||||
- DO NOT push to the remote repository unless the user explicitly asks
|
||||
- NEVER use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input
|
||||
- If there are no changes to commit, do not create an empty commit
|
||||
|
||||
## Creating Pull Requests
|
||||
|
||||
### When to Create PRs
|
||||
Use the `gh` command via the Bash tool for ALL GitHub-related tasks including working with issues, pull requests, checks, and releases.
|
||||
|
||||
### Pull Request Workflow
|
||||
|
||||
**Step 1 - Understand Branch State (in parallel):**
|
||||
Run these bash commands simultaneously:
|
||||
- `git status` - see all untracked files
|
||||
- `git diff` - see both staged and unstaged changes
|
||||
- Check if the current branch tracks a remote branch and is up to date
|
||||
- `git log` and `git diff [base-branch]...HEAD` - understand the full commit history from when the branch diverged
|
||||
|
||||
**Step 2 - Analyze All Commits:**
|
||||
Analyze all changes that will be included in the pull request, making sure to look at all relevant commits (NOT just the latest commit, but ALL commits that will be included in the pull request).
|
||||
|
||||
Draft a pull request summary covering:
|
||||
- What changed
|
||||
- Why it changed
|
||||
- How to test it
|
||||
|
||||
**Step 3 - Create PR (in parallel if needed):**
|
||||
- Create new branch if needed
|
||||
- Push to remote with -u flag if needed
|
||||
- Create PR using `gh pr create` with the format below
|
||||
|
||||
Use a HEREDOC to pass the body for correct formatting:
|
||||
|
||||
```bash
|
||||
gh pr create --title "the pr title" --body "$(cat <<'EOF'
|
||||
## Summary
|
||||
<1-3 bullet points>
|
||||
|
||||
## Test plan
|
||||
[Bulleted markdown checklist of TODOs for testing the pull request...]
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
### Important Notes
|
||||
- DO NOT use the TodoWrite or Task tools
|
||||
- Return the PR URL when done
|
||||
- All changes flow through PRs for human review
|
||||
- Branch protection rules still apply
|
||||
|
||||
## Using GitHub CLI (gh)
|
||||
|
||||
The `gh` command provides comprehensive GitHub integration:
|
||||
|
||||
**View PR comments:**
|
||||
```bash
|
||||
gh api repos/foo/bar/pulls/123/comments
|
||||
```
|
||||
|
||||
**Work with issues:**
|
||||
```bash
|
||||
gh issue list
|
||||
gh issue create --title "Bug report" --body "Description"
|
||||
```
|
||||
|
||||
**Check PR status:**
|
||||
```bash
|
||||
gh pr status
|
||||
gh pr view 123
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always check git status** before and after operations
|
||||
2. **Review diffs carefully** before committing
|
||||
3. **Follow repository conventions** for commit messages
|
||||
4. **Never commit secrets** or sensitive files
|
||||
5. **Verify branch state** before creating PRs
|
||||
6. **Include all relevant commits** in PR summaries
|
||||
7. **Use descriptive titles** and comprehensive descriptions
|
||||
8. **Test before pushing** when possible
|
||||
9. **Respect git hooks** and handle their feedback appropriately
|
||||
10. **Ask for clarification** if unsure about destructive operations
|
||||
147
skills/headless/SKILL.md
Normal file
147
skills/headless/SKILL.md
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
name: headless
|
||||
description: How to run Claude Code in headless mode for automation, scripting, and CI/CD integration. Use when user asks about non-interactive mode, automation, scripting, or programmatic usage.
|
||||
---
|
||||
|
||||
# Claude Code Headless Mode
|
||||
|
||||
## Overview
|
||||
Headless mode enables running Claude Code programmatically via command line without an interactive UI, making it suitable for automation, scripts, and integration with other tools.
|
||||
|
||||
## Basic Usage
|
||||
The primary interface is the `claude` command with the `--print` (or `-p`) flag for non-interactive execution:
|
||||
|
||||
```bash
|
||||
claude -p "Stage my changes and write commits" \
|
||||
--allowedTools "Bash,Read" \
|
||||
--permission-mode acceptEdits
|
||||
```
|
||||
|
||||
## Key Configuration Options
|
||||
|
||||
| Flag | Purpose | Example |
|
||||
|------|---------|---------|
|
||||
| `--print`, `-p` | Run non-interactively | `claude -p "query"` |
|
||||
| `--output-format` | Set output type (text, json, stream-json) | `claude -p --output-format json` |
|
||||
| `--resume`, `-r` | Resume by session ID | `claude --resume abc123` |
|
||||
| `--continue`, `-c` | Continue recent conversation | `claude --continue` |
|
||||
| `--allowedTools` | Specify permitted tools | `claude --allowedTools "Bash,Read"` |
|
||||
| `--mcp-config` | Load MCP servers from JSON | `claude --mcp-config servers.json` |
|
||||
|
||||
## Output Formats
|
||||
|
||||
### Text Output (Default)
|
||||
Returns plain text response.
|
||||
|
||||
### JSON Output
|
||||
Provides structured data with metadata:
|
||||
```json
|
||||
{
|
||||
"type": "result",
|
||||
"subtype": "success",
|
||||
"total_cost_usd": 0.003,
|
||||
"duration_ms": 1234,
|
||||
"num_turns": 6,
|
||||
"result": "Response text...",
|
||||
"session_id": "abc123"
|
||||
}
|
||||
```
|
||||
|
||||
### Streaming JSON Output
|
||||
Emits messages as received in JSONL format, useful for real-time processing.
|
||||
|
||||
## Input Methods
|
||||
|
||||
### Text Input
|
||||
Direct arguments or stdin:
|
||||
```bash
|
||||
echo "Explain this code" | claude -p
|
||||
```
|
||||
|
||||
### Streaming JSON Input
|
||||
Multiple conversation turns via stdin using JSONL format with `-p`, `--output-format stream-json`, and `--input-format stream-json`.
|
||||
|
||||
## Multi-turn Conversations
|
||||
|
||||
Resume existing sessions:
|
||||
```bash
|
||||
claude --continue "Refactor for performance"
|
||||
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Fix linting issues"
|
||||
```
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### SRE Incident Response
|
||||
Diagnose issues with severity assessment using allowed tools and MCP configuration for monitoring integrations.
|
||||
|
||||
### Security Review
|
||||
Audit pull request diffs for vulnerabilities and compliance issues using Read and WebSearch tools.
|
||||
|
||||
### Legal Assistant
|
||||
Multi-step document review maintaining session context across separate requests.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Use JSON output for programmatic parsing and integration
|
||||
- Parse results with tools like `jq` for data extraction
|
||||
- Handle errors by checking exit codes and stderr
|
||||
- Maintain session context for multi-turn workflows
|
||||
- Implement timeouts for long-running operations
|
||||
- Respect rate limits with delays between requests
|
||||
- Leverage session management for maintaining conversation state
|
||||
|
||||
## Example: Automated Code Review
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Review PR changes in headless mode
|
||||
|
||||
RESULT=$(claude -p "Review changes in git diff for security issues" \
|
||||
--allowedTools "Bash,Read,Grep" \
|
||||
--output-format json \
|
||||
--permission-mode acceptAll)
|
||||
|
||||
# Parse result
|
||||
echo "$RESULT" | jq -r '.result'
|
||||
|
||||
# Check exit code
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Review failed"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Example: CI/CD Integration
|
||||
|
||||
```bash
|
||||
# In .gitlab-ci.yml or GitHub Actions
|
||||
claude -p "Run tests and fix any failures" \
|
||||
--allowedTools "Bash,Read,Edit,Write" \
|
||||
--max-turns 10 \
|
||||
--output-format json
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
Check exit codes and parse error messages:
|
||||
- Exit code 0: Success
|
||||
- Non-zero: Error occurred (check stderr)
|
||||
|
||||
```bash
|
||||
if ! claude -p "task" 2>error.log; then
|
||||
echo "Error: $(cat error.log)"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Session Management
|
||||
|
||||
Save session IDs for continuation:
|
||||
```bash
|
||||
# First run
|
||||
RESULT=$(claude -p "Start analysis" --output-format json)
|
||||
SESSION_ID=$(echo "$RESULT" | jq -r '.session_id')
|
||||
|
||||
# Continue later
|
||||
claude --resume "$SESSION_ID" "Continue analysis"
|
||||
```
|
||||
191
skills/hooks/SKILL.md
Normal file
191
skills/hooks/SKILL.md
Normal file
@@ -0,0 +1,191 @@
|
||||
---
|
||||
name: hooks
|
||||
description: How to create and configure hooks in Claude Code for automated validation, transformations, and lifecycle event handling. Use when user asks about hooks, event automation, pre/post tool execution, session management, or automated workflows. Ignore when the user types in /hooks and simply allow the slash command to execute.
|
||||
---
|
||||
|
||||
# Claude Code Hooks
|
||||
|
||||
## Overview
|
||||
|
||||
Claude Code hooks are automated scripts that execute at specific lifecycle events, enabling validation, transformation, and control over tool execution and session management.
|
||||
|
||||
## Configuration Structure
|
||||
|
||||
Hooks are configured in settings files (`~/.claude/settings.json`, `.claude/settings.json`, or `.claude/settings.local.json`) using this pattern:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"EventName": [
|
||||
{
|
||||
"matcher": "ToolPattern",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "your-command-here",
|
||||
"timeout": 60
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key features:**
|
||||
- Matchers use case-sensitive patterns (regex supported)
|
||||
- Use `*` or empty string to match all tools
|
||||
- Optional timeout configuration (default: 60 seconds)
|
||||
- `$CLAUDE_PROJECT_DIR` environment variable available for project-relative paths
|
||||
|
||||
## Hook Events
|
||||
|
||||
### PreToolUse & PostToolUse
|
||||
Executes before/after tool operations. Supports matchers for:
|
||||
- Task, Bash, Glob, Grep, Read, Edit, Write, WebFetch, WebSearch
|
||||
|
||||
### UserPromptSubmit
|
||||
Runs when the user submits a prompt, before Claude processes it, enabling context injection and prompt validation.
|
||||
|
||||
### Notification
|
||||
Triggers when Claude requests permissions or waits for input.
|
||||
|
||||
### Stop & SubagentStop
|
||||
Executes when agents complete responses.
|
||||
|
||||
### SessionStart
|
||||
Useful for loading in development context like existing issues or recent changes to your codebase, installing dependencies, or setting up environment variables.
|
||||
|
||||
**Environment persistence:**
|
||||
Use `CLAUDE_ENV_FILE` to persist variables across bash commands:
|
||||
```bash
|
||||
echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
|
||||
```
|
||||
|
||||
### SessionEnd
|
||||
Runs during session cleanup with `reason` field (clear, logout, prompt_input_exit, other).
|
||||
|
||||
### PreCompact
|
||||
Executes before context compaction with matchers: `manual` or `auto`.
|
||||
|
||||
## Hook Input/Output
|
||||
|
||||
**Input delivered via stdin as JSON containing:**
|
||||
- session_id, transcript_path, cwd, permission_mode
|
||||
- hook_event_name and event-specific fields
|
||||
|
||||
**Output methods:**
|
||||
|
||||
1. **Exit codes:**
|
||||
- 0: Success (stdout shown in transcript mode)
|
||||
- 2: Blocking error (stderr fed back to Claude)
|
||||
- Other: Non-blocking error
|
||||
|
||||
2. **JSON output** for advanced control:
|
||||
```json
|
||||
{
|
||||
"continue": true,
|
||||
"stopReason": "message",
|
||||
"suppressOutput": true,
|
||||
"systemMessage": "warning"
|
||||
}
|
||||
```
|
||||
|
||||
## Decision Control Examples
|
||||
|
||||
**PreToolUse:** Allow, deny, or ask for tool execution with optional input modification:
|
||||
```json
|
||||
{
|
||||
"hookSpecificOutput": {
|
||||
"permissionDecision": "allow",
|
||||
"permissionDecisionReason": "Auto-approved",
|
||||
"updatedInput": {"field": "value"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**PostToolUse:** Provide feedback or block:
|
||||
```json
|
||||
{
|
||||
"decision": "block",
|
||||
"reason": "Explanation"
|
||||
}
|
||||
```
|
||||
|
||||
**UserPromptSubmit:** Block prompts or add context:
|
||||
```json
|
||||
{
|
||||
"decision": "block",
|
||||
"reason": "Security violation"
|
||||
}
|
||||
```
|
||||
|
||||
**Stop/SubagentStop:** Prevent completion:
|
||||
```json
|
||||
{
|
||||
"decision": "block",
|
||||
"reason": "Must continue with..."
|
||||
}
|
||||
```
|
||||
|
||||
## MCP Tool Integration
|
||||
|
||||
MCP tools follow pattern: `mcp__<server>__<tool>`
|
||||
|
||||
Configure with regex matchers:
|
||||
```json
|
||||
{
|
||||
"matcher": "mcp__memory__.*",
|
||||
"hooks": [{"type": "command", "command": "validate.py"}]
|
||||
}
|
||||
```
|
||||
|
||||
## Practical Examples
|
||||
|
||||
**Bash validation (exit code):**
|
||||
Detect non-preferred commands and reject them with exit code 2.
|
||||
|
||||
**UserPromptSubmit context injection (exit code 0):**
|
||||
Add current time or project context via stdout; Claude sees this automatically.
|
||||
|
||||
**PreToolUse approval (JSON):**
|
||||
Auto-approve documentation file reads while maintaining security audit trails.
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
- **Notifications**: Customize input/permission alerts
|
||||
- **Automatic formatting**: Run `prettier` on TypeScript, `gofmt` on Go files after edits
|
||||
- **Logging**: Track executed commands for compliance
|
||||
- **Feedback**: Automated codebase convention validation
|
||||
- **Custom permissions**: Block production/sensitive file modifications
|
||||
|
||||
## Execution Details
|
||||
|
||||
- **Timeout:** 60 seconds default, configurable per command
|
||||
- **Parallelization:** All matching hooks run simultaneously
|
||||
- **Deduplication:** Identical commands execute once
|
||||
- **Environment:** Runs in current directory with Claude's environment
|
||||
|
||||
## Security Considerations
|
||||
|
||||
**Critical warning:** Claude Code hooks execute arbitrary shell commands on your system automatically. By using hooks, you acknowledge that:
|
||||
- You are solely responsible for the commands you configure
|
||||
- Hooks can modify, delete, or access any files your user account can access
|
||||
- Malicious or poorly written hooks can cause data loss or system damage
|
||||
|
||||
**Best practices:**
|
||||
- Validate and sanitize inputs
|
||||
- Always quote shell variables (`"$VAR"`)
|
||||
- Block path traversal attempts
|
||||
- Use absolute paths
|
||||
- Avoid sensitive files (.env, .git, credentials)
|
||||
|
||||
Configuration snapshots prevent mid-session modifications from affecting behavior.
|
||||
|
||||
## Debugging
|
||||
|
||||
Use `claude --debug` for hook execution details showing matched patterns, command execution, status codes, and output. Progress messages display in transcript mode (Ctrl-R).
|
||||
|
||||
## Configuration via Slash Command
|
||||
|
||||
Use the `/hooks` slash command to configure hooks interactively and save to either user settings (all projects) or project-specific settings.
|
||||
282
skills/ide/SKILL.md
Normal file
282
skills/ide/SKILL.md
Normal file
@@ -0,0 +1,282 @@
|
||||
---
|
||||
name: ide
|
||||
description: How to integrate Claude Code with VS Code and JetBrains IDEs. Use when user asks about IDE integration, VS Code extension, JetBrains plugin, or IDE setup.
|
||||
---
|
||||
|
||||
# Claude Code IDE Integration
|
||||
|
||||
## VS Code Extension (Beta)
|
||||
|
||||
### Overview
|
||||
|
||||
Claude Code integrates with Visual Studio Code through a native extension, providing a dedicated sidebar panel with IDE-native features.
|
||||
|
||||
### Key Features
|
||||
|
||||
**Native IDE experience:**
|
||||
- Dedicated sidebar panel accessed via the Spark icon
|
||||
- Review Claude's proposed changes before accepting
|
||||
- Auto-accept mode for automatic application of edits
|
||||
- Inline diff viewing with expandable details
|
||||
|
||||
**Integration features:**
|
||||
- File management through @-mentions and file picker attachment
|
||||
- Model Context Protocol (MCP) server integration
|
||||
- Conversation history access
|
||||
- Multiple simultaneous sessions
|
||||
- Support for most CLI slash commands
|
||||
|
||||
### Requirements & Installation
|
||||
|
||||
**Requirements:**
|
||||
- VS Code 1.98.0 or higher
|
||||
- Claude Code installed globally
|
||||
|
||||
**Installation:**
|
||||
Download from the Visual Studio Code Extension Marketplace.
|
||||
|
||||
Search for "Claude Code" in VS Code Extensions panel.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. Click the Spark icon to open the Claude Code panel
|
||||
2. Drag the sidebar wider to see inline diffs
|
||||
3. Click on diffs to expand for full details
|
||||
4. Interact with Claude as you would in the terminal
|
||||
5. Review and accept/reject changes
|
||||
|
||||
### Configuration
|
||||
|
||||
**Auto-accept mode:**
|
||||
Enable to automatically apply Claude's edits without manual review.
|
||||
|
||||
**File attachments:**
|
||||
Use @-mentions or the file picker to attach files to conversations.
|
||||
|
||||
**MCP servers:**
|
||||
Configure MCP integrations for extended functionality.
|
||||
|
||||
### Third-Party Provider Support
|
||||
|
||||
The extension supports Amazon Bedrock and Google Vertex AI through environment variable configuration in VS Code settings:
|
||||
|
||||
**Settings (JSON):**
|
||||
```json
|
||||
{
|
||||
"claude-code.env": {
|
||||
"ANTHROPIC_API_KEY": "your-key",
|
||||
"AWS_REGION": "us-east-1",
|
||||
"ANTHROPIC_VERTEX_PROJECT_ID": "your-project"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Current Limitations
|
||||
|
||||
Features not yet implemented:
|
||||
- Full MCP configuration
|
||||
- Subagents setup
|
||||
- Checkpoints
|
||||
- Advanced shortcuts
|
||||
- Tab completion
|
||||
|
||||
**Note:** These features are available in the terminal version.
|
||||
|
||||
### Legacy CLI Integration
|
||||
|
||||
For terminal-based users, the integration auto-installs when running `claude` from VS Code's integrated terminal.
|
||||
|
||||
**Features:**
|
||||
- Selection context sharing
|
||||
- Automatic diagnostic reporting
|
||||
- Terminal-based interaction
|
||||
|
||||
## JetBrains Integration
|
||||
|
||||
### Overview
|
||||
|
||||
Claude Code integrates with JetBrains IDEs through a dedicated plugin, offering features like interactive diff viewing and automatic selection context sharing.
|
||||
|
||||
### Supported IDEs
|
||||
|
||||
The plugin works with:
|
||||
- IntelliJ IDEA
|
||||
- PyCharm
|
||||
- Android Studio
|
||||
- WebStorm
|
||||
- PhpStorm
|
||||
- GoLand
|
||||
|
||||
### Key Features
|
||||
|
||||
**Quick launch:**
|
||||
- `Cmd+Esc` (Mac)
|
||||
- `Ctrl+Esc` (Windows/Linux)
|
||||
|
||||
**Diff viewing:**
|
||||
Code changes display directly in the IDE diff viewer
|
||||
|
||||
**Selection context:**
|
||||
Current IDE selections automatically share with Claude Code
|
||||
|
||||
**File references:**
|
||||
- `Cmd+Option+K` (Mac)
|
||||
- `Alt+Ctrl+K` (Linux/Windows)
|
||||
|
||||
**Diagnostic sharing:**
|
||||
IDE errors and diagnostics automatically sync with Claude
|
||||
|
||||
### Installation Methods
|
||||
|
||||
#### Marketplace Installation
|
||||
1. Find the Claude Code plugin in the JetBrains marketplace
|
||||
2. Install the plugin
|
||||
3. **Restart your IDE completely**
|
||||
|
||||
#### Auto-Installation
|
||||
The plugin may self-install when running `claude` in the integrated terminal.
|
||||
|
||||
**Important:** Requires full IDE restart to activate.
|
||||
|
||||
### Configuration
|
||||
|
||||
#### Claude Code Settings
|
||||
|
||||
1. Run `claude`
|
||||
2. Enter `/config`
|
||||
3. Set the diff tool to `auto` for automatic IDE detection
|
||||
|
||||
#### Plugin Settings
|
||||
|
||||
Go to: **Settings → Tools → Claude Code**
|
||||
|
||||
**Configuration options:**
|
||||
- Specify custom Claude command paths
|
||||
- Enable multi-line prompts with Option+Enter (macOS)
|
||||
- Configure automatic updates
|
||||
|
||||
#### ESC Key Troubleshooting
|
||||
|
||||
If ESC doesn't interrupt operations:
|
||||
|
||||
**Option 1:**
|
||||
Settings → Tools → Terminal → Uncheck "Move focus to the editor with Escape"
|
||||
|
||||
**Option 2:**
|
||||
Delete the "Switch focus to Editor" shortcut
|
||||
|
||||
### Special Configurations
|
||||
|
||||
#### Remote Development
|
||||
|
||||
Install the plugin on the remote host:
|
||||
Settings → Plugin (Host)
|
||||
|
||||
#### WSL Users
|
||||
|
||||
Set Claude command as:
|
||||
```
|
||||
wsl -d Ubuntu -- bash -lic "claude"
|
||||
```
|
||||
|
||||
Replace `Ubuntu` with your distribution name.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
**Plugin not working:**
|
||||
1. Run Claude from project root directory
|
||||
2. Verify plugin is enabled in IDE settings
|
||||
3. Completely restart the IDE (multiple times if needed)
|
||||
4. Check that Claude Code is installed globally
|
||||
|
||||
**WSL-specific issues:**
|
||||
Consult the dedicated troubleshooting guide in the Claude Code documentation.
|
||||
|
||||
**Diff viewer not showing:**
|
||||
1. Verify `/config` has diff tool set to `auto`
|
||||
2. Restart IDE
|
||||
3. Check plugin version is up to date
|
||||
|
||||
### Security Note
|
||||
|
||||
When auto-edit is enabled, Claude Code may modify IDE configuration files. Consider using manual approval mode for edits when using JetBrains IDEs.
|
||||
|
||||
## Comparison: VS Code vs JetBrains
|
||||
|
||||
| Feature | VS Code | JetBrains |
|
||||
|---------|---------|-----------|
|
||||
| **UI Integration** | Sidebar panel | Terminal-based |
|
||||
| **Diff Viewing** | Inline diffs | Native diff viewer |
|
||||
| **File Attachment** | @-mentions, picker | Selection sharing |
|
||||
| **Shortcuts** | Standard | Customizable |
|
||||
| **MCP Support** | Yes (basic) | Via CLI |
|
||||
| **Multi-session** | Yes | Via CLI |
|
||||
| **Maturity** | Beta | Stable |
|
||||
|
||||
## Best Practices
|
||||
|
||||
### For VS Code
|
||||
|
||||
1. **Drag sidebar wider** to see diffs clearly
|
||||
2. **Use @-mentions** for efficient file attachment
|
||||
3. **Enable auto-accept** only after building trust
|
||||
4. **Keep extension updated** for latest features
|
||||
5. **Use MCP servers** for extended capabilities
|
||||
|
||||
### For JetBrains
|
||||
|
||||
1. **Set diff tool to auto** for seamless integration
|
||||
2. **Use keyboard shortcuts** for quick access
|
||||
3. **Run from project root** for proper context
|
||||
4. **Share selections** for targeted help
|
||||
5. **Completely restart IDE** after installation
|
||||
|
||||
### General
|
||||
|
||||
1. **Start with manual approval** before enabling auto-accept
|
||||
2. **Use version control** to track Claude's changes
|
||||
3. **Review diffs carefully** before accepting
|
||||
4. **Configure permissions** appropriately
|
||||
5. **Leverage IDE diagnostics** for better context
|
||||
6. **Use subagents** for specialized tasks (CLI)
|
||||
7. **Enable checkpointing** for easy rollback (CLI)
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### VS Code: Feature Implementation
|
||||
|
||||
1. Open Claude Code sidebar
|
||||
2. Describe feature requirements
|
||||
3. Attach relevant files with @-mentions
|
||||
4. Review proposed changes in inline diffs
|
||||
5. Accept/reject individual changes
|
||||
6. Test and iterate
|
||||
|
||||
### JetBrains: Bug Fixing
|
||||
|
||||
1. Select error in editor
|
||||
2. Press `Cmd+Esc` to open Claude Code
|
||||
3. Share selection context automatically
|
||||
4. Describe the issue
|
||||
5. Review fix in diff viewer
|
||||
6. Accept and test
|
||||
|
||||
### Both: Code Review
|
||||
|
||||
1. Open files to review
|
||||
2. Ask Claude to review for:
|
||||
- Security issues
|
||||
- Performance problems
|
||||
- Best practices violations
|
||||
- Code quality improvements
|
||||
3. Review suggestions
|
||||
4. Apply relevant fixes
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Both integrations are actively developed. Upcoming features may include:
|
||||
- Enhanced MCP configuration (VS Code)
|
||||
- Subagent support (VS Code)
|
||||
- Checkpoint management (VS Code)
|
||||
- Improved multi-session handling
|
||||
- Advanced shortcuts and completions
|
||||
438
skills/interactive-mode/SKILL.md
Normal file
438
skills/interactive-mode/SKILL.md
Normal file
@@ -0,0 +1,438 @@
|
||||
---
|
||||
name: interactive-mode
|
||||
description: Interactive mode features including keyboard shortcuts, vim mode, command history, and background tasks. Use when user asks about REPL, keyboard shortcuts, interactive features, or vim mode.
|
||||
---
|
||||
|
||||
# Claude Code Interactive Mode
|
||||
|
||||
## Overview
|
||||
|
||||
Interactive mode provides a rich REPL (Read-Eval-Print Loop) environment with keyboard shortcuts, command history, vim editing, and background task management.
|
||||
|
||||
## Keyboard Controls
|
||||
|
||||
### Essential Shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Ctrl+C` | Cancel current input or generation |
|
||||
| `Ctrl+D` | Exit the Claude Code session |
|
||||
| `Ctrl+L` | Clear terminal screen (preserves conversation history) |
|
||||
| `Ctrl+O` | Toggle verbose output (shows detailed tool usage) |
|
||||
| `Ctrl+R` | Search backwards through command history |
|
||||
| `Ctrl+B` | Move bash invocation to background |
|
||||
| `Tab` | Switch extended thinking on and off |
|
||||
|
||||
### Navigation
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `↑`/`↓` | Navigate through command history |
|
||||
| `←`/`→` | Move cursor left/right |
|
||||
| `Home` | Move to start of line |
|
||||
| `End` | Move to end of line |
|
||||
|
||||
### Help
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `?` | Show help and shortcuts |
|
||||
|
||||
## Multiline Input Methods
|
||||
|
||||
Claude Code supports several ways to create multiline inputs:
|
||||
|
||||
### Universal Method
|
||||
```
|
||||
Line 1 \
|
||||
Line 2 \
|
||||
Line 3
|
||||
```
|
||||
**Backslash + Enter** works universally across all platforms.
|
||||
|
||||
### macOS Default
|
||||
```
|
||||
Option+Enter
|
||||
```
|
||||
**Option+Enter** creates a newline on macOS.
|
||||
|
||||
### After Terminal Setup
|
||||
```
|
||||
Shift+Enter
|
||||
```
|
||||
**Shift+Enter** functions after running `/terminal-setup`.
|
||||
|
||||
## Vim Editor Mode
|
||||
|
||||
### Enabling Vim Mode
|
||||
|
||||
**Temporary (current session):**
|
||||
```
|
||||
/vim
|
||||
```
|
||||
|
||||
**Permanent:**
|
||||
```
|
||||
/config
|
||||
```
|
||||
Then enable vim mode in configuration.
|
||||
|
||||
### Vim Navigation
|
||||
|
||||
**Movement:**
|
||||
- `h` - Move left
|
||||
- `j` - Move down
|
||||
- `k` - Move up
|
||||
- `l` - Move right
|
||||
- `w` - Move forward one word
|
||||
- `e` - Move to end of word
|
||||
- `b` - Move backward one word
|
||||
- `0` - Move to start of line
|
||||
- `$` - Move to end of line
|
||||
|
||||
**Editing:**
|
||||
- `i` - Insert mode
|
||||
- `a` - Append (insert after cursor)
|
||||
- `A` - Append at end of line
|
||||
- `I` - Insert at start of line
|
||||
- `x` - Delete character
|
||||
- `dd` - Delete line
|
||||
- `d$` - Delete to end of line
|
||||
- `d0` - Delete to start of line
|
||||
- `dw` - Delete word
|
||||
- `.` - Repeat last operation
|
||||
|
||||
**Modes:**
|
||||
- `Esc` - Return to normal mode
|
||||
- `i` - Enter insert mode
|
||||
|
||||
## Command History & Search
|
||||
|
||||
### Command History
|
||||
|
||||
**Navigation:**
|
||||
- `↑` - Previous command
|
||||
- `↓` - Next command
|
||||
|
||||
**Organization:**
|
||||
Session history is organized by working directory for better context.
|
||||
|
||||
### Search History
|
||||
|
||||
**Backward search:**
|
||||
1. Press `Ctrl+R`
|
||||
2. Type search term
|
||||
3. Press `Ctrl+R` again to cycle through matches
|
||||
4. Press `Enter` to execute
|
||||
5. Press `Esc` to cancel
|
||||
|
||||
**Features:**
|
||||
- Displays matching commands
|
||||
- Highlights search terms
|
||||
- Allows cycling through multiple matches
|
||||
|
||||
## Background Task Execution
|
||||
|
||||
### Overview
|
||||
|
||||
When Claude Code runs a command in the background, it runs the command asynchronously and immediately returns a background task ID.
|
||||
|
||||
### Trigger Background Execution
|
||||
|
||||
**Automatic:**
|
||||
Claude may prompt to background long-running tasks.
|
||||
|
||||
**Manual:**
|
||||
Press `Ctrl+B` to move regular bash invocations to the background.
|
||||
|
||||
### Managing Background Tasks
|
||||
|
||||
**View output:**
|
||||
Output is buffered and can be retrieved later.
|
||||
|
||||
**Monitor tasks:**
|
||||
Claude shows status updates for background tasks.
|
||||
|
||||
**Continue working:**
|
||||
You can interact with Claude while background tasks run.
|
||||
|
||||
## Quick Command Prefixes
|
||||
|
||||
### Special Prefixes
|
||||
|
||||
| Prefix | Purpose | Example |
|
||||
|--------|---------|---------|
|
||||
| `#` | Add content to CLAUDE.md memory | `# Use 2-space indentation` |
|
||||
| `/` | Trigger slash commands | `/help` |
|
||||
| `!` | Direct bash execution (no Claude interpretation) | `!ls -la` |
|
||||
| `@` | File path autocomplete | `@src/` + Tab |
|
||||
|
||||
### Memory Shortcut (`#`)
|
||||
|
||||
**Add to memory:**
|
||||
```
|
||||
# Always use TypeScript strict mode
|
||||
```
|
||||
|
||||
Claude will prompt you to select the target memory file:
|
||||
- Project memory (`.claude/CLAUDE.md`)
|
||||
- User memory (`~/.claude/CLAUDE.md`)
|
||||
|
||||
### Direct Bash (`!`)
|
||||
|
||||
**Execute without interpretation:**
|
||||
```
|
||||
!git status
|
||||
!npm test
|
||||
!echo "Hello"
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- Faster execution
|
||||
- No AI interpretation overhead
|
||||
- Direct command output
|
||||
|
||||
### File Autocomplete (`@`)
|
||||
|
||||
**Trigger autocomplete:**
|
||||
```
|
||||
@src/
|
||||
```
|
||||
|
||||
Press `Tab` to see file suggestions.
|
||||
|
||||
**Attach files to conversation:**
|
||||
```
|
||||
Review @src/components/Button.tsx for issues
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Extended Thinking
|
||||
|
||||
**Toggle extended thinking:**
|
||||
Press `Tab` to enable/disable.
|
||||
|
||||
**What it does:**
|
||||
- Allows Claude more thinking time
|
||||
- Better for complex reasoning
|
||||
- Uses more tokens
|
||||
- Shows thinking process in verbose mode
|
||||
|
||||
### Verbose Output
|
||||
|
||||
**Toggle verbose mode:**
|
||||
Press `Ctrl+O`
|
||||
|
||||
**What it shows:**
|
||||
- Detailed tool usage
|
||||
- API calls and responses
|
||||
- Token usage
|
||||
- Performance metrics
|
||||
- Debugging information
|
||||
|
||||
### Screen Management
|
||||
|
||||
**Clear screen:**
|
||||
Press `Ctrl+L` to clear the terminal while preserving conversation history.
|
||||
|
||||
**Difference from `/clear`:**
|
||||
- `Ctrl+L`: Clears screen only (visual)
|
||||
- `/clear`: Clears conversation history (context)
|
||||
|
||||
## Session Management
|
||||
|
||||
### Exit Session
|
||||
|
||||
**Clean exit:**
|
||||
Press `Ctrl+D` or type `/exit`
|
||||
|
||||
**Force exit:**
|
||||
Press `Ctrl+C` multiple times
|
||||
|
||||
### Interrupting Operations
|
||||
|
||||
**Cancel current operation:**
|
||||
Press `Ctrl+C` once
|
||||
|
||||
**Common scenarios:**
|
||||
- Long-running AI generation
|
||||
- Bash command execution
|
||||
- File operations
|
||||
- Web searches
|
||||
|
||||
## Tips & Tricks
|
||||
|
||||
### Efficient Navigation
|
||||
|
||||
**Quick history access:**
|
||||
```
|
||||
↑ # Previous command
|
||||
↑↑ # Two commands back
|
||||
```
|
||||
|
||||
**Search specific commands:**
|
||||
```
|
||||
Ctrl+R "test" # Find commands with "test"
|
||||
```
|
||||
|
||||
### Productive Workflows
|
||||
|
||||
**Background long tasks:**
|
||||
```
|
||||
# Long-running test suite
|
||||
Ctrl+B to background it
|
||||
Continue working on other tasks
|
||||
```
|
||||
|
||||
**Quick iterations:**
|
||||
```
|
||||
↑ # Recall last command
|
||||
# Edit slightly
|
||||
Enter # Execute modified version
|
||||
```
|
||||
|
||||
**Memory building:**
|
||||
```
|
||||
# Use snake_case for variables
|
||||
# Prefer composition over inheritance
|
||||
# Write tests for all public APIs
|
||||
```
|
||||
|
||||
### Vim Mode Power Users
|
||||
|
||||
**Fast editing:**
|
||||
```
|
||||
Esc # Normal mode
|
||||
0 # Start of line
|
||||
d$ # Delete to end
|
||||
i # Insert mode
|
||||
Type new content
|
||||
Esc # Back to normal
|
||||
```
|
||||
|
||||
**Quick fixes:**
|
||||
```
|
||||
Esc # Normal mode
|
||||
$ # End of line
|
||||
x # Delete last character
|
||||
a # Append
|
||||
Type correction
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Configure Terminal
|
||||
|
||||
**Run setup:**
|
||||
```
|
||||
/terminal-setup
|
||||
```
|
||||
|
||||
**What it configures:**
|
||||
- Multiline input behavior
|
||||
- Key bindings
|
||||
- Shell integration
|
||||
- Terminal compatibility
|
||||
|
||||
### Configure Settings
|
||||
|
||||
**Access configuration:**
|
||||
```
|
||||
/config
|
||||
```
|
||||
|
||||
**Available settings:**
|
||||
- Vim mode enable/disable
|
||||
- Diff viewer preferences
|
||||
- Permission defaults
|
||||
- Output preferences
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Exploratory Development
|
||||
|
||||
```
|
||||
# Ask questions
|
||||
"explain the authentication flow"
|
||||
|
||||
# Make changes
|
||||
"add rate limiting"
|
||||
|
||||
# Test
|
||||
!npm test
|
||||
|
||||
# Adjust
|
||||
↑ to recall, modify, retry
|
||||
```
|
||||
|
||||
### Debugging Session
|
||||
|
||||
```
|
||||
# Enable verbose
|
||||
Ctrl+O
|
||||
|
||||
# Run with details
|
||||
"analyze the memory leak"
|
||||
|
||||
# Review verbose output
|
||||
# Identify issue
|
||||
# Fix
|
||||
|
||||
# Disable verbose
|
||||
Ctrl+O
|
||||
```
|
||||
|
||||
### Batch Operations
|
||||
|
||||
```
|
||||
# Background first task
|
||||
"run full test suite" → Ctrl+B
|
||||
|
||||
# Continue with other work
|
||||
"refactor user module"
|
||||
|
||||
# Check background task
|
||||
# Complete when done
|
||||
```
|
||||
|
||||
## Integration with Shell
|
||||
|
||||
### Command History Persistence
|
||||
|
||||
Claude Code integrates with your shell's command history, allowing you to:
|
||||
- Access Claude commands in shell history
|
||||
- Use shell history search (Ctrl+R)
|
||||
- Mix Claude commands with regular shell commands
|
||||
|
||||
### Shell Compatibility
|
||||
|
||||
Works with:
|
||||
- Bash
|
||||
- Zsh
|
||||
- Fish
|
||||
- Other POSIX-compatible shells
|
||||
|
||||
### Environment Integration
|
||||
|
||||
Claude Code respects:
|
||||
- Shell environment variables
|
||||
- Shell aliases
|
||||
- Shell functions
|
||||
- Current working directory
|
||||
|
||||
## Accessibility
|
||||
|
||||
### Screen Reader Support
|
||||
|
||||
Claude Code works with screen readers for:
|
||||
- Command input
|
||||
- Output reading
|
||||
- Navigation
|
||||
|
||||
### Keyboard-only Navigation
|
||||
|
||||
All features accessible via keyboard:
|
||||
- No mouse required
|
||||
- Full keyboard navigation
|
||||
- Comprehensive shortcuts
|
||||
67
skills/mcp-tool/SKILL.md
Normal file
67
skills/mcp-tool/SKILL.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
name: mcp-tool
|
||||
description: Understanding the Model Context Protocol (MCP) and how to use it in Claude Code. Use when user asks about MCP, Model Context Protocol, connecting external tools, MCP servers, or extending Claude's capabilities.
|
||||
---
|
||||
|
||||
# Model Context Protocol (MCP)
|
||||
|
||||
## Core Concept
|
||||
|
||||
MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.
|
||||
|
||||
## Purpose & Use Cases
|
||||
|
||||
MCP enables developers to connect AI models to custom tools and data sources in a standardized, interoperable manner—addressing a key need in extending Claude's capabilities beyond its base training.
|
||||
|
||||
## MCP in Anthropic Products
|
||||
|
||||
The protocol integrates across multiple Anthropic offerings:
|
||||
|
||||
1. **Messages API** - Developers can use the MCP connector to link to MCP servers programmatically
|
||||
2. **Claude Code** - Supports adding custom MCP servers or using Claude Code as a server itself
|
||||
3. **Claude.ai** - Teams can enable MCP connectors through the platform
|
||||
4. **Claude Desktop** - Allows local MCP server configuration
|
||||
|
||||
## Build Your Own MCP Products
|
||||
|
||||
For protocol details, server/client development guidance, and community-created implementations, refer to the official MCP Documentation at **modelcontextprotocol.io**.
|
||||
|
||||
## MCP in Claude Code
|
||||
|
||||
### MCP Tool Integration
|
||||
|
||||
MCP tools follow the pattern: `mcp__<server>__<tool>`
|
||||
|
||||
### Using MCP in Hooks
|
||||
|
||||
Configure MCP tools with regex matchers in hooks:
|
||||
```json
|
||||
{
|
||||
"matcher": "mcp__memory__.*",
|
||||
"hooks": [{"type": "command", "command": "validate.py"}]
|
||||
}
|
||||
```
|
||||
|
||||
### MCP Slash Commands
|
||||
|
||||
MCP servers expose prompts as commands with the pattern:
|
||||
|
||||
```
|
||||
/mcp__<server-name>__<prompt-name> [arguments]
|
||||
```
|
||||
|
||||
These are dynamically discovered from connected MCP servers and automatically available when the server is active.
|
||||
|
||||
### Managing MCP Servers
|
||||
|
||||
Use the `/mcp` built-in command to manage MCP server connections.
|
||||
|
||||
## Plugin Integration
|
||||
|
||||
Plugins can include MCP servers via `.mcp.json` configuration for external tool integration.
|
||||
|
||||
## Resources
|
||||
|
||||
- Official MCP Documentation: modelcontextprotocol.io
|
||||
- Anthropic's MCP implementation guides
|
||||
- Community-created MCP servers and implementations
|
||||
148
skills/memory/SKILL.md
Normal file
148
skills/memory/SKILL.md
Normal file
@@ -0,0 +1,148 @@
|
||||
---
|
||||
name: memory
|
||||
description: How to use CLAUDE.md memory files for persistent instructions across sessions. Use when user asks about CLAUDE.md, memory files, project instructions, or persistent context.
|
||||
---
|
||||
|
||||
# Claude Code Memory (CLAUDE.md)
|
||||
|
||||
## Overview
|
||||
Claude Code maintains persistent memories across sessions using CLAUDE.md files organized in a hierarchical structure with four memory locations.
|
||||
|
||||
## Memory Hierarchy
|
||||
|
||||
**Enterprise Policy** (highest priority)
|
||||
- macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`
|
||||
- Linux: `/etc/claude-code/CLAUDE.md`
|
||||
- Windows: `C:\ProgramData\ClaudeCode\CLAUDE.md`
|
||||
- Organization-wide instructions for all users
|
||||
|
||||
**Project Memory**
|
||||
- Location: `./CLAUDE.md` or `./.claude/CLAUDE.md`
|
||||
- Purpose: Team-shared instructions for the project
|
||||
- Shared via source control
|
||||
|
||||
**User Memory**
|
||||
- Location: `~/.claude/CLAUDE.md`
|
||||
- Personal preferences applying across all projects
|
||||
|
||||
**Project Memory (Local)** — Deprecated
|
||||
- `./CLAUDE.local.md` is now superseded by imports
|
||||
|
||||
## CLAUDE.md Imports Feature
|
||||
|
||||
Files support `@path/to/import` syntax for including additional content. Examples:
|
||||
|
||||
```markdown
|
||||
See @README for project overview and @package.json for available npm commands
|
||||
```
|
||||
|
||||
Import paths can be relative or absolute. Practical use case for individual preferences:
|
||||
|
||||
```markdown
|
||||
Individual Preferences - @~/.claude/my-project-instructions.md
|
||||
```
|
||||
|
||||
Imports ignore markdown code spans and support recursive inclusion up to 5 levels deep.
|
||||
|
||||
## Core Usage Methods
|
||||
|
||||
### Quick Addition with `#` Shortcut
|
||||
Start input with `#` followed by your memory. The system prompts you to select the target memory file.
|
||||
|
||||
### Direct Editing
|
||||
Use `/memory` slash command to open memory files in your system editor for extensive modifications.
|
||||
|
||||
### Initialization
|
||||
Run `/init` to bootstrap a CLAUDE.md file with project-specific information.
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Be Specific**: "Use 2-space indentation" outperforms "Format code properly."
|
||||
|
||||
**Structure**: Format memories as bullet points under descriptive markdown headings.
|
||||
|
||||
**Review Periodically**: Update memories as projects evolve.
|
||||
|
||||
**Ideal Memory Content**:
|
||||
- Frequently-used build commands
|
||||
- Code style preferences
|
||||
- Naming conventions
|
||||
- Architectural patterns specific to your project
|
||||
- Testing requirements
|
||||
- Deployment procedures
|
||||
- Code review criteria
|
||||
|
||||
## Example CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# Project Instructions
|
||||
|
||||
## Code Style
|
||||
- Use 2-space indentation
|
||||
- Prefer functional components in React
|
||||
- Use TypeScript strict mode
|
||||
- Follow ESLint rules without exceptions
|
||||
|
||||
## Build Commands
|
||||
- `npm run dev` - Start development server
|
||||
- `npm run test` - Run test suite
|
||||
- `npm run build` - Production build
|
||||
|
||||
## Architecture
|
||||
- API routes in `src/api/`
|
||||
- Components in `src/components/`
|
||||
- Utilities in `src/utils/`
|
||||
- Follow feature-based folder structure
|
||||
|
||||
## Testing
|
||||
- Write unit tests for all utilities
|
||||
- Integration tests for API routes
|
||||
- Use React Testing Library for components
|
||||
|
||||
## External Resources
|
||||
See @README.md for project overview
|
||||
See @CONTRIBUTING.md for contribution guidelines
|
||||
```
|
||||
|
||||
## Working with Team Memories
|
||||
|
||||
**Project-level CLAUDE.md**:
|
||||
- Commit to source control
|
||||
- Share coding standards across team
|
||||
- Define common workflows
|
||||
- Document project-specific conventions
|
||||
|
||||
**Local overrides**:
|
||||
- Use imports to extend project memory
|
||||
- Add personal preferences without affecting team
|
||||
- Reference local configuration files
|
||||
|
||||
## Memory Hierarchy in Practice
|
||||
|
||||
When Claude processes a request, it reads all applicable memory files in order of precedence:
|
||||
1. Enterprise policy (if configured)
|
||||
2. Project memory (team-shared)
|
||||
3. User memory (personal preferences)
|
||||
|
||||
Settings in higher-priority files take precedence over lower-priority ones.
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
**Onboarding**: New team members get instant context from project CLAUDE.md
|
||||
|
||||
**Consistency**: Team maintains consistent code style through shared memory
|
||||
|
||||
**Personalization**: Individual developers add personal preferences via user memory
|
||||
|
||||
**Security**: Enterprise policies enforce security requirements globally
|
||||
|
||||
**Documentation**: Import existing project docs to provide context
|
||||
|
||||
## Tips
|
||||
|
||||
- Keep memories focused and actionable
|
||||
- Use headings to organize different types of instructions
|
||||
- Update memories when conventions change
|
||||
- Leverage imports to avoid duplication
|
||||
- Review memories periodically for relevance
|
||||
- Use specific examples rather than vague guidelines
|
||||
51
skills/output-styles/SKILL.md
Normal file
51
skills/output-styles/SKILL.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: output-styles
|
||||
description: Understanding output styles in Claude Code (deprecated feature). Use when user asks about customizing Claude's behavior, output styles, or explanatory/learning modes.
|
||||
---
|
||||
|
||||
# Claude Code Output Styles
|
||||
|
||||
## Deprecation Status
|
||||
Output styles are **deprecated** as of November 5, 2025. The feature has been automatically converted to plugins and is no longer supported.
|
||||
|
||||
## What Output Styles Were
|
||||
|
||||
Output styles allowed customization of Claude Code's behavior beyond software engineering tasks. They directly modified the system prompt while preserving core capabilities like file operations and script execution.
|
||||
|
||||
## Built-in Styles (Deprecated)
|
||||
|
||||
**Default**: Standard software engineering assistance
|
||||
|
||||
**Explanatory**: Provides educational 'Insights' in between helping you complete software engineering tasks
|
||||
|
||||
**Learning**: Collaborative mode where Claude shares insights and requests user contributions, marked with `TODO(human)` comments
|
||||
|
||||
## How They Worked
|
||||
|
||||
Output styles excluded default code generation instructions and substituted custom system prompt guidance instead. This differed from `CLAUDE.md` or `--append-system-prompt`, which only appended context rather than replacing the base prompt.
|
||||
|
||||
## Migration Path
|
||||
|
||||
Users should transition to:
|
||||
|
||||
1. **SessionStart hooks** - for adding context at session start via plugin-based automation
|
||||
2. **Subagents** - for specialized AI assistants with custom system prompts and specific tool permissions
|
||||
3. **Plugins** - the primary replacement, with more powerful and flexible ways to customize Claude Code's behavior
|
||||
|
||||
## Installation Example
|
||||
|
||||
The explanatory output style is available as a plugin:
|
||||
|
||||
```
|
||||
/plugin marketplace add anthropics/claude-code
|
||||
/plugin install explanatory-output-style@claude-code-plugins
|
||||
```
|
||||
|
||||
## Recommended Alternatives
|
||||
|
||||
For customizing Claude Code's behavior, use:
|
||||
- **Plugins** for distributable, reusable customizations
|
||||
- **Subagents** for task-specific specialized assistants
|
||||
- **SessionStart hooks** for session initialization context
|
||||
- **CLAUDE.md** for project-specific context
|
||||
- `--append-system-prompt` for session-specific instructions
|
||||
331
skills/overview/SKILL.md
Normal file
331
skills/overview/SKILL.md
Normal file
@@ -0,0 +1,331 @@
|
||||
---
|
||||
name: overview
|
||||
description: Overview of Claude Code capabilities, features, and use cases. Use when user asks about what Claude Code is, what it can do, or general capabilities.
|
||||
---
|
||||
|
||||
# Claude Code Overview
|
||||
|
||||
Claude Code is Anthropic's agentic CLI tool designed for developers working in terminal environments.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
### Code Development
|
||||
|
||||
**Build features from descriptions:**
|
||||
Turn plain English requirements into functional code with planning and validation.
|
||||
|
||||
**Examples:**
|
||||
- "Implement user authentication with JWT"
|
||||
- "Add a REST API endpoint for user profiles"
|
||||
- "Create a dashboard component with charts"
|
||||
|
||||
### Debugging & Problem Solving
|
||||
|
||||
**Analyze codebases to identify and fix issues:**
|
||||
Work from error messages or bug descriptions provided by users.
|
||||
|
||||
**Examples:**
|
||||
- "Fix the TypeError in dashboard.tsx"
|
||||
- "Debug why the API returns 500 errors"
|
||||
- "Resolve the memory leak in the worker process"
|
||||
|
||||
### Codebase Navigation
|
||||
|
||||
**Ask questions about project structure:**
|
||||
Claude maintains awareness of entire codebases while accessing current web information and external data sources via MCP integrations.
|
||||
|
||||
**Examples:**
|
||||
- "Where is user authentication handled?"
|
||||
- "What does this project do?"
|
||||
- "How do the payment flows work?"
|
||||
- "Show me all the API endpoints"
|
||||
|
||||
### Task Automation
|
||||
|
||||
**Handle routine development work:**
|
||||
- Resolve lint issues
|
||||
- Manage merge conflicts
|
||||
- Generate release notes
|
||||
- Run test suites and fix failures
|
||||
- Update dependencies
|
||||
- Refactor code for consistency
|
||||
|
||||
## Why Developers Prefer It
|
||||
|
||||
### Native Integration
|
||||
|
||||
**Works directly within developer workflows:**
|
||||
Unlike separate chat interfaces, Claude Code operates directly in the terminal and integrates with existing tools.
|
||||
|
||||
**Terminal-native features:**
|
||||
- Interactive REPL mode
|
||||
- Command history
|
||||
- Vim mode support
|
||||
- File path autocomplete
|
||||
- Background task execution
|
||||
|
||||
### Proactive Execution
|
||||
|
||||
**Independent action:**
|
||||
The tool can edit files, execute commands, and create commits independently.
|
||||
|
||||
**Extensibility through MCP:**
|
||||
Access design documents, project management systems, and custom tooling through Model Context Protocol integrations.
|
||||
|
||||
### Unix Philosophy
|
||||
|
||||
**Composable, scriptable design:**
|
||||
- Pipe input and output
|
||||
- Chain with other commands
|
||||
- Integrate into CI/CD pipelines
|
||||
- Use in automation scripts
|
||||
- Parse JSON output programmatically
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Pipe git diff for review
|
||||
git diff | claude -p "review these changes"
|
||||
|
||||
# Parse JSON output
|
||||
claude -p "task" --output-format json | jq -r '.result'
|
||||
|
||||
# Use in scripts
|
||||
if claude -p "run tests" --output-format json | jq -e '.subtype == "success"'; then
|
||||
echo "Tests passed"
|
||||
fi
|
||||
```
|
||||
|
||||
### Enterprise Ready
|
||||
|
||||
**Multiple deployment options:**
|
||||
- Claude API (direct)
|
||||
- AWS Bedrock
|
||||
- Google Cloud Vertex AI
|
||||
|
||||
**Built-in features:**
|
||||
- Security controls
|
||||
- Privacy protections
|
||||
- Compliance support
|
||||
- Usage monitoring
|
||||
- Cost tracking
|
||||
- Team collaboration
|
||||
|
||||
## Key Features
|
||||
|
||||
### Intelligent Context Management
|
||||
|
||||
**Progressive disclosure:**
|
||||
- Only loads relevant information as needed
|
||||
- Manages large codebases efficiently
|
||||
- Uses prompt caching for cost optimization
|
||||
|
||||
**CLAUDE.md memory files:**
|
||||
- Project-level instructions
|
||||
- Team-shared guidelines
|
||||
- Personal preferences
|
||||
- Hierarchical configuration
|
||||
|
||||
### Customization & Extension
|
||||
|
||||
**Slash commands:**
|
||||
Create custom commands for frequent tasks.
|
||||
|
||||
**Subagents:**
|
||||
Specialized AI assistants for specific domains.
|
||||
|
||||
**Skills:**
|
||||
Modular capabilities that extend Claude's expertise.
|
||||
|
||||
**Hooks:**
|
||||
Automated scripts triggered by events.
|
||||
|
||||
**MCP servers:**
|
||||
Connect to external tools and data sources.
|
||||
|
||||
**Plugins:**
|
||||
Shareable packages combining all of the above.
|
||||
|
||||
### Developer Experience
|
||||
|
||||
**Interactive features:**
|
||||
- Real-time diff viewing
|
||||
- File attachment with @-mentions
|
||||
- Conversation history
|
||||
- Session resumption
|
||||
- Checkpoint system for easy rollback
|
||||
|
||||
**IDE integration:**
|
||||
- VS Code extension (beta)
|
||||
- JetBrains plugin
|
||||
- Native diff viewers
|
||||
- Selection context sharing
|
||||
|
||||
### Safety & Control
|
||||
|
||||
**Permission management:**
|
||||
- Granular tool access control
|
||||
- File-level restrictions
|
||||
- Command approval workflows
|
||||
- Sandbox mode for isolation
|
||||
|
||||
**Checkpointing:**
|
||||
- Automatic state tracking
|
||||
- Easy rollback to previous states
|
||||
- Conversation and code rewinding
|
||||
|
||||
**Git integration:**
|
||||
- Safe commit practices
|
||||
- Pull request generation
|
||||
- Adherence to git workflows
|
||||
- Pre-commit hook support
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### Feature Development
|
||||
```
|
||||
"Implement a new search feature with autocomplete"
|
||||
"Add pagination to the user list"
|
||||
"Create an admin dashboard"
|
||||
```
|
||||
|
||||
### Bug Fixing
|
||||
```
|
||||
"Fix the authentication redirect issue"
|
||||
"Resolve the race condition in the worker"
|
||||
"Debug why emails aren't sending"
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
```
|
||||
"Review this code for security issues"
|
||||
"Refactor for better performance"
|
||||
"Add error handling throughout"
|
||||
"Improve test coverage"
|
||||
```
|
||||
|
||||
### DevOps & Automation
|
||||
```
|
||||
"Set up CI/CD pipeline"
|
||||
"Create Docker configuration"
|
||||
"Write deployment scripts"
|
||||
"Generate infrastructure as code"
|
||||
```
|
||||
|
||||
### Documentation
|
||||
```
|
||||
"Add JSDoc comments to all functions"
|
||||
"Generate API documentation"
|
||||
"Create README with examples"
|
||||
"Write migration guide"
|
||||
```
|
||||
|
||||
### Learning & Exploration
|
||||
```
|
||||
"Explain how this authentication works"
|
||||
"What design patterns are used here?"
|
||||
"Show me examples of using this API"
|
||||
"How can I optimize this query?"
|
||||
```
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Installation
|
||||
|
||||
**Requires:** Node.js 18+
|
||||
|
||||
**NPM:**
|
||||
```bash
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
**Native installer:**
|
||||
```bash
|
||||
# macOS/Linux
|
||||
curl -fsSL https://claude.ai/install.sh | bash
|
||||
|
||||
# Homebrew
|
||||
brew install --cask claude-code
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
Start an interactive session and log in:
|
||||
```bash
|
||||
claude
|
||||
/login
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- **Claude.ai** (subscription-based, recommended)
|
||||
- **Claude Console** (API access with prepaid credits)
|
||||
|
||||
### First Steps
|
||||
|
||||
1. Navigate to your project
|
||||
2. Run `claude`
|
||||
3. Ask about your codebase
|
||||
4. Make some changes
|
||||
5. Create a commit
|
||||
|
||||
**Approximate time:** 30 seconds from installation to first task
|
||||
|
||||
## Resources
|
||||
|
||||
- **Documentation:** https://docs.claude.com/en/docs/claude-code
|
||||
- **GitHub:** https://github.com/anthropics/claude-code
|
||||
- **Support:** https://github.com/anthropics/claude-code/issues
|
||||
|
||||
## Comparison: Claude Code vs Other Tools
|
||||
|
||||
### vs GitHub Copilot
|
||||
- **Claude Code:** Full agentic workflows, terminal-native, multi-file operations
|
||||
- **Copilot:** Autocomplete, inline suggestions, IDE-focused
|
||||
|
||||
### vs ChatGPT
|
||||
- **Claude Code:** Direct code execution, file operations, git integration
|
||||
- **ChatGPT:** Conversational interface, manual copy-paste
|
||||
|
||||
### vs Traditional IDEs
|
||||
- **Claude Code:** Natural language interface, autonomous execution
|
||||
- **IDEs:** Manual coding, refactoring tools, debugging
|
||||
|
||||
### vs CI/CD Tools
|
||||
- **Claude Code:** Intelligent automation, context-aware
|
||||
- **CI/CD:** Script-based, deterministic workflows
|
||||
|
||||
**Best approach:** Use Claude Code alongside these tools for comprehensive development support.
|
||||
|
||||
## Enterprise Features
|
||||
|
||||
### Team Collaboration
|
||||
- Shared plugins via marketplaces
|
||||
- Project-level configuration
|
||||
- Team memory files (CLAUDE.md)
|
||||
- Standardized workflows
|
||||
|
||||
### Security & Compliance
|
||||
- Permission controls
|
||||
- File access restrictions
|
||||
- Audit logging via OpenTelemetry
|
||||
- Sandbox execution mode
|
||||
|
||||
### Cost Management
|
||||
- Usage monitoring
|
||||
- Cost tracking by user/team
|
||||
- Budget alerts
|
||||
- ROI measurement tools
|
||||
|
||||
### Deployment Options
|
||||
- Direct API access
|
||||
- AWS Bedrock integration
|
||||
- Google Vertex AI integration
|
||||
- On-premises support (coming soon)
|
||||
|
||||
## What's Next?
|
||||
|
||||
- Explore **quickstart guide** for hands-on tutorial
|
||||
- Learn about **slash commands** for custom workflows
|
||||
- Set up **subagents** for specialized tasks
|
||||
- Configure **hooks** for automation
|
||||
- Install **plugins** from the marketplace
|
||||
- Join the **community** on GitHub
|
||||
214
skills/plugins/SKILL.md
Normal file
214
skills/plugins/SKILL.md
Normal file
@@ -0,0 +1,214 @@
|
||||
---
|
||||
name: plugins
|
||||
description: How to create, install, and manage Claude Code plugins and plugin marketplaces. Use when user asks about plugins, plugin creation, plugin distribution, or plugin marketplaces.
|
||||
---
|
||||
|
||||
# Claude Code Plugins
|
||||
|
||||
## Overview
|
||||
|
||||
Plugins extend Claude Code with custom functionality including commands, agents, hooks, Skills, and MCP servers. They can be shared across projects and teams through marketplaces.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Basic Structure
|
||||
A plugin requires:
|
||||
- **Plugin manifest** (`.claude-plugin/plugin.json`) - metadata
|
||||
- **Commands directory** (`commands/`) - custom slash commands
|
||||
- **Optional components** - agents, skills, hooks, MCP servers
|
||||
|
||||
### Creating Your First Plugin
|
||||
|
||||
1. **Setup directories**
|
||||
```bash
|
||||
mkdir test-marketplace/my-first-plugin
|
||||
cd my-first-plugin
|
||||
mkdir .claude-plugin commands
|
||||
```
|
||||
|
||||
2. **Create plugin manifest** (`.claude-plugin/plugin.json`)
|
||||
```json
|
||||
{
|
||||
"name": "my-first-plugin",
|
||||
"description": "A simple greeting plugin",
|
||||
"version": "1.0.0",
|
||||
"author": {"name": "Your Name"}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Add command** (`commands/hello.md`)
|
||||
Contains: "Greet the user warmly and ask how you can help them today."
|
||||
|
||||
4. **Create marketplace manifest** (`.claude-plugin/marketplace.json`)
|
||||
Lists your plugins with their source paths and descriptions.
|
||||
|
||||
5. **Install locally**
|
||||
```
|
||||
/plugin marketplace add ./test-marketplace
|
||||
/plugin install my-first-plugin@test-marketplace
|
||||
```
|
||||
|
||||
## Plugin Components
|
||||
|
||||
### Commands
|
||||
Markdown files in `commands/` directory defining custom slash commands that Claude can invoke.
|
||||
|
||||
### Agents
|
||||
Agent definitions in `agents/` directory for specialized task automation.
|
||||
|
||||
### Skills
|
||||
`SKILL.md` files in `skills/` directory that extend Claude's autonomous capabilities. Model-invoked based on task context.
|
||||
|
||||
### Hooks
|
||||
`hooks.json` for event handling and workflow automation.
|
||||
|
||||
### MCP Servers
|
||||
`.mcp.json` configuration for external tool integration.
|
||||
|
||||
## Managing Plugins
|
||||
|
||||
**Add marketplace**: `/plugin marketplace add your-org/claude-plugins`
|
||||
|
||||
**Browse/install**: `/plugin` opens interactive menu
|
||||
|
||||
**Direct install**: `/plugin install formatter@org-name`
|
||||
|
||||
**Control**: Enable, disable, or uninstall plugins as needed
|
||||
|
||||
**Verify**: Run `/help` to see newly available commands
|
||||
|
||||
## Team Setup
|
||||
|
||||
Configure plugins at repository level via `.claude/settings.json`. When team members trust the folder, marketplaces and plugins install automatically.
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. Create local development marketplace
|
||||
2. Organize plugins in subdirectories
|
||||
3. Test changes iteratively
|
||||
4. Uninstall and reinstall to verify updates
|
||||
5. Document with README and semantic versioning
|
||||
|
||||
## Distribution
|
||||
|
||||
- Add comprehensive documentation
|
||||
- Use semantic versioning in `plugin.json`
|
||||
- Create or use existing marketplaces
|
||||
- Test with team members before wider release
|
||||
|
||||
## Plugin Marketplaces
|
||||
|
||||
Plugin marketplaces are JSON-based catalogs that distribute Claude Code extensions. They enable centralized discovery, version management, and team distribution of plugins across multiple sources.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Centralized discovery**: Browse plugins from multiple sources in one location
|
||||
- **Version management**: Track and automatically update plugin versions
|
||||
- **Team distribution**: Share required plugins across organizations
|
||||
- **Flexible sources**: Support git repositories, GitHub repos, local paths, and package managers
|
||||
|
||||
### Adding Marketplaces
|
||||
|
||||
**GitHub Repositories:**
|
||||
```
|
||||
/plugin marketplace add owner/repo
|
||||
```
|
||||
|
||||
**Git Repositories:**
|
||||
```
|
||||
/plugin marketplace add https://gitlab.com/company/plugins.git
|
||||
```
|
||||
|
||||
**Local Development:**
|
||||
```
|
||||
/plugin marketplace add ./my-marketplace
|
||||
/plugin marketplace add ./path/to/marketplace.json
|
||||
/plugin marketplace add https://url.of/marketplace.json
|
||||
```
|
||||
|
||||
### Creating a Marketplace
|
||||
|
||||
Create `.claude-plugin/marketplace.json` in your repository:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "company-tools",
|
||||
"owner": {
|
||||
"name": "DevTools Team",
|
||||
"email": "[email protected]"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "code-formatter",
|
||||
"source": "./plugins/formatter",
|
||||
"description": "Automatic code formatting on save",
|
||||
"version": "2.1.0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Plugin Sources
|
||||
|
||||
**Relative Paths:**
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"source": "./plugins/my-plugin"
|
||||
}
|
||||
```
|
||||
|
||||
**GitHub:**
|
||||
```json
|
||||
{
|
||||
"name": "github-plugin",
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "owner/plugin-repo"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Git Services:**
|
||||
```json
|
||||
{
|
||||
"name": "git-plugin",
|
||||
"source": {
|
||||
"source": "url",
|
||||
"url": "https://gitlab.com/team/plugin.git"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Team Configuration
|
||||
|
||||
Specify marketplaces in `.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"extraKnownMarketplaces": {
|
||||
"team-tools": {
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "your-org/claude-plugins"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Management Commands
|
||||
|
||||
```
|
||||
/plugin marketplace list # Show all marketplaces
|
||||
/plugin marketplace update name # Refresh metadata
|
||||
/plugin marketplace remove name # Remove marketplace
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Establish clear versioning policies
|
||||
- Provide comprehensive README documentation
|
||||
- Maintain active community engagement
|
||||
- Review plugins for security before distribution
|
||||
- Document all marketplace contents
|
||||
114
skills/slash-commands/SKILL.md
Normal file
114
skills/slash-commands/SKILL.md
Normal file
@@ -0,0 +1,114 @@
|
||||
---
|
||||
name: slash-commands
|
||||
description: How to create, use, and manage custom slash commands in Claude Code. Use when user asks about creating custom commands, command arguments, command organization, or slash command features.
|
||||
---
|
||||
|
||||
# Slash Commands
|
||||
|
||||
## Overview
|
||||
|
||||
Slash commands control Claude's behavior during interactive sessions. They're organized into built-in commands, custom commands defined by users, plugin commands, and MCP-exposed prompts.
|
||||
|
||||
## Built-in Commands
|
||||
|
||||
Key built-in commands include:
|
||||
|
||||
- `/help` - Get usage help
|
||||
- `/clear` - Clear conversation history
|
||||
- `/model` - Select or change the AI model
|
||||
- `/cost` - Show token usage statistics
|
||||
- `/memory` - Edit CLAUDE.md memory files
|
||||
- `/sandbox` - Enable sandboxed bash execution
|
||||
- `/rewind` - Rewind conversation and/or code
|
||||
- `/mcp` - Manage MCP server connections
|
||||
|
||||
## Custom Slash Commands
|
||||
|
||||
### File Organization
|
||||
|
||||
Custom commands are Markdown files stored in two locations:
|
||||
|
||||
- **Project commands**: `.claude/commands/` (shared with team via git)
|
||||
- **Personal commands**: `~/.claude/commands/` (user-level only)
|
||||
|
||||
### Basic Syntax
|
||||
|
||||
```
|
||||
/<command-name> [arguments]
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
Commands support two argument styles:
|
||||
|
||||
**Capture all arguments:**
|
||||
```markdown
|
||||
Fix issue #$ARGUMENTS following coding standards
|
||||
```
|
||||
|
||||
**Individual positional arguments:**
|
||||
```markdown
|
||||
Review PR #$1 with priority $2 and assign to $3
|
||||
```
|
||||
|
||||
### Features
|
||||
|
||||
**Namespacing**: Organize commands in subdirectories. A file at `.claude/commands/frontend/component.md` creates `/component` with description "(project:frontend)".
|
||||
|
||||
**Bash execution**: Prefix commands with `!` to execute bash and include output:
|
||||
```markdown
|
||||
---
|
||||
allowed-tools: Bash(git status:*), Bash(git add:*)
|
||||
---
|
||||
Current git status: ![git status]
|
||||
```
|
||||
|
||||
Note: Replace `[git status]` with the actual command in backticks when creating your slash command.
|
||||
|
||||
**File references**: Use `@` prefix to include file contents in commands:
|
||||
```markdown
|
||||
Review the implementation in @src/utils/helpers.js
|
||||
```
|
||||
|
||||
**Frontmatter metadata**:
|
||||
```markdown
|
||||
---
|
||||
description: Brief command description
|
||||
allowed-tools: Tool specifications
|
||||
argument-hint: [expected-args]
|
||||
model: specific-model-id
|
||||
---
|
||||
```
|
||||
|
||||
## Plugin Commands
|
||||
|
||||
Plugins distribute custom slash commands automatically. They use the format `/plugin-name:command-name` when disambiguation is needed, support all standard features (arguments, bash execution, file references), and appear in `/help` when installed.
|
||||
|
||||
## MCP Slash Commands
|
||||
|
||||
MCP servers expose prompts as commands with the pattern:
|
||||
|
||||
```
|
||||
/mcp__<server-name>__<prompt-name> [arguments]
|
||||
```
|
||||
|
||||
These are dynamically discovered from connected MCP servers and automatically available when the server is active.
|
||||
|
||||
## SlashCommand Tool
|
||||
|
||||
The `SlashCommand` tool allows Claude to invoke custom commands programmatically during conversations. To encourage usage, reference commands in your instructions with their slash prefix (e.g., "Run `/write-unit-test`").
|
||||
|
||||
**Limitations**: Only supports user-defined custom commands with a `description` field populated in frontmatter. Built-in commands like `/compact` cannot be invoked via the tool.
|
||||
|
||||
**Management**:
|
||||
- Disable all: `/permissions` then add `SlashCommand` to deny rules
|
||||
- Disable specific commands: Add `disable-model-invocation: true` to frontmatter
|
||||
- Permission syntax: `SlashCommand:/commit` (exact match) or `SlashCommand:/review-pr:*` (prefix match)
|
||||
|
||||
## Skills vs Slash Commands
|
||||
|
||||
**Use slash commands for**: Simple, frequently-used prompts that fit in one file.
|
||||
|
||||
**Use Skills for**: Complex capabilities requiring multiple files, scripts, or organizational structure.
|
||||
|
||||
Key difference: Commands require explicit invocation; Skills are discovered automatically based on context.
|
||||
172
skills/sub-agents/SKILL.md
Normal file
172
skills/sub-agents/SKILL.md
Normal file
@@ -0,0 +1,172 @@
|
||||
---
|
||||
name: sub-agents
|
||||
description: How to create and use specialized subagents in Claude Code for task delegation. Use when user asks about creating specialized agents, delegating tasks, agent configuration, or subagent features.
|
||||
---
|
||||
|
||||
# Subagents
|
||||
|
||||
## Overview
|
||||
Subagents are specialized AI assistants that Claude Code can delegate tasks to. Each operates with its own context window, custom system prompt, and configurable tool access.
|
||||
|
||||
## Key Features
|
||||
|
||||
**Context Management**: Each subagent operates in its own context, preventing pollution of the main conversation
|
||||
|
||||
**Specialization**: Task-specific configurations enable higher success rates on designated work
|
||||
|
||||
**Reusability**: Once created, subagents work across different projects and teams
|
||||
|
||||
**Flexible Permissions**: Individual tool access control per subagent
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Run `/agents` command
|
||||
2. Select "Create New Agent"
|
||||
3. Choose project-level or user-level scope
|
||||
4. Define purpose, select tools, customize system prompt
|
||||
5. Save and invoke automatically or explicitly
|
||||
|
||||
## Configuration
|
||||
|
||||
### File Locations
|
||||
- **Project subagents**: `.claude/agents/`
|
||||
- **User subagents**: `~/.claude/agents/`
|
||||
- Project-level takes precedence over user-level
|
||||
|
||||
### File Format
|
||||
Markdown with YAML frontmatter containing:
|
||||
- `name`: Unique identifier
|
||||
- `description`: Purpose and invocation guidance
|
||||
- `tools`: Optional comma-separated list
|
||||
- `model`: Optional model alias (sonnet/opus/haiku) or 'inherit'
|
||||
|
||||
### Example Structure
|
||||
```yaml
|
||||
---
|
||||
name: code-reviewer
|
||||
description: Expert code review specialist. Use proactively after code changes.
|
||||
tools: Read, Grep, Glob, Bash
|
||||
model: inherit
|
||||
---
|
||||
|
||||
Your system prompt explaining the subagent's role and approach...
|
||||
```
|
||||
|
||||
## Available Tools
|
||||
|
||||
When configuring subagents, you can grant access to these tools via the `tools` field in frontmatter:
|
||||
|
||||
### Tools That Require Permission
|
||||
|
||||
**Bash** - Executes shell commands in your environment
|
||||
- Use for: Running tests, git commands, build scripts
|
||||
- Example: `Bash`
|
||||
|
||||
**Edit** - Makes targeted edits to specific files
|
||||
- Use for: Code modifications, refactoring
|
||||
- Example: `Edit`
|
||||
|
||||
**NotebookEdit** - Modifies Jupyter notebook cells
|
||||
- Use for: Data science workflows, notebook updates
|
||||
- Example: `NotebookEdit`
|
||||
|
||||
**SlashCommand** - Runs a custom slash command
|
||||
- Use for: Invoking user-defined commands
|
||||
- Example: `SlashCommand`
|
||||
|
||||
**WebFetch** - Fetches content from a specified URL
|
||||
- Use for: Documentation lookup, API calls
|
||||
- Example: `WebFetch`
|
||||
|
||||
**WebSearch** - Performs web searches with domain filtering
|
||||
- Use for: Finding current information, research
|
||||
- Example: `WebSearch`
|
||||
|
||||
**Write** - Creates or overwrites files
|
||||
- Use for: Generating new files, reports
|
||||
- Example: `Write`
|
||||
|
||||
### Tools That Don't Require Permission
|
||||
|
||||
**Glob** - Finds files based on pattern matching
|
||||
- Use for: Finding files by name pattern
|
||||
- Example: `Glob`
|
||||
|
||||
**Grep** - Searches for patterns in file contents
|
||||
- Use for: Code search, pattern matching
|
||||
- Example: `Grep`
|
||||
|
||||
**NotebookRead** - Reads and displays Jupyter notebook contents
|
||||
- Use for: Analyzing notebooks
|
||||
- Example: `NotebookRead`
|
||||
|
||||
**Read** - Reads the contents of files
|
||||
- Use for: Code review, analysis
|
||||
- Example: `Read`
|
||||
|
||||
**Task** - Runs a sub-agent to handle complex, multi-step tasks
|
||||
- Use for: Delegating to other specialized agents
|
||||
- Example: `Task`
|
||||
|
||||
**TodoWrite** - Creates and manages structured task lists
|
||||
- Use for: Planning and tracking work
|
||||
- Example: `TodoWrite`
|
||||
|
||||
### Configuring Tool Access
|
||||
|
||||
**Grant all tools:**
|
||||
```yaml
|
||||
tools: Bash, Edit, Read, Write, Glob, Grep, WebFetch, WebSearch
|
||||
```
|
||||
|
||||
**Grant minimal tools (read-only):**
|
||||
```yaml
|
||||
tools: Read, Glob, Grep
|
||||
```
|
||||
|
||||
**Grant specific tools for specialized tasks:**
|
||||
```yaml
|
||||
tools: Read, Bash, TodoWrite # For a test runner agent
|
||||
```
|
||||
|
||||
**Omit tools field to inherit from parent:**
|
||||
```yaml
|
||||
# No tools field - uses same tools as main Claude instance
|
||||
```
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
**Automatic Delegation**: Claude recognizes matching tasks and invokes appropriate subagents
|
||||
|
||||
**Explicit Invocation**: Request specific subagents via natural language commands like "Use the debugger subagent to investigate this error"
|
||||
|
||||
## Example Subagents
|
||||
|
||||
### Code Reviewer
|
||||
Reviews code for quality, security, and maintainability. Provides feedback categorized by priority (critical/warnings/suggestions).
|
||||
|
||||
### Debugger
|
||||
Specializes in root cause analysis. Captures error messages, isolates failures, and implements minimal fixes.
|
||||
|
||||
### Data Scientist
|
||||
Handles SQL queries and data analysis. Writes optimized queries and provides data-driven recommendations.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Generate initial subagents with Claude, then customize
|
||||
- Design focused subagents with single responsibilities
|
||||
- Write detailed system prompts with specific instructions
|
||||
- Limit tool access to necessary functions only
|
||||
- Version control project-level subagents
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
**Chaining**: Combine multiple subagents for complex workflows
|
||||
|
||||
**Dynamic Selection**: Claude intelligently chooses subagents based on task context and description fields
|
||||
|
||||
**Performance**: Subagents preserve main context but may add latency during initial context gathering
|
||||
|
||||
## CLI Configuration
|
||||
|
||||
Define subagents dynamically with `--agents` flag accepting JSON objects for session-specific or automation-based configurations.
|
||||
213
skills/troubleshooting/SKILL.md
Normal file
213
skills/troubleshooting/SKILL.md
Normal file
@@ -0,0 +1,213 @@
|
||||
---
|
||||
name: troubleshooting
|
||||
description: Common issues and solutions for Claude Code installation, authentication, performance, and IDE integration. Use when user encounters errors, problems, or asks about debugging.
|
||||
---
|
||||
|
||||
# Claude Code Troubleshooting
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### Windows WSL Problems
|
||||
|
||||
**OS/platform detection issues:**
|
||||
May require running `npm config set os linux` before installation.
|
||||
|
||||
**Node.js path conflicts:**
|
||||
WSL may use Windows npm instead of Linux versions.
|
||||
- Check with `which npm` and `which node`
|
||||
- Identify whether Linux or Windows paths are active
|
||||
- nvm version conflicts can be resolved by ensuring nvm loads in shell configuration files
|
||||
|
||||
**Recommended Solution:**
|
||||
Use the native Claude Code installer as an alternative to npm:
|
||||
```bash
|
||||
curl -fsSL https://claude.ai/install.sh | bash
|
||||
```
|
||||
|
||||
### Linux/Mac Permission Errors
|
||||
|
||||
**Native installer (recommended):**
|
||||
```bash
|
||||
curl -fsSL https://claude.ai/install.sh | bash
|
||||
```
|
||||
|
||||
**Migration from npm:**
|
||||
Migrate to local installation to avoid future permission issues:
|
||||
```bash
|
||||
claude migrate-installer
|
||||
```
|
||||
|
||||
## Authentication & Permissions
|
||||
|
||||
### Reset Authentication
|
||||
|
||||
Run `/logout` and restart Claude Code to reset authentication.
|
||||
|
||||
For persistent issues, remove stored auth data:
|
||||
```bash
|
||||
rm -rf ~/.config/claude-code/auth.json
|
||||
```
|
||||
|
||||
### Manage Permissions
|
||||
|
||||
Use `/permissions` to allow specific tools without repeated approval prompts.
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Reduce Context Size
|
||||
|
||||
Use `/compact` regularly to reduce context size for large codebases.
|
||||
|
||||
### Cancel Unresponsive Operations
|
||||
|
||||
Press `Ctrl+C` to cancel unresponsive operations.
|
||||
|
||||
### Fix Search Functionality
|
||||
|
||||
Install system `ripgrep` to fix search functionality:
|
||||
```bash
|
||||
# macOS
|
||||
brew install ripgrep
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt install ripgrep
|
||||
|
||||
# Fedora
|
||||
sudo dnf install ripgrep
|
||||
```
|
||||
|
||||
## IDE Integration Issues
|
||||
|
||||
### JetBrains on WSL2
|
||||
|
||||
**Firewall Issues:**
|
||||
Configure Windows Firewall or enable mirrored networking mode.
|
||||
|
||||
Add to `.wslconfig`:
|
||||
```ini
|
||||
[wsl2]
|
||||
networkingMode=mirrored
|
||||
```
|
||||
|
||||
### ESC Key Not Working (JetBrains)
|
||||
|
||||
Go to Settings → Tools → Terminal and disable "Move focus to the editor with Escape."
|
||||
|
||||
Or delete the "Switch focus to Editor" shortcut.
|
||||
|
||||
## Markdown Issues
|
||||
|
||||
### Missing Language Tags
|
||||
|
||||
Request language tags explicitly:
|
||||
```
|
||||
"Add appropriate language tags to all code blocks."
|
||||
```
|
||||
|
||||
### Automatic Formatting
|
||||
|
||||
Use formatting hooks for automatic post-processing validation.
|
||||
|
||||
## Common Error Messages
|
||||
|
||||
### "Command not found: claude"
|
||||
|
||||
**Solution:**
|
||||
1. Verify installation: `npm list -g @anthropic-ai/claude-code`
|
||||
2. Check PATH includes npm global bin directory
|
||||
3. Restart terminal
|
||||
4. Reinstall if necessary
|
||||
|
||||
### "Authentication failed"
|
||||
|
||||
**Solution:**
|
||||
1. Run `/logout` then `/login`
|
||||
2. Verify API key is valid
|
||||
3. Check network connectivity
|
||||
4. Remove auth file: `rm -rf ~/.config/claude-code/auth.json`
|
||||
|
||||
### "Permission denied"
|
||||
|
||||
**Solution:**
|
||||
1. Check file permissions in project directory
|
||||
2. Verify user has write access
|
||||
3. Use `/permissions` to configure allowed operations
|
||||
4. Check settings.json for overly restrictive deny rules
|
||||
|
||||
### "Context too large"
|
||||
|
||||
**Solution:**
|
||||
1. Run `/compact` to reduce context
|
||||
2. Be more specific in queries
|
||||
3. Use subagents for isolated tasks
|
||||
4. Clear conversation with `/clear`
|
||||
|
||||
### "Rate limit exceeded"
|
||||
|
||||
**Solution:**
|
||||
1. Wait before retrying
|
||||
2. Check API usage limits
|
||||
3. Use `--max-turns` to limit operations
|
||||
4. Implement delays in automation scripts
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Built-in Diagnostics
|
||||
|
||||
**Report bugs:**
|
||||
```
|
||||
/bug
|
||||
```
|
||||
|
||||
**Check installation health:**
|
||||
```
|
||||
/doctor
|
||||
```
|
||||
|
||||
### External Resources
|
||||
|
||||
- **GitHub Issues**: https://github.com/anthropics/claude-code/issues
|
||||
- **Documentation**: https://docs.claude.com/en/docs/claude-code
|
||||
- **Community Support**: Check GitHub Discussions
|
||||
|
||||
## Debug Mode
|
||||
|
||||
Enable verbose logging:
|
||||
```bash
|
||||
claude --debug
|
||||
claude --verbose
|
||||
```
|
||||
|
||||
View detailed output:
|
||||
```bash
|
||||
claude --output-format json
|
||||
```
|
||||
|
||||
## Reinstallation
|
||||
|
||||
If all else fails, completely reinstall:
|
||||
|
||||
```bash
|
||||
# Uninstall
|
||||
npm uninstall -g @anthropic-ai/claude-code
|
||||
|
||||
# Clear cache
|
||||
rm -rf ~/.config/claude-code
|
||||
rm -rf ~/.claude
|
||||
|
||||
# Reinstall
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
|
||||
# Or use native installer
|
||||
curl -fsSL https://claude.ai/install.sh | bash
|
||||
```
|
||||
|
||||
## Prevention Tips
|
||||
|
||||
1. Keep Claude Code updated: `claude update`
|
||||
2. Regularly run `/compact` for large projects
|
||||
3. Use specific queries rather than vague requests
|
||||
4. Configure permissions appropriately
|
||||
5. Monitor API usage and costs
|
||||
6. Use version control for important changes
|
||||
7. Enable checkpointing for easy recovery
|
||||
Reference in New Issue
Block a user