gilles/claude-code-best-practice
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated settings

Browse Source
This commit is contained in:
Shayan Rais
2026-02-20 18:07:49 +05:00
parent fa26ac1d71
commit a4f7f2ec48
13 changed files with 530 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
reports/live/agent-command-skills/claude-agents-frontmatter.md
+144
View File
@@ -0,0 +1,144 @@
# Claude Code: Agents Frontmatter Reference
Quick-reference tables for defining subagents in `.claude/agents/*.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
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Unique identifier using lowercase letters and hyphens |
| `description` | string | Yes | When to invoke. Use `"PROACTIVELY"` for auto-invocation by Claude |
| `tools` | string/list | No | Comma-separated allowlist of tools (e.g., `Read, Write, Edit, Bash`). Inherits all tools if omitted. Supports `Task(agent_type)` syntax to restrict spawnable subagents |
| `disallowedTools` | string/list | No | Tools to deny, removed from inherited or specified list |
| `model` | string | No | Model alias: `haiku`, `sonnet`, `opus`, or `inherit` (default: `inherit`) |
| `permissionMode` | string | No | Permission mode: `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan` |
| `maxTurns` | integer | No | Maximum number of agentic turns before the subagent stops |
| `skills` | list | No | Skill names to preload into agent context at startup (full content injected, not just made available) |
| `mcpServers` | list | No | MCP servers for this subagent — server name strings or inline `{name: config}` objects |
| `hooks` | object | No | Lifecycle hooks scoped to this subagent: `PreToolUse`, `PostToolUse`, `Stop` (converted to `SubagentStop` at runtime) |
| `memory` | string | No | Persistent memory scope: `user`, `project`, or `local` |
| `background` | boolean | No | Set to `true` to always run as a background task (default: `false`) |
| `isolation` | string | No | Set to `"worktree"` to run in a temporary git worktree (auto-cleaned if no changes) |
| `color` | string | No | CLI output color for visual distinction (e.g., `green`, `magenta`) |
---
## Memory Scopes
| Scope | Storage Location | Shared | Version Controlled |
|-------|-----------------|--------|--------------------|
| `user` | `~/.claude/agent-memory/<name>/` | No | No |
| `project` | `.claude/agent-memory/<name>/` | Yes | Yes |
| `local` | `.claude/agent-memory-local/<name>/` | No | No |
See [claude-agent-memory.md](../claude-agent-memory.md) for full details.
---
## Invocation
Agents are invoked via the **Task tool**, never via bash commands:
```
Task(subagent_type="agent-name", description="...", prompt="...", model="haiku")
```
Or from a command file that delegates to an agent.
---
## Example: Minimal Agent
```yaml
---
name: code-reviewer
description: Reviews code for quality issues
tools: Read, Grep, Glob
model: haiku
---
Review the code for quality issues and report findings.
```
## Example: Full-Featured Agent (All Fields)
```yaml
---
name: deploy-manager
description: Use this agent PROACTIVELY for deployment pipelines and release management
tools: Read, Write, Edit, Bash, Grep, Glob, Task(monitor, rollback)
disallowedTools: NotebookEdit
model: sonnet
permissionMode: acceptEdits
maxTurns: 25
skills:
- deploy-checklist
- rollback-procedures
mcpServers:
- slack
- name: pagerduty
command: npx
args: ["-y", "@pagerduty/mcp-server"]
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-deploy-command.sh"
PostToolUse:
- matcher: "Write"
hooks:
- type: command
command: "./scripts/log-file-changes.sh"
Stop:
- hooks:
- type: command
command: "./scripts/notify-deploy-complete.sh"
memory: project
background: false
isolation: worktree
color: blue
---
You are a deployment manager. Follow the deploy-checklist skill for
pre-flight checks and use rollback-procedures if any step fails.
Notify the team via Slack when deployment completes.
```
---
## Scope and Priority
When multiple subagents share the same name, the higher-priority location wins:
| Location | Scope | Priority |
|----------|-------|----------|
| `--agents` CLI flag | Current session | 1 (highest) |
| `.claude/agents/` | Current project | 2 |
| `~/.claude/agents/` | All your projects | 3 |
| Plugin's `agents/` directory | Where plugin is enabled | 4 (lowest) |
---
## Agents in This Repository
| Agent | Model | Tools | Skills | Memory |
|-------|-------|-------|--------|--------|
| `weather` | sonnet | WebFetch, Read, Write | weather-fetcher, weather-transformer | project |
| `presentation-curator` | sonnet | Read, Write, Edit, Grep, Glob | vibe-to-agentic-framework, presentation-structure, presentation-styling | — |
---
## Sources
- [Create custom subagents — Claude Code Docs](https://code.claude.com/docs/en/sub-agents)
- [Claude Code CHANGELOG](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
reports/live/agent-command-skills/claude-commands-frontmatter.md
+99
View File
@@ -0,0 +1,99 @@
# Claude Code: Commands Frontmatter Reference
Quick-reference tables for defining custom commands in `.claude/commands/<name>.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
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `description` | string | Recommended | Short description shown in autocomplete when user types `/` |
| `model` | string | No | Model override for this command (e.g., `haiku`, `sonnet`) |
Commands have minimal frontmatter compared to agents and skills — they are lightweight entry points that delegate heavy work to agents.
---
## Invocation
| Method | Example |
|--------|---------|
| **Slash command** | User types `/command-name` at the prompt |
| **With arguments** | `/command-name arg1 arg2` — arguments are appended to the prompt |
---
## Scope Levels
| Scope | Location | Shared |
|-------|----------|--------|
| **Project** | `.claude/commands/*.md` | Yes (committed to repo) |
| **User** | `~/.claude/commands/*.md` | No (personal, all projects) |
Both scopes are available simultaneously — project commands appear alongside user commands.
---
## Template Variables
Available inside command markdown via `${VARIABLE}`:
| Variable | Description |
|----------|-------------|
| `${ARGUMENTS}` | Arguments passed after the command name |
| `${CLAUDE_SESSION_ID}` | Current session identifier |
| `${CLAUDE_PROJECT_DIR}` | Project root directory path |
---
## Example: Orchestrator Command
```yaml
---
description: Fetch and transform weather data for Karachi
model: haiku
---
# Weather Orchestrator
1. Ask the user for temperature unit preference
2. Use the Task tool to invoke the weather agent
3. Report the results
```
---
## Commands in This Repository
| Command | Model | Description | Delegates To |
|---------|-------|-------------|-------------|
| `weather-orchestrator` | haiku | Fetch and transform Karachi weather | weather agent |
---
## Intentionally Not Documented Here
These items were identified during the 2.1.0–2.1.49 audit but belong in other reports:
| 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) |
| 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) |
---
## Sources
- [Create custom commands — Claude Code Docs](https://code.claude.com/docs/en/custom-commands)
- [Claude Code CHANGELOG](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
reports/live/agent-command-skills/claude-commands.md
+244
View File
@@ -0,0 +1,244 @@
# 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)
reports/live/agent-command-skills/claude-skills-frontmatter.md
+189
View File
@@ -0,0 +1,189 @@
# 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)