updated readme
This commit is contained in:
Shayan Rais
@@ -85,11 +85,11 @@ These items were identified during the 2.1.0–2.1.49 audit but belong in other
|
||||
|
||||
| Item | Reason | Where It Belongs |
|
||||
|------|--------|-----------------|
|
||||
| Skill `user-invocable` field | Skill-specific frontmatter | [claude-skills-frontmatter.md](claude-skills-frontmatter.md) |
|
||||
| Skill `${CLAUDE_SESSION_ID}` variable | Skill-specific template variable | [claude-skills-frontmatter.md](claude-skills-frontmatter.md) |
|
||||
| Skill `user-invocable` field | Skill-specific frontmatter | [claude-skills-frontmatter.md](../best-practice/claude-skills-frontmatter.md) |
|
||||
| Skill `${CLAUDE_SESSION_ID}` variable | Skill-specific template variable | [claude-skills-frontmatter.md](../best-practice/claude-skills-frontmatter.md) |
|
||||
| Agent `memory` frontmatter | Already covered in depth | [claude-agent-memory.md](../claude-agent-memory.md) |
|
||||
| claude.ai MCP connectors | Product feature, not settings | N/A |
|
||||
| `chat:newline` keybinding | Keybindings reference, not settings | [claude-commands.md](claude-commands.md) (Keyboard Shortcuts section) |
|
||||
| `chat:newline` keybinding | Keybindings reference, not settings | [claude-commands.md](../best-practice/claude-commands.md) (Keyboard Shortcuts section) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,244 +0,0 @@
|
||||
# Claude Code Commands Reference
|
||||
|
||||
A comprehensive reference of all available slash commands in Claude Code's interactive mode.
|
||||
|
||||
<table width="100%">
|
||||
<tr>
|
||||
<td><a href="../">← Back to Claude Code Best Practice</a></td>
|
||||
<td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Session Management](#session-management)
|
||||
2. [Context & Cost](#context--cost)
|
||||
3. [Model & Planning](#model--planning)
|
||||
4. [Project & Memory](#project--memory)
|
||||
5. [Configuration](#configuration)
|
||||
6. [Extensions & Integrations](#extensions--integrations)
|
||||
7. [Diagnostics & Debugging](#diagnostics--debugging)
|
||||
8. [Import / Export](#import--export)
|
||||
9. [Authentication](#authentication)
|
||||
10. [Input Modes & Prefixes](#input-modes--prefixes)
|
||||
11. [Dynamic Commands](#dynamic-commands)
|
||||
12. [CLI Flags](#cli-flags)
|
||||
13. [Keyboard Shortcuts](#keyboard-shortcuts)
|
||||
|
||||
---
|
||||
|
||||
## Session Management
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/clear` | Clear conversation history and start fresh |
|
||||
| `/compact [instructions]` | Compress conversation to free context window. Optional instructions focus the compaction on specific topics |
|
||||
| `/rename <name>` | Rename the current session for easier identification |
|
||||
| `/resume [session]` | Resume a previous conversation by ID or name, or open the session picker |
|
||||
| `/rewind` | Rewind the conversation and/or code to an earlier point, or summarize from a selected message |
|
||||
| `/fork` | Fork the current conversation into a new session |
|
||||
| `/teleport` | Resume a remote session from claude.ai (subscribers only) |
|
||||
| `/exit` | Exit the REPL |
|
||||
|
||||
---
|
||||
|
||||
## Context & Cost
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/context` | Visualize current context usage as a colored grid with token counts and percentages |
|
||||
| `/cost` | Show token usage statistics and spending for the current session |
|
||||
| `/usage` | Show plan usage limits and rate limit status (subscription plans only) |
|
||||
| `/stats` | Visualize daily usage, session history, streaks, and model preferences. Supports date range filtering |
|
||||
|
||||
---
|
||||
|
||||
## Model & Planning
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/model` | Switch models (haiku, sonnet, opus) and adjust Opus 4.6 effort level with arrow keys |
|
||||
| `/plan` | Enter read-only planning mode where Claude suggests approaches without making changes |
|
||||
| `/fast` | Toggle fast mode — same Opus 4.6 model with faster output |
|
||||
|
||||
---
|
||||
|
||||
## Project & Memory
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/init` | Initialize a new project with CLAUDE.md guide |
|
||||
| `/memory` | View and edit CLAUDE.md memory files (user, project, and local scope) |
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/config` | Open the interactive Settings interface with search functionality |
|
||||
| `/permissions` | View or update tool permissions |
|
||||
| `/theme` | Change the color theme |
|
||||
| `/vim` | Enable vim-style editing mode |
|
||||
| `/terminal-setup` | Enable shift+enter for newlines in IDE terminals, Apple Terminal, Warp, and Alacritty |
|
||||
| `/keybindings` | Customize keyboard shortcuts per context, create chord sequences |
|
||||
| `/statusline` | Set up Claude Code's status line UI |
|
||||
| `/sandbox` | Configure sandboxing with dependency status |
|
||||
|
||||
---
|
||||
|
||||
## Extensions & Integrations
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/agents` | Manage custom subagents — view, create, edit, delete |
|
||||
| `/skills` | View available skills and their descriptions |
|
||||
| `/hooks` | Interactive interface to manage hooks |
|
||||
| `/mcp` | Manage MCP server connections — add, enable, list, get info, OAuth authentication |
|
||||
| `/plugin` | Manage plugins — install, uninstall, enable, disable, browse marketplaces |
|
||||
| `/ide` | Connect to IDE integration |
|
||||
|
||||
---
|
||||
|
||||
## Diagnostics & Debugging
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/doctor` | Check the health of your Claude Code installation. Detects unreachable permissions, config issues, and updates |
|
||||
| `/debug [description]` | Troubleshoot the current session by reading the session debug log |
|
||||
| `/tasks` | List and manage background tasks |
|
||||
| `/todos` | List current TODO items |
|
||||
| `/help` | Show all available slash commands and usage help |
|
||||
| `/feedback` | Generate a GitHub issue URL for reporting bugs or feedback |
|
||||
|
||||
---
|
||||
|
||||
## Import / Export
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/copy` | Copy the last assistant response to clipboard |
|
||||
| `/export [filename]` | Export the current conversation to a file or clipboard |
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/login` | Authenticate with Claude Code via OAuth |
|
||||
| `/logout` | Log out from Claude Code |
|
||||
|
||||
---
|
||||
|
||||
## Input Modes & Prefixes
|
||||
|
||||
These are special prefixes you can type at the prompt, not slash commands per se:
|
||||
|
||||
| Prefix | Description |
|
||||
|--------|-------------|
|
||||
| `/` | Trigger command or skill autocomplete |
|
||||
| `!` | Bash mode — run shell commands directly and add output to conversation |
|
||||
| `@` | File path mention — trigger file path autocomplete for context |
|
||||
|
||||
---
|
||||
|
||||
## Dynamic Commands
|
||||
|
||||
These commands are not built-in but are discovered at runtime from your configuration:
|
||||
|
||||
### MCP Prompts
|
||||
|
||||
MCP servers can expose prompts that appear as commands:
|
||||
|
||||
```
|
||||
/mcp__<server-name>__<prompt-name>
|
||||
```
|
||||
|
||||
### Plugin Commands
|
||||
|
||||
Installed plugins can provide their own commands, namespaced by plugin name:
|
||||
|
||||
```
|
||||
/plugin-name:command-name
|
||||
```
|
||||
|
||||
### Custom Skills
|
||||
|
||||
Skills defined in `.claude/skills/` appear as invocable commands:
|
||||
|
||||
```
|
||||
/skill-name
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CLI Flags
|
||||
|
||||
These flags are used when launching Claude Code from the terminal, not as interactive commands:
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--doctor` | Run diagnostics from the command line |
|
||||
| `--debug` | Launch in debug mode with hook execution details |
|
||||
| `--resume` | Resume most recent session |
|
||||
| `--plan` | Start in plan mode |
|
||||
| `--init` | Initialize repository with CLAUDE.md setup |
|
||||
| `--init-only` | Run repository initialization only, then exit |
|
||||
| `--maintenance` | Run repository maintenance operations |
|
||||
| `--from-pr <url>` | Resume a session linked to a specific GitHub PR |
|
||||
|
||||
---
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
### Navigation & Control
|
||||
|
||||
| Shortcut | Description |
|
||||
|----------|-------------|
|
||||
| `Ctrl+C` | Cancel current input or generation |
|
||||
| `Ctrl+D` | Exit Claude Code session |
|
||||
| `Ctrl+L` | Clear terminal screen |
|
||||
| `Ctrl+R` | Reverse search command history |
|
||||
| `Ctrl+O` | Toggle verbose output |
|
||||
| `Esc` + `Esc` | Rewind or summarize |
|
||||
|
||||
### Model & Mode Switching
|
||||
|
||||
| Shortcut | Description |
|
||||
|----------|-------------|
|
||||
| `Option+P` / `Alt+P` | Switch model |
|
||||
| `Option+T` / `Alt+T` | Toggle extended thinking |
|
||||
| `Shift+Tab` / `Alt+M` | Toggle permission modes |
|
||||
| `Ctrl+B` | Background running tasks |
|
||||
| `Ctrl+T` | Toggle task list |
|
||||
|
||||
### Text Editing
|
||||
|
||||
| Shortcut | Description |
|
||||
|----------|-------------|
|
||||
| `Ctrl+G` | Open prompt in default text editor |
|
||||
| `Ctrl+V` / `Cmd+V` | Paste image from clipboard |
|
||||
| `Ctrl+K` | Delete to end of line |
|
||||
| `Ctrl+U` | Delete entire line |
|
||||
| `Ctrl+Y` | Paste deleted text |
|
||||
| `Alt+Y` | Cycle paste history |
|
||||
|
||||
### Multiline Input
|
||||
|
||||
| Shortcut | Description |
|
||||
|----------|-------------|
|
||||
| `\` + `Enter` | Quick escape for multiline |
|
||||
| `Option+Enter` | macOS default multiline |
|
||||
| `Shift+Enter` | Multiline (iTerm2, WezTerm, Ghostty, Kitty) |
|
||||
| `Ctrl+J` | Line feed character for multiline |
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [Claude Code Interactive Mode](https://code.claude.com/docs/en/interactive-mode)
|
||||
- [Claude Code CLI Reference](https://code.claude.com/docs/en/cli-reference)
|
||||
- [Claude Code Slash Commands](https://code.claude.com/docs/en/slash-commands)
|
||||
- [Claude Code CHANGELOG](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
|
||||
- [Claude Code Common Workflows](https://code.claude.com/docs/en/common-workflows)
|
||||
@@ -1,809 +0,0 @@
|
||||
# Claude Code Settings Reference
|
||||
|
||||
A comprehensive guide to all available configuration options in Claude Code's `settings.json` files. As of February 2026, Claude Code exposes **38 settings** and **84 environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts).
|
||||
|
||||
<table width="100%">
|
||||
<tr>
|
||||
<td><a href="../">← Back to Claude Code Best Practice</a></td>
|
||||
<td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Settings Hierarchy](#settings-hierarchy)
|
||||
2. [Core Configuration](#core-configuration)
|
||||
3. [Permissions](#permissions)
|
||||
4. [Hooks](#hooks)
|
||||
5. [MCP Servers](#mcp-servers)
|
||||
6. [Sandbox](#sandbox)
|
||||
7. [Plugins](#plugins)
|
||||
8. [Model Configuration](#model-configuration)
|
||||
9. [Display & UX](#display--ux)
|
||||
10. [AWS & Cloud Credentials](#aws--cloud-credentials)
|
||||
11. [Environment Variables](#environment-variables-via-env)
|
||||
12. [Useful Commands](#useful-commands)
|
||||
|
||||
---
|
||||
|
||||
## Settings Hierarchy
|
||||
|
||||
Claude Code settings use a 5-level user-writable override chain plus an enforced policy layer:
|
||||
|
||||
| Priority | Location | Scope | Version Control | Purpose |
|
||||
|----------|----------|-------|-----------------|---------|
|
||||
| 1 | Command line arguments | Session | N/A | Single-session overrides |
|
||||
| 2 | `.claude/settings.local.json` | Project | No (git-ignored) | Personal project-specific |
|
||||
| 3 | `.claude/settings.json` | Project | Yes (committed) | Team-shared settings |
|
||||
| 4 | `~/.claude/settings.local.json` | User | N/A | Personal global overrides |
|
||||
| 5 | `~/.claude/settings.json` | User | N/A | Global personal defaults |
|
||||
|
||||
**Policy layer**: `managed-settings.json` is organization-enforced and cannot be overridden by local settings.
|
||||
|
||||
**Important**:
|
||||
- `deny` rules have highest safety precedence and cannot be overridden by lower-priority allow/ask rules.
|
||||
- Managed settings may lock or override local behavior even if local files specify different values.
|
||||
|
||||
---
|
||||
|
||||
## Core Configuration
|
||||
|
||||
### General Settings
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `model` | string | `"default"` | Override default model. Accepts aliases (`sonnet`, `opus`, `haiku`) or full model IDs |
|
||||
| `agent` | string | - | Set the default agent for the main conversation. Value is the agent name from `.claude/agents/`. Also available via `--agent` CLI flag |
|
||||
| `language` | string | `"english"` | Claude's preferred response language |
|
||||
| `cleanupPeriodDays` | number | `30` | Sessions inactive longer than this are deleted at startup |
|
||||
| `autoUpdatesChannel` | string | `"latest"` | Release channel: `"stable"` or `"latest"` |
|
||||
| `alwaysThinkingEnabled` | boolean | `false` | Enable extended thinking by default for all sessions |
|
||||
| `skipWebFetchPreflight` | boolean | `false` | Skip WebFetch blocklist check before fetching URLs |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"model": "opus",
|
||||
"agent": "code-reviewer",
|
||||
"language": "japanese",
|
||||
"cleanupPeriodDays": 60,
|
||||
"autoUpdatesChannel": "stable",
|
||||
"alwaysThinkingEnabled": true
|
||||
}
|
||||
```
|
||||
|
||||
### Plans Directory
|
||||
|
||||
Store plan files in a custom location relative to project root.
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `plansDirectory` | string | `.claude/plans/` | Directory where `/plan` outputs are stored |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"plansDirectory": "./my-plans"
|
||||
}
|
||||
```
|
||||
|
||||
**Use Case:** Useful for organizing planning artifacts separately from Claude's internal files, or for keeping plans in a shared team location.
|
||||
|
||||
### Attribution Settings
|
||||
|
||||
Customize attribution messages for git commits and pull requests.
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `attribution.commit` | string | Co-authored-by | Git commit attribution (supports trailers) |
|
||||
| `attribution.pr` | string | Generated message | Pull request description attribution |
|
||||
| `includeCoAuthoredBy` | boolean | `true` | **DEPRECATED** - Use `attribution` instead |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"attribution": {
|
||||
"commit": "Generated with AI\n\nCo-Authored-By: Claude <noreply@anthropic.com>",
|
||||
"pr": "Generated with Claude Code"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** Set to empty string (`""`) to hide attribution entirely.
|
||||
|
||||
### Authentication Helpers
|
||||
|
||||
Scripts for dynamic authentication token generation.
|
||||
|
||||
| Key | Type | Description |
|
||||
|-----|------|-------------|
|
||||
| `apiKeyHelper` | string | Shell script path that outputs auth token (sent as `X-Api-Key` header) |
|
||||
| `forceLoginMethod` | string | Restrict login to `"claudeai"` or `"console"` accounts |
|
||||
| `forceLoginOrgUUID` | string | UUID to automatically select organization during login |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"apiKeyHelper": "/bin/generate_temp_api_key.sh",
|
||||
"forceLoginMethod": "console",
|
||||
"forceLoginOrgUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
|
||||
}
|
||||
```
|
||||
|
||||
### Company Announcements
|
||||
|
||||
Display custom announcements to users at startup (cycled randomly).
|
||||
|
||||
| Key | Type | Description |
|
||||
|-----|------|-------------|
|
||||
| `companyAnnouncements` | array | Array of strings displayed at startup |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"companyAnnouncements": [
|
||||
"Welcome to Acme Corp!",
|
||||
"Remember to run tests before committing!",
|
||||
"Check the wiki for coding standards"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Permissions
|
||||
|
||||
Control what tools and operations Claude can perform.
|
||||
|
||||
### Permission Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [],
|
||||
"ask": [],
|
||||
"deny": [],
|
||||
"additionalDirectories": [],
|
||||
"defaultMode": "acceptEdits",
|
||||
"disableBypassPermissionsMode": "disable"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Permission Keys
|
||||
|
||||
| Key | Type | Description |
|
||||
|-----|------|-------------|
|
||||
| `permissions.allow` | array | Rules allowing tool use without prompting |
|
||||
| `permissions.ask` | array | Rules requiring user confirmation |
|
||||
| `permissions.deny` | array | Rules blocking tool use (highest precedence) |
|
||||
| `permissions.additionalDirectories` | array | Extra directories Claude can access |
|
||||
| `permissions.defaultMode` | string | Default permission mode |
|
||||
| `permissions.disableBypassPermissionsMode` | string | Prevent bypass mode activation |
|
||||
|
||||
### Permission Modes
|
||||
|
||||
| Mode | Behavior |
|
||||
|------|----------|
|
||||
| `"default"` | Standard permission checking with prompts |
|
||||
| `"acceptEdits"` | Auto-accept file edits without asking |
|
||||
| `"askEdits"` | Ask before every operation |
|
||||
| `"viewOnly"` | Read-only mode, no modifications |
|
||||
| `"bypassPermissions"` | Skip all permission checks (dangerous) |
|
||||
| `"plan"` | Read-only exploration mode |
|
||||
|
||||
### Tool Permission Syntax
|
||||
|
||||
| Tool | Syntax | Examples |
|
||||
|------|--------|----------|
|
||||
| `Bash` | `Bash(command pattern)` | `Bash(npm run *)`, `Bash(* install)`, `Bash(git * main)` |
|
||||
| `Read` | `Read(path pattern)` | `Read(.env)`, `Read(./secrets/**)` |
|
||||
| `Edit` | `Edit(path pattern)` | `Edit(src/**)`, `Edit(*.ts)` |
|
||||
| `Write` | `Write(path pattern)` | `Write(*.md)`, `Write(./docs/**)` |
|
||||
| `NotebookEdit` | `NotebookEdit(pattern)` | `NotebookEdit(*)` |
|
||||
| `WebFetch` | `WebFetch(domain:pattern)` | `WebFetch(domain:example.com)` |
|
||||
| `WebSearch` | `WebSearch` | Global web search |
|
||||
| `Task` | `Task(agent-name)` | `Task(Explore)`, `Task(my-agent)` |
|
||||
| `Skill` | `Skill(skill-name)` | `Skill(weather-fetcher)` |
|
||||
| `MCP` | `mcp__server__tool` | `mcp__memory__*`, `mcp__github__*` |
|
||||
|
||||
**Bash wildcard notes:**
|
||||
- `*` can appear at **any position**: prefix (`Bash(* install)`), suffix (`Bash(npm *)`), or middle (`Bash(git * main)`)
|
||||
- `Bash(*)` is treated as equivalent to `Bash` (matches all bash commands)
|
||||
- Permission rules support output redirections: `Bash(python:*)` matches `python script.py > output.txt`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Edit(*)",
|
||||
"Write(*)",
|
||||
"Bash(npm run *)",
|
||||
"Bash(git *)",
|
||||
"WebFetch(domain:*)",
|
||||
"mcp__*"
|
||||
],
|
||||
"ask": [
|
||||
"Bash(rm *)",
|
||||
"Bash(git push *)"
|
||||
],
|
||||
"deny": [
|
||||
"Read(.env)",
|
||||
"Read(./secrets/**)",
|
||||
"Bash(curl *)"
|
||||
],
|
||||
"additionalDirectories": ["../shared-libs/"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hooks
|
||||
|
||||
Execute custom shell commands at various points in Claude Code's lifecycle.
|
||||
|
||||
### Hook Events (16 total)
|
||||
|
||||
| Event | When Fired | Matcher Support | Common Use Cases |
|
||||
|-------|------------|-----------------|------------------|
|
||||
| `SessionStart` | New or resumed session | No | Load context, set environment |
|
||||
| `SessionEnd` | Session terminates | No | Cleanup, logging |
|
||||
| `UserPromptSubmit` | User submits prompt | No | Validate input, add context |
|
||||
| `PreToolUse` | Before tool execution | Yes | Validate commands, modify inputs |
|
||||
| `PostToolUse` | After tool succeeds | Yes | Run linters, verify output |
|
||||
| `PostToolUseFailure` | After tool fails | Yes | Log failures, recovery |
|
||||
| `PermissionRequest` | Permission dialog appears | Yes | Auto-approve/deny patterns |
|
||||
| `Notification` | Notification sent | Yes | Sound alerts, logging |
|
||||
| `Stop` | Claude finishes responding | No | Block/continue decisions |
|
||||
| `SubagentStart` | Subagent spawned | Yes | Per-agent setup |
|
||||
| `SubagentStop` | Subagent completes | Yes | Cleanup, validation |
|
||||
| `PreCompact` | Before context compaction | Yes | Backup, logging |
|
||||
| `Setup` | Repository init (`--init`, `--init-only`, `--maintenance`) | Yes | One-time setup |
|
||||
| `TeammateIdle` | Agent Teams teammate goes idle | Yes | Team orchestration, routing |
|
||||
| `TaskCompleted` | A tracked task is completed | Yes | Progress automation, notifications |
|
||||
| `ConfigChange` | Configuration files change during session | Yes | Enterprise security auditing, blocking settings changes |
|
||||
|
||||
### Hook Configuration Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"EventName": [
|
||||
{
|
||||
"matcher": "ToolPattern",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "script.sh",
|
||||
"timeout": 60000,
|
||||
"once": true
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"disableAllHooks": false,
|
||||
"allowManagedHooksOnly": false
|
||||
}
|
||||
```
|
||||
|
||||
### Hook Properties
|
||||
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `matcher` | string | Regex pattern to match tool/event (optional) |
|
||||
| `type` | string | `"command"` or `"prompt"` |
|
||||
| `command` | string | Shell command to execute (for `type: "command"`) |
|
||||
| `prompt` | string | LLM prompt for evaluation (for `type: "prompt"`) |
|
||||
| `timeout` | number | Timeout in milliseconds |
|
||||
| `once` | boolean | Run only once per session |
|
||||
| `model` | string | Custom model for prompt-based stop hooks (for `type: "prompt"`) |
|
||||
|
||||
### Hook Matcher Patterns
|
||||
|
||||
| Pattern | Matches |
|
||||
|---------|---------|
|
||||
| `"Bash"` | Exact match only |
|
||||
| `"Edit\|Write"` | Multiple tools with regex OR |
|
||||
| `"mcp__.*"` | All MCP tools |
|
||||
| `"mcp__memory__.*"` | Specific MCP server tools |
|
||||
| `"*"` or `""` | All tools |
|
||||
|
||||
### Hook Exit Codes
|
||||
|
||||
| Exit Code | Behavior |
|
||||
|-----------|----------|
|
||||
| `0` | Success, continue |
|
||||
| `1` | Error (logged, continues) |
|
||||
| `2` | Block the operation |
|
||||
|
||||
### Environment Variables in Hooks
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `${CLAUDE_PROJECT_DIR}` | Project root directory |
|
||||
| `CLAUDE_TOOL_NAME` | Current tool name |
|
||||
| `CLAUDE_TOOL_INPUT` | Tool input (JSON) |
|
||||
| `CLAUDE_TOOL_OUTPUT` | Tool output (PostToolUse only) |
|
||||
|
||||
**PreToolUse/PostToolUse Input Fields:**
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `tool_use_id` | Unique identifier for this specific tool invocation |
|
||||
|
||||
**Stop/SubagentStop Input Fields:**
|
||||
|
||||
The `Stop` and `SubagentStop` hooks receive additional fields in their JSON input:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `last_assistant_message` | The final assistant response text (avoids parsing transcript files) |
|
||||
| `agent_id` | Agent identifier (SubagentStop only) |
|
||||
| `agent_transcript_path` | Path to agent's transcript file (SubagentStop only) |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Bash",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/validate.py",
|
||||
"timeout": 5000
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"SessionStart": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'Session started!'",
|
||||
"timeout": 1000,
|
||||
"once": true
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"disableAllHooks": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Servers
|
||||
|
||||
Configure Model Context Protocol servers for extended capabilities.
|
||||
|
||||
### MCP Settings
|
||||
|
||||
| Key | Type | Scope | Description |
|
||||
|-----|------|-------|-------------|
|
||||
| `enableAllProjectMcpServers` | boolean | Any | Auto-approve all `.mcp.json` servers |
|
||||
| `enabledMcpjsonServers` | array | Any | Allowlist specific server names |
|
||||
| `disabledMcpjsonServers` | array | Any | Blocklist specific server names |
|
||||
| `allowedMcpServers` | array | Managed only | Allowlist with name/command/URL matching |
|
||||
| `deniedMcpServers` | array | Managed only | Blocklist with matching |
|
||||
|
||||
### MCP Server Matching (Managed Settings)
|
||||
|
||||
```json
|
||||
{
|
||||
"allowedMcpServers": [
|
||||
{ "serverName": "github" },
|
||||
{ "serverCommand": "npx @modelcontextprotocol/*" },
|
||||
{ "serverUrl": "https://mcp.company.com/*" }
|
||||
],
|
||||
"deniedMcpServers": [
|
||||
{ "serverName": "dangerous-server" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"enableAllProjectMcpServers": true,
|
||||
"enabledMcpjsonServers": ["memory", "github", "filesystem"],
|
||||
"disabledMcpjsonServers": ["experimental-server"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sandbox
|
||||
|
||||
Configure bash command sandboxing for security.
|
||||
|
||||
### Sandbox Settings
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `sandbox.enabled` | boolean | `false` | Enable bash sandboxing |
|
||||
| `sandbox.autoAllowBashIfSandboxed` | boolean | `true` | Auto-approve bash when sandboxed |
|
||||
| `sandbox.excludedCommands` | array | `[]` | Commands to run outside sandbox |
|
||||
| `sandbox.allowUnsandboxedCommands` | boolean | `true` | Allow `dangerouslyDisableSandbox` |
|
||||
| `sandbox.ignoreViolations` | object | `{}` | Map of command patterns to path arrays — suppress violation warnings |
|
||||
| `sandbox.enableWeakerNestedSandbox` | boolean | `false` | Weaker sandbox for Docker (reduces security) |
|
||||
| `sandbox.network.allowUnixSockets` | array | `[]` | Specific Unix socket paths accessible in sandbox |
|
||||
| `sandbox.network.allowAllUnixSockets` | boolean | `false` | Allow all Unix sockets (overrides allowUnixSockets) |
|
||||
| `sandbox.network.allowLocalBinding` | boolean | `false` | Allow binding to localhost ports (macOS) |
|
||||
| `sandbox.network.allowedDomains` | array | `[]` | Network domain allowlist for sandbox |
|
||||
| `sandbox.network.deniedDomains` | array | `[]` | Network domain denylist for sandbox |
|
||||
| `sandbox.network.httpProxyPort` | number | - | HTTP proxy port 1-65535 (custom proxy) |
|
||||
| `sandbox.network.socksProxyPort` | number | - | SOCKS5 proxy port 1-65535 (custom proxy) |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"sandbox": {
|
||||
"enabled": true,
|
||||
"autoAllowBashIfSandboxed": true,
|
||||
"excludedCommands": ["git", "docker", "gh"],
|
||||
"allowUnsandboxedCommands": false,
|
||||
"network": {
|
||||
"allowUnixSockets": ["/var/run/docker.sock"],
|
||||
"allowLocalBinding": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plugins
|
||||
|
||||
Configure Claude Code plugins and marketplaces.
|
||||
|
||||
### Plugin Settings
|
||||
|
||||
| Key | Type | Scope | Description |
|
||||
|-----|------|-------|-------------|
|
||||
| `enabledPlugins` | object | Any | Enable/disable specific plugins |
|
||||
| `extraKnownMarketplaces` | object | Any | Add custom plugin marketplaces |
|
||||
| `strictKnownMarketplaces` | array | Managed only | Allowlist of permitted marketplaces |
|
||||
| `skippedMarketplaces` | array | Any | Marketplaces user declined to install |
|
||||
| `skippedPlugins` | array | Any | Plugins user declined to install |
|
||||
| `pluginConfigs` | object | Any | Per-plugin MCP server configs (keyed by `plugin@marketplace`) |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"enabledPlugins": {
|
||||
"formatter@acme-tools": true,
|
||||
"deployer@acme-tools": true,
|
||||
"experimental@acme-tools": false
|
||||
},
|
||||
"extraKnownMarketplaces": {
|
||||
"acme-tools": {
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "acme-corp/claude-plugins"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Model Configuration
|
||||
|
||||
### Model Aliases
|
||||
|
||||
| Alias | Description |
|
||||
|-------|-------------|
|
||||
| `"default"` | Recommended for your account type |
|
||||
| `"sonnet"` | Latest Sonnet model (Claude Sonnet 4.6) |
|
||||
| `"opus"` | Latest Opus model (Claude Opus 4.6) |
|
||||
| `"haiku"` | Fast Haiku model |
|
||||
| `"sonnet[1m]"` | Sonnet with 1M token context |
|
||||
| `"opusplan"` | Opus for planning, Sonnet for execution |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"model": "opus"
|
||||
}
|
||||
```
|
||||
|
||||
### Effort Level (Opus 4.6)
|
||||
|
||||
When Opus 4.6 is selected, the `/model` command exposes an **effort level** control that adjusts how much reasoning the model applies per response. Use the ← → arrow keys in the `/model` UI to cycle through effort levels.
|
||||
|
||||
| Effort Level | Description |
|
||||
|-------------|-------------|
|
||||
| High (default) | Full reasoning depth, best for complex tasks |
|
||||
| Medium | Balanced reasoning, good for everyday tasks |
|
||||
| Low | Minimal reasoning, fastest responses |
|
||||
|
||||
**How to use:**
|
||||
1. Run `/model` in Claude Code
|
||||
2. Select **Default (recommended)** — Opus 4.6
|
||||
3. Use **← →** arrow keys to adjust the effort level
|
||||
4. The setting applies to the current session and future sessions
|
||||
|
||||
**Note:** Effort level is only available for Opus 4.6. Other models (Sonnet, Haiku) do not expose this control.
|
||||
|
||||
### Model Environment Variables
|
||||
|
||||
Configure via `env` key:
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_MODEL": "sonnet",
|
||||
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "custom-haiku-model",
|
||||
"ANTHROPIC_DEFAULT_SONNET_MODEL": "custom-sonnet-model",
|
||||
"ANTHROPIC_DEFAULT_OPUS_MODEL": "custom-opus-model",
|
||||
"CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
|
||||
"MAX_THINKING_TOKENS": "10000"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Display & UX
|
||||
|
||||
### Display Settings
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `statusLine` | object | - | Custom status line configuration |
|
||||
| `outputStyle` | string | `"default"` | Output style (e.g., `"Explanatory"`) |
|
||||
| `spinnerTipsEnabled` | boolean | `true` | Show tips while waiting |
|
||||
| `spinnerVerbs` | object | - | Custom spinner verbs with `mode` ("append" or "replace") and `verbs` array |
|
||||
| `spinnerTipsOverride` | object | - | Custom spinner tips with `tips` (string array) and optional `excludeDefault` (boolean) |
|
||||
| `terminalProgressBarEnabled` | boolean | `true` | Show progress bar in terminal |
|
||||
| `showTurnDuration` | boolean | `true` | Show turn duration messages |
|
||||
| `respectGitignore` | boolean | `true` | Respect .gitignore in file picker |
|
||||
|
||||
### Status Line Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"statusLine": {
|
||||
"type": "command",
|
||||
"command": "~/.claude/statusline.sh",
|
||||
"padding": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Status Line Input Fields:**
|
||||
|
||||
The status line command receives a JSON object on stdin with these notable fields:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `workspace.added_dirs` | Directories added via `/add-dir` |
|
||||
| `context_window.used_percentage` | Context window usage percentage |
|
||||
| `context_window.remaining_percentage` | Context window remaining percentage |
|
||||
| `current_usage` | Current context window token count |
|
||||
| `exceeds_200k_tokens` | Whether context exceeds 200k tokens |
|
||||
|
||||
### File Suggestion Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"fileSuggestion": {
|
||||
"type": "command",
|
||||
"command": "~/.claude/file-suggestion.sh"
|
||||
},
|
||||
"respectGitignore": true
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"statusLine": {
|
||||
"type": "command",
|
||||
"command": "git branch --show-current 2>/dev/null || echo 'no-branch'"
|
||||
},
|
||||
"spinnerTipsEnabled": true,
|
||||
"spinnerVerbs": {
|
||||
"mode": "replace",
|
||||
"verbs": ["Cooking", "Brewing", "Crafting", "Conjuring"]
|
||||
},
|
||||
"spinnerTipsOverride": {
|
||||
"tips": ["Use /compact at ~50% context", "Start with plan mode for complex tasks"],
|
||||
"excludeDefault": true
|
||||
},
|
||||
"terminalProgressBarEnabled": true,
|
||||
"showTurnDuration": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AWS & Cloud Credentials
|
||||
|
||||
### AWS Settings
|
||||
|
||||
| Key | Type | Description |
|
||||
|-----|------|-------------|
|
||||
| `awsAuthRefresh` | string | Script to refresh AWS auth (modifies `.aws` dir) |
|
||||
| `awsCredentialExport` | string | Script outputting JSON with AWS credentials |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"awsAuthRefresh": "aws sso login --profile myprofile",
|
||||
"awsCredentialExport": "/bin/generate_aws_grant.sh"
|
||||
}
|
||||
```
|
||||
|
||||
### OpenTelemetry
|
||||
|
||||
| Key | Type | Description |
|
||||
|-----|------|-------------|
|
||||
| `otelHeadersHelper` | string | Script to generate dynamic OpenTelemetry headers |
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"otelHeadersHelper": "/bin/generate_otel_headers.sh"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables (via `env`)
|
||||
|
||||
Set environment variables for all Claude Code sessions.
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_API_KEY": "...",
|
||||
"NODE_ENV": "development",
|
||||
"DEBUG": "true"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `ANTHROPIC_API_KEY` | API key for authentication |
|
||||
| `ANTHROPIC_AUTH_TOKEN` | OAuth token |
|
||||
| `ANTHROPIC_BASE_URL` | Custom API endpoint |
|
||||
| `CLAUDE_CODE_USE_BEDROCK` | Use AWS Bedrock (`1` to enable) |
|
||||
| `CLAUDE_CODE_USE_VERTEX` | Use Google Vertex AI (`1` to enable) |
|
||||
| `CLAUDE_CODE_USE_FOUNDRY` | Use Microsoft Foundry (`1` to enable) |
|
||||
| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enable/disable telemetry (`0` or `1`) |
|
||||
| `DISABLE_ERROR_REPORTING` | Disable error reporting (`1` to disable) |
|
||||
| `DISABLE_TELEMETRY` | Disable telemetry (`1` to disable) |
|
||||
| `MCP_TIMEOUT` | MCP startup timeout in ms (default: 10000) |
|
||||
| `MAX_MCP_OUTPUT_TOKENS` | Max MCP output tokens (default: 50000) |
|
||||
| `BASH_MAX_TIMEOUT_MS` | Bash command timeout |
|
||||
| `BASH_MAX_OUTPUT_LENGTH` | Max bash output length |
|
||||
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Auto-compact threshold percentage (1-100). Default is ~95%. Set lower (e.g., `50`) to trigger compaction earlier. Values above 95% have no effect. Use `/context` to monitor current usage. Example: `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 claude` |
|
||||
| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Keep cwd between bash calls (`1` to enable) |
|
||||
| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Disable background tasks (`1` to disable) |
|
||||
| `ENABLE_TOOL_SEARCH` | MCP tool search threshold (e.g., `auto:5`) |
|
||||
| `DISABLE_PROMPT_CACHING` | Disable all prompt caching (`1` to disable) |
|
||||
| `DISABLE_PROMPT_CACHING_HAIKU` | Disable Haiku prompt caching |
|
||||
| `DISABLE_PROMPT_CACHING_SONNET` | Disable Sonnet prompt caching |
|
||||
| `DISABLE_PROMPT_CACHING_OPUS` | Disable Opus prompt caching |
|
||||
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Disable experimental beta features (`1` to disable) |
|
||||
| `CLAUDE_CODE_SHELL` | Override automatic shell detection |
|
||||
| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Override default file read token limit |
|
||||
| `CLAUDE_CODE_ENABLE_TASKS` | Set to `false` to disable new task system |
|
||||
| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | Auto-exit SDK mode after idle duration (ms) |
|
||||
|
||||
---
|
||||
|
||||
## Useful Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/model` | Switch models and adjust Opus 4.6 effort level |
|
||||
| `/config` | Interactive configuration UI |
|
||||
| `/memory` | View/edit all memory files |
|
||||
| `/agents` | Manage subagents |
|
||||
| `/mcp` | Manage MCP servers |
|
||||
| `/hooks` | View configured hooks |
|
||||
| `/plugin` | Manage plugins |
|
||||
| `/keybindings` | Configure custom keyboard shortcuts |
|
||||
| `/skills` | View and manage skills |
|
||||
| `/permissions` | View and manage permission rules |
|
||||
| `--doctor` | Diagnose configuration issues |
|
||||
| `--debug` | Debug mode with hook execution details |
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Complete Example
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "sonnet",
|
||||
"agent": "code-reviewer",
|
||||
"language": "english",
|
||||
"cleanupPeriodDays": 30,
|
||||
"autoUpdatesChannel": "stable",
|
||||
"alwaysThinkingEnabled": true,
|
||||
"plansDirectory": "./plans",
|
||||
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Edit(*)",
|
||||
"Write(*)",
|
||||
"Bash(npm run *)",
|
||||
"Bash(git *)",
|
||||
"WebFetch(domain:*)",
|
||||
"mcp__*"
|
||||
],
|
||||
"deny": [
|
||||
"Read(.env)",
|
||||
"Read(./secrets/**)"
|
||||
],
|
||||
"additionalDirectories": ["../shared/"]
|
||||
},
|
||||
|
||||
"enableAllProjectMcpServers": true,
|
||||
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'Tool starting'",
|
||||
"timeout": 5000
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"disableAllHooks": false,
|
||||
|
||||
"sandbox": {
|
||||
"enabled": true,
|
||||
"excludedCommands": ["git", "docker"]
|
||||
},
|
||||
|
||||
"attribution": {
|
||||
"commit": "Generated with Claude Code",
|
||||
"pr": ""
|
||||
},
|
||||
|
||||
"statusLine": {
|
||||
"type": "command",
|
||||
"command": "git branch --show-current"
|
||||
},
|
||||
|
||||
"spinnerTipsEnabled": true,
|
||||
"spinnerTipsOverride": {
|
||||
"tips": ["Custom tip 1", "Custom tip 2"],
|
||||
"excludeDefault": false
|
||||
},
|
||||
"showTurnDuration": false,
|
||||
|
||||
"env": {
|
||||
"NODE_ENV": "development"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [Claude Code Settings Documentation](https://code.claude.com/docs/en/settings)
|
||||
- [Claude Code Settings JSON Schema](https://www.schemastore.org/claude-code-settings.json)
|
||||
- [Claude Code Configuration Guide](https://claudelog.com/configuration/)
|
||||
- [Claude Code GitHub Settings Examples](https://github.com/feiskyer/claude-code-settings)
|
||||
- [Eesel AI - Developer's Guide to settings.json](https://www.eesel.ai/blog/settings-json-claude-code)
|
||||
- [Shipyard - Claude Code CLI Cheatsheet](https://shipyard.build/blog/claude-code-cheat-sheet/)
|
||||
@@ -1,189 +0,0 @@
|
||||
# Claude Code: Skills Frontmatter Reference
|
||||
|
||||
Quick-reference tables for defining skills in `.claude/skills/<name>/SKILL.md`.
|
||||
|
||||
<table width="100%">
|
||||
<tr>
|
||||
<td><a href="../">← Back to Claude Code Best Practice</a></td>
|
||||
<td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
---
|
||||
|
||||
## Frontmatter Fields
|
||||
|
||||
All fields are optional. Only `description` is recommended so Claude knows when to use the skill.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | string | No | Display name and `/slash-command`. Lowercase letters, numbers, hyphens only (max 64 chars). Defaults to directory name if omitted |
|
||||
| `description` | string | Recommended | What the skill does and when to use it. Claude uses this for auto-discovery. Falls back to first paragraph of content if omitted |
|
||||
| `argument-hint` | string | No | Hint shown during autocomplete (e.g., `[issue-number]`, `[filename] [format]`) |
|
||||
| `disable-model-invocation` | boolean | No | Set `true` to prevent Claude from auto-loading this skill. User can still invoke via `/name`. Default: `false` |
|
||||
| `user-invocable` | boolean | No | Set `false` to hide from the `/` menu. Use for background knowledge Claude should load automatically but users shouldn't invoke directly. Default: `true` |
|
||||
| `allowed-tools` | string | No | Tools Claude can use without permission prompts when this skill is active (e.g., `Bash(agent-browser:*)`) |
|
||||
| `model` | string | No | Model to use when this skill is active |
|
||||
| `context` | string | No | Set to `"fork"` to run in an isolated subagent context |
|
||||
| `agent` | string | No | Which subagent type to use when `context: fork` is set (e.g., `Explore`, `Plan`, or a custom agent name). Default: `general-purpose` |
|
||||
| `hooks` | object | No | Lifecycle hooks scoped to this skill (same format as agent hooks) |
|
||||
|
||||
---
|
||||
|
||||
## Invocation Methods
|
||||
|
||||
| Method | Trigger | Example |
|
||||
|--------|---------|---------|
|
||||
| **Slash command** | User types `/skill-name` | `/weather-fetcher` |
|
||||
| **Agent preload** | Listed in agent's `skills:` frontmatter | `skills: [weather-fetcher]` |
|
||||
| **Auto-discovery** | Claude matches user intent to `description` | Automatic |
|
||||
| **Direct mention** | User references the skill by name | "Use the weather-fetcher skill" |
|
||||
|
||||
---
|
||||
|
||||
## Invocation Control
|
||||
|
||||
| Frontmatter | User can invoke | Claude can invoke | Context loading |
|
||||
|-------------|-----------------|-------------------|-----------------|
|
||||
| (default) | Yes | Yes | Description always in context, full skill loads when invoked |
|
||||
| `disable-model-invocation: true` | Yes | No | Description not in context, full skill loads when user invokes |
|
||||
| `user-invocable: false` | No | Yes | Description always in context, full skill loads when invoked |
|
||||
|
||||
---
|
||||
|
||||
## Skill vs Agent vs Command
|
||||
|
||||
| Aspect | Skill | Agent | Command |
|
||||
|--------|-------|-------|---------|
|
||||
| **File location** | `.claude/skills/<name>/SKILL.md` | `.claude/agents/<name>.md` | `.claude/commands/<name>.md` |
|
||||
| **Has own tools** | No (restricts via `allowed-tools`) | Yes (`tools:` field) | No |
|
||||
| **Has memory** | No | Yes (`memory:` field) | No |
|
||||
| **Has hooks** | Yes (`hooks:` field) | Yes (`hooks:` field) | No |
|
||||
| **Can preload skills** | No | Yes (`skills:` field) | No |
|
||||
| **User-invocable** | Yes (`/skill-name`) | No (invoked via Task tool) | Yes (`/command-name`) |
|
||||
| **Runs in isolation** | Optional (`context: fork`) | Always isolated subprocess | Runs in main context |
|
||||
| **Supporting files** | Yes (same directory) | No | No |
|
||||
|
||||
---
|
||||
|
||||
## String Substitutions
|
||||
|
||||
Available inside skill markdown for dynamic values:
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `$ARGUMENTS` | All arguments passed when invoking the skill |
|
||||
| `$ARGUMENTS[N]` | Access a specific argument by 0-based index (e.g., `$ARGUMENTS[0]`) |
|
||||
| `$N` | Shorthand for `$ARGUMENTS[N]` (e.g., `$0`, `$1`) |
|
||||
| `${CLAUDE_SESSION_ID}` | Current session identifier |
|
||||
| `` !`command` `` | Dynamic context injection — shell command output replaces the placeholder before Claude sees it |
|
||||
|
||||
---
|
||||
|
||||
## Example: Minimal Skill
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: weather-fetcher
|
||||
description: Instructions for fetching weather data from wttr.in API
|
||||
---
|
||||
|
||||
Fetch the current temperature from https://wttr.in/Karachi?format=j1
|
||||
```
|
||||
|
||||
## Example: Restricted Skill
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: agent-browser
|
||||
description: Browser automation CLI for AI agents
|
||||
allowed-tools: Bash(agent-browser:*)
|
||||
---
|
||||
|
||||
Every browser automation follows: navigate → snapshot → interact → re-snapshot.
|
||||
```
|
||||
|
||||
## Example: Fork Context Skill
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-analysis
|
||||
description: Analyze code quality in isolation
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
Analyze the codebase for code quality issues without affecting the main conversation.
|
||||
```
|
||||
|
||||
## Example: Full-Featured Skill (All Fields)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: fix-issue
|
||||
description: Fix a GitHub issue by number, following team coding standards
|
||||
argument-hint: [issue-number]
|
||||
disable-model-invocation: true
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Edit, Write, Bash(gh *), Bash(npm test *)
|
||||
model: sonnet
|
||||
context: fork
|
||||
agent: general-purpose
|
||||
hooks:
|
||||
PostToolUse:
|
||||
- matcher: "Edit|Write"
|
||||
hooks:
|
||||
- type: command
|
||||
command: "./scripts/run-linter.sh"
|
||||
---
|
||||
|
||||
Fix GitHub issue $0 following our coding standards.
|
||||
|
||||
## Context
|
||||
- PR diff: !`gh pr diff`
|
||||
- Issue details: !`gh issue view $0`
|
||||
|
||||
## Steps
|
||||
1. Read the issue description
|
||||
2. Understand the requirements
|
||||
3. Implement the fix
|
||||
4. Write tests
|
||||
5. Create a commit
|
||||
|
||||
Session: ${CLAUDE_SESSION_ID}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scope and Priority
|
||||
|
||||
When skills share the same name, the higher-priority location wins:
|
||||
|
||||
| Location | Scope | Priority |
|
||||
|----------|-------|----------|
|
||||
| Enterprise (managed settings) | All users in organization | 1 (highest) |
|
||||
| Personal (`~/.claude/skills/`) | All your projects | 2 |
|
||||
| Project (`.claude/skills/`) | This project only | 3 |
|
||||
| Plugin (`<plugin>/skills/`) | Where plugin is enabled | Namespaced (no conflict) |
|
||||
|
||||
Skills from `.claude/commands/` still work. If a skill and a command share the same name, the skill takes precedence.
|
||||
|
||||
---
|
||||
|
||||
## Skills in This Repository
|
||||
|
||||
| Skill | Description | Used By |
|
||||
|-------|-------------|---------|
|
||||
| `weather-fetcher` | Fetch temperature from wttr.in API | weather agent |
|
||||
| `weather-transformer` | Apply transformations to temperature data | weather agent |
|
||||
| `agent-browser` | Browser automation CLI commands | standalone (auto-discovery) |
|
||||
| `presentation/vibe-to-agentic-framework` | Conceptual framework for the presentation | presentation-curator agent |
|
||||
| `presentation/presentation-structure` | Slide format, weight system, navigation | presentation-curator agent |
|
||||
| `presentation/presentation-styling` | CSS classes and component patterns | presentation-curator agent |
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [Use skills — Claude Code Docs](https://code.claude.com/docs/en/skills)
|
||||
- [Claude Code CHANGELOG](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
|
||||
Reference in New Issue
Block a user