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
.claude/agents/presentation-curator.md
+2 -2
View File
@@ -54,7 +54,7 @@ After changes, verify:
5. Any `goToSlide()` calls in the TOC point to correct slide numbers
6. Weighted slide titles in `vibe-to-agentic-framework` match actual `<h1>` titles in `presentation/index.html`
7. Agent identifiers are consistent across examples (use `frontend-engineer` / `backend-engineer`; do not introduce aliases like `frontend-eng`)
8. Hook references remain canonical (`15 hook events`) in presentation-facing content
8. Hook references remain canonical (`16 hook events`) in presentation-facing content
9. Do not manually insert `.weight-badge` markup in slide HTML (badges are JS-injected)
10. Settings precedence text must separate user-writable override order from enforced policy (`managed-settings.json`)
11. If slide 32 is touched, ensure skill frontmatter coverage includes `context: fork`
@@ -97,7 +97,7 @@ If you encountered an edge case, discovered a new pattern, or found that the wor
_Findings from previous executions are recorded here. Add new entries as bullet points._
- Hook-event references drifted across files. Treat `15 hook events` as canonical and sync all docs in the same run.
- Hook-event references drifted across files. Treat `16 hook events` as canonical and sync all docs in the same run.
- Do not use shorthand agent names in examples (`frontend-eng`). Keep identifiers exactly aligned with agent definitions.
- Never hardcode `.weight-badge` in slide HTML; badges are runtime-injected.
- Keep the framework skill name stable as `vibe-to-agentic-framework` to avoid broken skill references.
.claude/hooks/HOOKS-README.md
+3 -1
View File
@@ -1,7 +1,7 @@
# HOOKS-README
contains all the details, scripts, and instructions for the hooks
## Hook Events Overview - [Official 15 Hooks](https://docs.claude.com/en/docs/claude-code/hooks-guide)
## Hook Events Overview - [Official 16 Hooks](https://docs.claude.com/en/docs/claude-code/hooks-guide)
Claude Code provides several hook events that run at different points in the workflow:
1. SessionStart: Runs when Claude Code starts a new session or resumes one
2. SessionEnd: Runs when a Claude Code session ends
@@ -18,6 +18,7 @@ Claude Code provides several hook events that run at different points in the wor
13. Setup: Runs during setup/maintenance workflows
14. TeammateIdle: Runs when an Agent Team teammate goes idle
15. TaskCompleted: Runs when a tracked task reaches completion
16. ConfigChange: Fires when configuration files change during a session, for enterprise security auditing
## Prerequisites
@@ -83,6 +84,7 @@ Edit `.claude/hooks/config/hooks-config.json` for team-wide defaults:
"disableSetupHook": false,
"disableTeammateIdleHook": false,
"disableTaskCompletedHook": false,
"disableConfigChangeHook": false,
"disableLogging": true
}
```
.claude/hooks/config/hooks-config.json
+1
View File
@@ -14,5 +14,6 @@
"disableSetupHook": false,
"disableTeammateIdleHook": false,
"disableTaskCompletedHook": false,
"disableConfigChangeHook": false,
"disableLogging": true
}
.claude/hooks/scripts/hooks.py
+2 -1
View File
@@ -3,7 +3,7 @@
Claude Code Hook Handler
=============================================
This script handles events from Claude Code and plays sounds for different hook events.
Supports all 15 Claude Code hook event names: https://docs.claude.com/en/docs/claude-code/hooks-guide
Supports all 16 Claude Code hook event names: https://docs.claude.com/en/docs/claude-code/hooks-guide
Special handling for git commits: plays pretooluse-git-committing.mp3
"""
@@ -39,6 +39,7 @@ HOOK_SOUND_MAP = {
"Setup": "setup",
"TeammateIdle": "teammateidle",
"TaskCompleted": "taskcompleted",
"ConfigChange": "configchange",
}
# ===== BASH COMMAND PATTERNS =====
CLAUDE.md
+18 -7
View File
@@ -19,12 +19,16 @@ The agent has skills preloaded via the `skills` field, providing domain knowledg
### Skill Definition Structure
Skills in `.claude/skills/<name>/SKILL.md` use YAML frontmatter:
- `name`: Skill identifier (optional, uses directory name if omitted)
- `name`: Display name and `/slash-command` (defaults to directory name)
- `description`: When to invoke (recommended for auto-discovery)
- `model`: Model to use when skill is active
- `argument-hint`: Autocomplete hint (e.g., `[issue-number]`)
- `disable-model-invocation`: Set `true` to prevent automatic invocation
- `user-invocable`: Set `false` to hide from `/` menu (background knowledge only)
- `allowed-tools`: Tools allowed without permission prompts when skill is active
- `model`: Model to use when skill is active
- `context`: Set to `fork` to run in isolated subagent context
- `allowed-tools`: Restrict which tools Claude can use
- `agent`: Subagent type for `context: fork` (default: `general-purpose`)
- `hooks`: Lifecycle hooks scoped to this skill
### Presentation System
Any request to update, modify, or fix the presentation (`presentation/index.html`) must be handled by the `presentation-curator` agent (`.claude/agents/presentation-curator.md`). Always delegate presentation work to this agent via the Task tool — never edit the presentation directly.
@@ -41,7 +45,7 @@ Cross-platform sound notification system in `.claude/hooks/`:
- `config/hooks-config.local.json`: Personal overrides (git-ignored)
- `sounds/`: Audio files organized by hook event (generated via ElevenLabs TTS)
Hook events configured in `.claude/settings.json`: PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStart, SubagentStop, PreCompact, SessionStart, SessionEnd, Setup, PermissionRequest.
Hook events configured in `.claude/settings.json`: PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStart, SubagentStop, PreCompact, SessionStart, SessionEnd, Setup, PermissionRequest, TeammateIdle, TaskCompleted, ConfigChange.
Special handling: git commits trigger `pretooluse-git-committing` sound.
@@ -59,11 +63,18 @@ Be explicit about tool usage in subagent definitions. Avoid vague terms like "la
Subagents in `.claude/agents/*.md` use YAML frontmatter:
- `name`: Subagent identifier
- `description`: When to invoke (use "PROACTIVELY" for auto-invocation)
- `tools`: Comma-separated list of allowed tools
- `model`: Typically "haiku" for efficiency
- `color`: CLI output color for visual distinction
- `tools`: Comma-separated allowlist of tools (inherits all if omitted). Supports `Task(agent_type)` syntax
- `disallowedTools`: Tools to deny, removed from inherited or specified list
- `model`: Model alias: `haiku`, `sonnet`, `opus`, or `inherit` (default: `inherit`)
- `permissionMode`: Permission mode (e.g., `"acceptEdits"`, `"plan"`, `"bypassPermissions"`)
- `maxTurns`: Maximum agentic turns before the subagent stops
- `skills`: List of skill names to preload into agent context
- `mcpServers`: MCP servers for this subagent (server names or inline configs)
- `hooks`: Lifecycle hooks scoped to this subagent (`PreToolUse`, `PostToolUse`, `Stop`)
- `memory`: Persistent memory scope — `user`, `project`, or `local` (see `reports/claude-agent-memory.md`)
- `background`: Set to `true` to always run as a background task
- `isolation`: Set to `"worktree"` to run in a temporary git worktree
- `color`: CLI output color for visual distinction
### Configuration Hierarchy
1. `.claude/settings.local.json`: Personal settings (git-ignored)
README.md
+16 -4
View File
@@ -138,14 +138,14 @@ See [weather-orchestration-architecture](weather-orchestration/weather-orchestra
| `/compact` | `/context` | `/model` | `/plan` | `/config` |
| `/clear` | `/cost` | `/memory` | `/doctor` | `/rewind` |
[**See Complete List →**](reports/claude-commands.md)
[**See Complete List →**](reports/live/agent-command-skills/claude-commands.md)
## CLAUDE SETTINGS
| | |
|---|---|
| [**Claude Settings**](reports/claude-settings.md) | [**Global vs Project Settings**](reports/claude-global-vs-project-settings.md) |
| [**Claude Settings**](reports/live/claude-settings.md) | [**Global vs Project Settings**](reports/claude-global-vs-project-settings.md) |
## MCP SERVERS FOR DAILY USE
@@ -164,15 +164,27 @@ Research (Context7/DeepWiki) -> Debug (Playwright/Chrome) -> Document (Excalidra
## REPORTS
### Live Reports
> Reports that are frequently updated as Claude Code evolves.
| Report | Description |
|--------|-------------|
| [Claude Code Commands Reference](reports/live/agent-command-skills/claude-commands.md) | Complete reference of all slash commands, keyboard shortcuts, and input modes |
| [Claude Code Settings Reference](reports/live/claude-settings.md) | Comprehensive guide to all `settings.json` configuration options |
| [Agents Frontmatter Reference](reports/live/agent-command-skills/claude-agents-frontmatter.md) | Complete reference of all agent (`.claude/agents/`) frontmatter fields |
| [Commands Frontmatter Reference](reports/live/agent-command-skills/claude-commands-frontmatter.md) | Complete reference of all command (`.claude/commands/`) frontmatter fields |
| [Skills Frontmatter Reference](reports/live/agent-command-skills/claude-skills-frontmatter.md) | Complete reference of all skill (`.claude/skills/`) frontmatter fields |
### Reports
| Report | Description |
|--------|-------------|
| [Agent SDK vs CLI System Prompts](reports/claude-agent-sdk-vs-cli-system-prompts.md) | Why Claude CLI and Agent SDK outputs may differ—system prompt architecture and determinism |
| [Browser Automation MCP Comparison](reports/claude-in-chrome-v-chrome-devtools-mcp.md) | Comparison of Playwright, Chrome DevTools, and Claude in Chrome for automated testing |
| [Claude Code CLI Startup Flags](reports/claude-cli-startup-flags.md) | Complete reference of all CLI flags, subcommands, and environment variables |
| [Claude Code Commands Reference](reports/claude-commands.md) | Complete reference of all slash commands, keyboard shortcuts, and input modes |
| [Claude Code Settings Reference](reports/claude-settings.md) | Comprehensive guide to all `settings.json` configuration options |
| [CLAUDE.md Loading in Monorepos](reports/claude-md-for-larger-mono-repos.md) | Understanding ancestor vs descendant loading behavior for CLAUDE.md files |
| [Global vs Project Settings](reports/claude-global-vs-project-settings.md) | Which features are global-only (`~/.claude/`) vs dual-scope, including Tasks and Agent Teams |
| [Skills Discovery in Monorepos](reports/claude-skills-for-larger-mono-repos.md) | How skills are discovered and loaded in large monorepo projects |
| [Agent Memory Frontmatter](reports/claude-agent-memory.md) | Persistent memory scopes (`user`, `project`, `local`) for subagents — enabling agents to learn across sessions |
| [Boris Cherny's 12 Customization Tips](reports/claude-boris-tips-feb-26.md) | 12 ways to customize Claude Code — from terminal config to plugins, agents, hooks, and output styles |
| [Advanced Tool Use Patterns](reports/claude-advanced-tool-use.md) | Programmatic Tool Calling (PTC), Tool Search, and Tool Use Examples |
presentation/index.html
+1 -1
View File
@@ -1068,7 +1068,7 @@ Task(
<p><strong>PostToolUse</strong> &mdash; auto-format code</p>
<p><strong>Stop</strong> &mdash; check task completion</p>
<p><strong>SessionStart</strong> &mdash; load context</p>
<p style="margin-top: 12px; color: #666;">15 hook events, 5 can block execution.</p>
<p style="margin-top: 12px; color: #666;">16 hook events, 5 can block execution.</p>
</div>
<div class="col-card">
<h4>MCP Servers</h4>
reports/claude-cli-startup-flags.md
+7
View File
@@ -118,6 +118,7 @@ A comprehensive reference of all available command-line flags when launching Cla
| Flag | Short | Description |
|------|-------|-------------|
| `--add-dir <PATH>` | | Add additional working directories for Claude to access |
| `--worktree` | `-w` | Start Claude in an isolated git worktree (branched from HEAD) |
---
@@ -206,6 +207,12 @@ These environment variables modify Claude Code behavior at startup:
| `MAX_THINKING_TOKENS` | Limit thinking token budget (set to `0` to disable) |
| `CLAUDE_CODE_EFFORT_LEVEL` | Control thinking depth: `low`, `medium`, `high` |
| `USE_BUILTIN_RIPGREP=0` | Use system ripgrep instead of built-in (Alpine Linux) |
| `CLAUDE_CODE_ENABLE_TASKS=false` | Disable new task management system, revert to old todos |
| `CLAUDE_CODE_SHELL` | Override automatic shell detection |
| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Override default file read token limit |
| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | Auto-exit SDK mode after idle duration (ms) |
| `CLAUDE_CODE_SIMPLE` | Enable simple mode (Bash + Edit tools only) |
| `CLAUDE_BASH_NO_LOGIN=1` | Skip login shell for BashTool |
---
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/claude-commands.md → reports/live/agent-command-skills/claude-commands.md
+2 -2
View File
@@ -4,8 +4,8 @@ A comprehensive reference of all available slash commands in Claude Code's inter
<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>
<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>
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)
reports/claude-settings.md → reports/live/claude-settings.md
+46 -3
View File
@@ -196,7 +196,7 @@ Control what tools and operations Claude can perform.
| Tool | Syntax | Examples |
|------|--------|----------|
| `Bash` | `Bash(command pattern)` | `Bash(npm run *)`, `Bash(git commit *)` |
| `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/**)` |
@@ -207,6 +207,11 @@ Control what tools and operations Claude can perform.
| `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
{
@@ -239,7 +244,7 @@ Control what tools and operations Claude can perform.
Execute custom shell commands at various points in Claude Code's lifecycle.
### Hook Events (15 total)
### Hook Events (16 total)
| Event | When Fired | Matcher Support | Common Use Cases |
|-------|------------|-----------------|------------------|
@@ -255,9 +260,10 @@ Execute custom shell commands at various points in Claude Code's lifecycle.
| `SubagentStart` | Subagent spawned | Yes | Per-agent setup |
| `SubagentStop` | Subagent completes | Yes | Cleanup, validation |
| `PreCompact` | Before context compaction | Yes | Backup, logging |
| `Setup` | Repository init (`--init`, `--maintenance`) | Yes | One-time setup |
| `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
@@ -293,6 +299,7 @@ Execute custom shell commands at various points in Claude Code's lifecycle.
| `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
@@ -321,6 +328,22 @@ Execute custom shell commands at various points in Claude Code's lifecycle.
| `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
{
@@ -556,6 +579,18 @@ Configure via `env` key:
}
```
**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
@@ -662,6 +697,11 @@ Set environment variables for all Claude Code sessions.
| `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) |
---
@@ -676,6 +716,9 @@ Set environment variables for all Claude Code sessions.
| `/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 |