diff --git a/.claude/agents/presentation-curator.md b/.claude/agents/presentation-curator.md index e0ab56e..c644deb 100644 --- a/.claude/agents/presentation-curator.md +++ b/.claude/agents/presentation-curator.md @@ -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 `

` 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. diff --git a/.claude/hooks/HOOKS-README.md b/.claude/hooks/HOOKS-README.md index dfe7618..270ae03 100644 --- a/.claude/hooks/HOOKS-README.md +++ b/.claude/hooks/HOOKS-README.md @@ -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 } ``` diff --git a/.claude/hooks/config/hooks-config.json b/.claude/hooks/config/hooks-config.json index 79ef816..c3b5655 100644 --- a/.claude/hooks/config/hooks-config.json +++ b/.claude/hooks/config/hooks-config.json @@ -14,5 +14,6 @@ "disableSetupHook": false, "disableTeammateIdleHook": false, "disableTaskCompletedHook": false, + "disableConfigChangeHook": false, "disableLogging": true } diff --git a/.claude/hooks/scripts/hooks.py b/.claude/hooks/scripts/hooks.py index 2c2b044..e4dcff2 100644 --- a/.claude/hooks/scripts/hooks.py +++ b/.claude/hooks/scripts/hooks.py @@ -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 ===== diff --git a/CLAUDE.md b/CLAUDE.md index dce548b..aecb2cc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,12 +19,16 @@ The agent has skills preloaded via the `skills` field, providing domain knowledg ### Skill Definition Structure Skills in `.claude/skills//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) diff --git a/README.md b/README.md index c28cbe7..4b5613c 100644 --- a/README.md +++ b/README.md @@ -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 | diff --git a/presentation/index.html b/presentation/index.html index d5a376a..09db98c 100644 --- a/presentation/index.html +++ b/presentation/index.html @@ -1068,7 +1068,7 @@ Task(

PostToolUse — auto-format code

Stop — check task completion

SessionStart — load context

-

15 hook events, 5 can block execution.

+

16 hook events, 5 can block execution.

MCP Servers

diff --git a/reports/claude-cli-startup-flags.md b/reports/claude-cli-startup-flags.md index 1e0b6d3..10b1be2 100644 --- a/reports/claude-cli-startup-flags.md +++ b/reports/claude-cli-startup-flags.md @@ -118,6 +118,7 @@ A comprehensive reference of all available command-line flags when launching Cla | Flag | Short | Description | |------|-------|-------------| | `--add-dir ` | | 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 | --- diff --git a/reports/live/agent-command-skills/claude-agents-frontmatter.md b/reports/live/agent-command-skills/claude-agents-frontmatter.md new file mode 100644 index 0000000..588be7a --- /dev/null +++ b/reports/live/agent-command-skills/claude-agents-frontmatter.md @@ -0,0 +1,144 @@ +# Claude Code: Agents Frontmatter Reference + +Quick-reference tables for defining subagents in `.claude/agents/*.md`. + + + + + + +
← Back to Claude Code Best PracticeClaude
+ +--- + +## 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//` | No | No | +| `project` | `.claude/agent-memory//` | Yes | Yes | +| `local` | `.claude/agent-memory-local//` | 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) diff --git a/reports/live/agent-command-skills/claude-commands-frontmatter.md b/reports/live/agent-command-skills/claude-commands-frontmatter.md new file mode 100644 index 0000000..f64130a --- /dev/null +++ b/reports/live/agent-command-skills/claude-commands-frontmatter.md @@ -0,0 +1,99 @@ +# Claude Code: Commands Frontmatter Reference + +Quick-reference tables for defining custom commands in `.claude/commands/.md`. + + + + + + +
← Back to Claude Code Best PracticeClaude
+ +--- + +## 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) diff --git a/reports/claude-commands.md b/reports/live/agent-command-skills/claude-commands.md similarity index 98% rename from reports/claude-commands.md rename to reports/live/agent-command-skills/claude-commands.md index 9160615..62b7672 100644 --- a/reports/claude-commands.md +++ b/reports/live/agent-command-skills/claude-commands.md @@ -4,8 +4,8 @@ A comprehensive reference of all available slash commands in Claude Code's inter - - + +
← Back to Claude Code Best PracticeClaude← Back to Claude Code Best PracticeClaude
diff --git a/reports/live/agent-command-skills/claude-skills-frontmatter.md b/reports/live/agent-command-skills/claude-skills-frontmatter.md new file mode 100644 index 0000000..321a989 --- /dev/null +++ b/reports/live/agent-command-skills/claude-skills-frontmatter.md @@ -0,0 +1,189 @@ +# Claude Code: Skills Frontmatter Reference + +Quick-reference tables for defining skills in `.claude/skills//SKILL.md`. + + + + + + +
← Back to Claude Code Best PracticeClaude
+ +--- + +## 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//SKILL.md` | `.claude/agents/.md` | `.claude/commands/.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 (`/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) diff --git a/reports/claude-settings.md b/reports/live/claude-settings.md similarity index 90% rename from reports/claude-settings.md rename to reports/live/claude-settings.md index 9b49c7f..c8ca667 100644 --- a/reports/claude-settings.md +++ b/reports/live/claude-settings.md @@ -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 |