From 3776747e8a025cf28fc61d2b56b39f0af6bfd39e Mon Sep 17 00:00:00 2001 From: Shayan Rais Date: Mon, 2 Mar 2026 10:47:11 +0500 Subject: [PATCH] major refactor --- !/command-skill-agent-flow.svg | 62 ++-- .../workflow-claude-subagents-agent.md} | 2 +- .../workflow-claude-subagents.md} | 6 +- README.md | 48 +-- best-practice/claude-commands.md | 309 +++++++----------- best-practice/claude-skills-frontmatter.md | 189 ----------- best-practice/claude-subagents.md | 2 +- .../claude-subagents-implementation.md | 2 +- reports/claude-commands-frontmatter.md | 99 ------ 9 files changed, 178 insertions(+), 541 deletions(-) rename .claude/agents/workflows/{reports/workflow-changelog-claude-subagents-agent.md => best-practice/workflow-claude-subagents-agent.md} (99%) rename .claude/commands/workflows/{reports/workflow-changelog-report-claude-subagents.md => best-practice/workflow-claude-subagents.md} (98%) delete mode 100644 best-practice/claude-skills-frontmatter.md delete mode 100644 reports/claude-commands-frontmatter.md diff --git a/!/command-skill-agent-flow.svg b/!/command-skill-agent-flow.svg index 6eaba0a..1695c50 100644 --- a/!/command-skill-agent-flow.svg +++ b/!/command-skill-agent-flow.svg @@ -1,53 +1,63 @@ - + - - + + - + - - User + + User - + - - Command - /orchestrator + + Command + commands/weather-orchestrator + + Invokes the weather agent + to fetch & transform data - - Task + + Task - - Agent + + Agent + agents/weather - - skills: - • fetcher • transformer - (preloaded knowledge) + + preloaded skills: + weather-fetcher + weather-transformer + + Executes skills sequentially: + fetch temp, then transform it - + - - Output - output.md + + Output + orchestration-workflow/output.md + + Transformed temperature + written to output file - + - - Command → Agent (with preloaded Skills) → Output + + commands/weather-orchestrator → agents/weather (with preloaded skills) → orchestration-workflow/output.md diff --git a/.claude/agents/workflows/reports/workflow-changelog-claude-subagents-agent.md b/.claude/agents/workflows/best-practice/workflow-claude-subagents-agent.md similarity index 99% rename from .claude/agents/workflows/reports/workflow-changelog-claude-subagents-agent.md rename to .claude/agents/workflows/best-practice/workflow-claude-subagents-agent.md index 4c8887d..57ed3f4 100644 --- a/.claude/agents/workflows/reports/workflow-changelog-claude-subagents-agent.md +++ b/.claude/agents/workflows/best-practice/workflow-claude-subagents-agent.md @@ -1,5 +1,5 @@ --- -name: workflow-changelog-claude-subagents-agent +name: workflow-claude-subagents-agent description: Research agent that fetches Claude Code docs, reads the local subagents report, and analyzes drift model: opus color: blue diff --git a/.claude/commands/workflows/reports/workflow-changelog-report-claude-subagents.md b/.claude/commands/workflows/best-practice/workflow-claude-subagents.md similarity index 98% rename from .claude/commands/workflows/reports/workflow-changelog-report-claude-subagents.md rename to .claude/commands/workflows/best-practice/workflow-claude-subagents.md index 72e4574..2c6e35b 100644 --- a/.claude/commands/workflows/reports/workflow-changelog-report-claude-subagents.md +++ b/.claude/commands/workflows/best-practice/workflow-claude-subagents.md @@ -17,9 +17,9 @@ This is a **read-then-report** workflow. Launch agents, merge results, and produ **Immediately** spawn both agents using the Task tool **in the same message** (parallel launch): -### Agent 1: workflow-changelog-claude-subagents-agent +### Agent 1: workflow-claude-subagents-agent -Spawn using `subagent_type: "workflow-changelog-claude-subagents-agent"`. Give it this prompt: +Spawn using `subagent_type: "workflow-claude-subagents-agent"`. Give it this prompt: > Research the claude-code-best-practice project for subagents report drift. Check the last $ARGUMENTS versions (default: 10). > @@ -69,7 +69,7 @@ Both agents run independently and will return their findings. ## Phase 2: Merge Findings & Generate Report **Wait for both agents to complete.** Once you have: -- **workflow-changelog-claude-subagents-agent findings** — detailed report analysis with local file reads, external doc fetches, and drift detection +- **workflow-claude-subagents-agent findings** — detailed report analysis with local file reads, external doc fetches, and drift detection - **claude-code-guide findings** — independent research on latest Claude Code agents features and frontmatter changes Cross-reference the two. The dedicated agent provides report-specific drift analysis, while the claude-code-guide agent may surface things it missed (e.g. very recent changes, undocumented features, or context from web searches). Flag any contradictions between the two for the user to resolve. diff --git a/README.md b/README.md index fe85908..a179951 100644 --- a/README.md +++ b/README.md @@ -23,9 +23,9 @@ practice makes claude perfect | Feature | Location | Description | |---------|----------|-------------| -| [**Skills**](https://code.claude.com/docs/en/skills) | `.claude/skills//SKILL.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-skills-frontmatter.md) [![Implemented](!/tags/implemented.svg)](.claude/skills/) Reusable knowledge, workflows, and slash commands — load on-demand or invoke with `/skill-name` | | [**Commands**](https://code.claude.com/docs/en/skills) | `.claude/commands/.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-commands.md) [![Implemented](!/tags/implemented.svg)](.claude/commands/) Entry-point prompts for workflows — invoke with `/command-name` | | [**Sub-Agents**](https://code.claude.com/docs/en/sub-agents) | `.claude/agents/.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-subagents.md) [![Implemented](!/tags/implemented.svg)](implementation/claude-subagents-implementation.md) Custom agents with their own name, color, tools, permissions, and model — usable as main agent or isolated subagents via the Task tool | +| [**Skills**](https://code.claude.com/docs/en/skills) | `.claude/skills//SKILL.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-commands.md#skills-frontmatter-fields) [![Implemented](!/tags/implemented.svg)](.claude/skills/) Reusable knowledge, workflows, and slash commands — load on-demand or invoke with `/skill-name` | | [**Memory**](https://code.claude.com/docs/en/memory) | `CLAUDE.md` | Persistent context via CLAUDE.md files and `@path` imports that Claude sees every session | | [**Rules**](https://code.claude.com/docs/en/memory#modular-rules-with-clauderules) | `.claude/rules/*.md` | Modular topic-specific instructions with optional path-scoping via frontmatter | | [**Hooks**](https://code.claude.com/docs/en/hooks) | `.claude/hooks/` | Deterministic scripts that run outside the agentic loop on specific events | @@ -39,17 +39,23 @@ practice makes claude perfect > **Note:** Custom slash commands have been merged into skills. Files in `.claude/commands/` still work, but skills (`.claude/skills/`) are recommended as they support additional features like supporting files, invocation control, and subagent execution. -## 💎 HIDDEN GEMS + -> Reports that are frequently updated as Claude Code evolves. +## Orchestration Workflow -| Report | Description | -|--------|-------------| -| [Claude Code Commands Reference](best-practice/claude-commands.md) | Complete reference of all slash commands, keyboard shortcuts, and input modes | -| [Claude Code Settings Reference](best-practice/claude-settings.md) | Comprehensive guide to all `settings.json` configuration options | -| [Subagents Reference](best-practice/claude-subagents.md) | Complete reference for Claude Code subagents — built-in agents, custom agents, and frontmatter fields | -| [Commands Frontmatter Reference](reports/claude-commands-frontmatter.md) | Complete reference of all command (`.claude/commands/`) frontmatter fields | -| [Skills Frontmatter Reference](best-practice/claude-skills-frontmatter.md) | Complete reference of all skill (`.claude/skills/`) frontmatter fields | +Workflow orchestration using the **Command → Agent → Skills** pattern. + +

+ Command Skill Agent Architecture Flow +

+ +| Component | Role | Example | +|-----------|------|---------| +| **Command** | Entry point, user interaction | `/weather-orchestrator` | +| **Agent** | Orchestrates workflow with preloaded skills | `weather` agent | +| **Skills** | Domain knowledge injected at startup | `weather-fetcher`, `weather-transformer` | + +See [orchestration-workflow](orchestration-workflow/orchestration-workflow.md) for implementation details. ## MY EXPERIENCE @@ -110,24 +116,6 @@ practice makes claude perfect - [Claude Code Tasks - inspired by beats](https://www.reddit.com/r/ClaudeAI/comments/1qkjznp/anthropic_replaced_claude_codes_old_todos_with/) [Inspiration](https://github.com/steveyegge/beads) - [Ralph Plugin](https://x.com/GeoffreyHuntley/status/2015031262692753449) - - -## Orchestration Workflow - -Workflow orchestration using the **Command → Agent → Skills** pattern. - -

- Command Skill Agent Architecture Flow -

- -| Component | Role | Example | -|-----------|------|---------| -| **Command** | Entry point, user interaction | `/weather-orchestrator` | -| **Agent** | Orchestrates workflow with preloaded skills | `weather` agent | -| **Skills** | Domain knowledge injected at startup | `weather-fetcher`, `weather-transformer` | - -See [orchestration-workflow](orchestration-workflow/orchestration-workflow.md) for implementation details. - ## AI TERMS | | | | | | @@ -191,8 +179,6 @@ Research (Context7/DeepWiki) -> Debug (Playwright/Chrome) -> Document (Excalidra | [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 | | [Usage, Rate Limits & Extra Usage](reports/claude-usage-and-rate-limits.md) | Usage commands (`/usage`, `/extra-usage`, `/cost`), rate limits, and pay-as-you-go overflow billing | -| [Claude Code Commands Reference](best-practice/claude-commands.md) | Complete reference of all slash commands, keyboard shortcuts, and input modes | +| [Commands Reference](best-practice/claude-commands.md) | Complete reference for Claude Code commands — command definitions, frontmatter fields, and all built-in slash commands | | [Claude Code Settings Reference](best-practice/claude-settings.md) | Comprehensive guide to all `settings.json` configuration options | | [Subagents Reference](best-practice/claude-subagents.md) | Complete reference for Claude Code subagents — built-in agents, custom agents, and frontmatter fields | -| [Commands Frontmatter Reference](reports/claude-commands-frontmatter.md) | Complete reference of all command (`.claude/commands/`) frontmatter fields | -| [Skills Frontmatter Reference](best-practice/claude-skills-frontmatter.md) | Complete reference of all skill (`.claude/skills/`) frontmatter fields | diff --git a/best-practice/claude-commands.md b/best-practice/claude-commands.md index 9160615..4372756 100644 --- a/best-practice/claude-commands.md +++ b/best-practice/claude-commands.md @@ -1,6 +1,9 @@ -# Claude Code Commands Reference +# Commands Best Practice -A comprehensive reference of all available slash commands in Claude Code's interactive mode. +![Last Updated](https://img.shields.io/badge/Last_Updated-Mar_2%2C_2026-white?style=flat&labelColor=555)
+[![Implemented](https://img.shields.io/badge/Implemented-2ea44f?style=flat)](../.claude/commands/) + +Complete reference for Claude Code commands — command definitions, frontmatter fields, and all built-in slash commands. @@ -9,236 +12,162 @@ A comprehensive reference of all available slash commands in Claude Code's inter
-## 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) +## Frontmatter Fields + +Custom commands are defined in `.claude/commands/.md` with optional YAML frontmatter. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `description` | string | Recommended | What the command does. Shown in autocomplete and used by Claude for auto-discovery | +| `argument-hint` | string | No | Hint shown during autocomplete (e.g., `[issue-number]`, `[filename]`) | +| `allowed-tools` | string | No | Tools allowed without permission prompts when this command is active | +| `model` | string | No | Model to use when this command runs (e.g., `haiku`, `sonnet`, `opus`) | --- -## Session Management +## String Substitutions -| 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 ` | 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 | +Available inside command markdown for dynamic values: + +| Variable | Description | +|----------|-------------| +| `$ARGUMENTS` | All arguments passed when invoking the command | +| `$ARGUMENTS[N]` | Access a specific argument by 0-based index | +| `$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 | --- -## Context & Cost +## Invocation -| 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 | +Custom commands are invoked by typing `/command-name` in Claude Code's interactive mode: ---- - -## 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 | +| Method | 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 | +| `/command-name` | Invoke directly from the command menu | +| `/command-name [args]` | Pass arguments that map to `$ARGUMENTS` | +| Autocomplete | Type `/` to see all available commands with descriptions | +| Subdirectories | Commands in subdirectories use `/subdir:command-name` | --- -## Dynamic Commands +## Example: Minimal Command -These commands are not built-in but are discovered at runtime from your configuration: +```yaml +--- +description: Fetch and transform weather data for Karachi +model: haiku +--- -### MCP Prompts - -MCP servers can expose prompts that appear as commands: - -``` -/mcp____ +Fetch the current temperature for Karachi, Pakistan and apply transformations. ``` -### Plugin Commands +## Example: Full-Featured Command (All Fields) -Installed plugins can provide their own commands, namespaced by plugin name: +```yaml +--- +description: Fix a GitHub issue by number, following team coding standards +argument-hint: [issue-number] +allowed-tools: Read, Edit, Write, Bash(gh *), Bash(npm test *) +model: sonnet +--- -``` -/plugin-name:command-name -``` +Fix GitHub issue $0 following our coding standards. -### Custom Skills +## Context +- PR diff: !`gh pr diff` +- Issue details: !`gh issue view $0` -Skills defined in `.claude/skills/` appear as invocable commands: +## Steps +1. Read the issue description +2. Understand the requirements +3. Implement the fix +4. Write tests +5. Create a commit -``` -/skill-name +Session: ${CLAUDE_SESSION_ID} ``` --- -## CLI Flags +## Scope and Priority -These flags are used when launching Claude Code from the terminal, not as interactive commands: +When multiple commands share the same name, the higher-priority location wins: -| 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 ` | Resume a session linked to a specific GitHub PR | +| Location | Scope | Priority | +|----------|-------|----------| +| Project (`.claude/commands/`) | This project only | 1 (highest) | +| Personal (`~/.claude/commands/`) | All your projects | 2 | +| Plugin (`/commands/`) | Where plugin is enabled | 3 (lowest) | --- -## Keyboard Shortcuts +## Claude Commands -### Navigation & Control +### All Commands -| 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 | +Built-in slash commands available in Claude Code's interactive mode: -### Model & Mode Switching +| Command | Tag | Description | +|---------|-----|-------------| +| `/clear` | ![Session](https://img.shields.io/badge/Session-4A90D9?style=flat) | Clear conversation history and start fresh | +| `/compact [instructions]` | ![Session](https://img.shields.io/badge/Session-4A90D9?style=flat) | Compress conversation to free context window. Optional instructions focus the compaction | +| `/exit` | ![Session](https://img.shields.io/badge/Session-4A90D9?style=flat) | Exit the REPL | +| `/fork` | ![Session](https://img.shields.io/badge/Session-4A90D9?style=flat) | Fork the current conversation into a new session | +| `/rename ` | ![Session](https://img.shields.io/badge/Session-4A90D9?style=flat) | Rename the current session for easier identification | +| `/resume [session]` | ![Session](https://img.shields.io/badge/Session-4A90D9?style=flat) | Resume a previous conversation by ID or name, or open the session picker | +| `/rewind` | ![Session](https://img.shields.io/badge/Session-4A90D9?style=flat) | Rewind conversation and/or code to an earlier point | +| `/teleport` | ![Session](https://img.shields.io/badge/Session-4A90D9?style=flat) | Resume a remote session from claude.ai (subscribers only) | +| `/context` | ![Context](https://img.shields.io/badge/Context-8E44AD?style=flat) | Visualize current context usage as a colored grid with token counts | +| `/cost` | ![Context](https://img.shields.io/badge/Context-8E44AD?style=flat) | Show token usage statistics and spending for the current session | +| `/stats` | ![Context](https://img.shields.io/badge/Context-8E44AD?style=flat) | Visualize daily usage, session history, streaks, and model preferences | +| `/usage` | ![Context](https://img.shields.io/badge/Context-8E44AD?style=flat) | Show plan usage limits and rate limit status (subscription plans only) | +| `/fast` | ![Model](https://img.shields.io/badge/Model-E67E22?style=flat) | Toggle fast mode — same Opus 4.6 model with faster output | +| `/model` | ![Model](https://img.shields.io/badge/Model-E67E22?style=flat) | Switch models (haiku, sonnet, opus) and adjust effort level | +| `/plan` | ![Model](https://img.shields.io/badge/Model-E67E22?style=flat) | Enter read-only planning mode — suggests approaches without making changes | +| `/init` | ![Project](https://img.shields.io/badge/Project-27AE60?style=flat) | Initialize a new project with CLAUDE.md guide | +| `/memory` | ![Memory](https://img.shields.io/badge/Memory-3498DB?style=flat) | View and edit CLAUDE.md memory files (user, project, and local scope) | +| `/config` | ![Config](https://img.shields.io/badge/Config-F39C12?style=flat) | Open the interactive Settings interface with search functionality | +| `/keybindings` | ![Config](https://img.shields.io/badge/Config-F39C12?style=flat) | Customize keyboard shortcuts per context, create chord sequences | +| `/permissions` | ![Config](https://img.shields.io/badge/Config-F39C12?style=flat) | View or update tool permissions | +| `/sandbox` | ![Config](https://img.shields.io/badge/Config-F39C12?style=flat) | Configure sandboxing with dependency status | +| `/statusline` | ![Config](https://img.shields.io/badge/Config-F39C12?style=flat) | Set up Claude Code's status line UI | +| `/terminal-setup` | ![Config](https://img.shields.io/badge/Config-F39C12?style=flat) | Enable shift+enter for newlines in IDE terminals | +| `/theme` | ![Config](https://img.shields.io/badge/Config-F39C12?style=flat) | Change the color theme | +| `/vim` | ![Config](https://img.shields.io/badge/Config-F39C12?style=flat) | Enable vim-style editing mode | +| `/agents` | ![Extensions](https://img.shields.io/badge/Extensions-16A085?style=flat) | Manage custom subagents — view, create, edit, delete | +| `/hooks` | ![Extensions](https://img.shields.io/badge/Extensions-16A085?style=flat) | Interactive interface to manage hooks | +| `/ide` | ![Extensions](https://img.shields.io/badge/Extensions-16A085?style=flat) | Connect to IDE integration | +| `/mcp` | ![Extensions](https://img.shields.io/badge/Extensions-16A085?style=flat) | Manage MCP server connections — add, enable, list, get info, OAuth | +| `/plugin` | ![Extensions](https://img.shields.io/badge/Extensions-16A085?style=flat) | Manage plugins — install, uninstall, enable, disable, browse marketplaces | +| `/skills` | ![Extensions](https://img.shields.io/badge/Extensions-16A085?style=flat) | View available skills and their descriptions | +| `/debug [description]` | ![Debug](https://img.shields.io/badge/Debug-E74C3C?style=flat) | Troubleshoot the current session by reading the debug log | +| `/doctor` | ![Debug](https://img.shields.io/badge/Debug-E74C3C?style=flat) | Check the health of your Claude Code installation | +| `/feedback` | ![Debug](https://img.shields.io/badge/Debug-E74C3C?style=flat) | Generate a GitHub issue URL for reporting bugs or feedback | +| `/help` | ![Debug](https://img.shields.io/badge/Debug-E74C3C?style=flat) | Show all available slash commands and usage help | +| `/tasks` | ![Debug](https://img.shields.io/badge/Debug-E74C3C?style=flat) | List and manage background tasks | +| `/todos` | ![Debug](https://img.shields.io/badge/Debug-E74C3C?style=flat) | List current TODO items | +| `/copy` | ![Export](https://img.shields.io/badge/Export-7F8C8D?style=flat) | Copy the last assistant response to clipboard | +| `/export [filename]` | ![Export](https://img.shields.io/badge/Export-7F8C8D?style=flat) | Export the current conversation to a file or clipboard | +| `/login` | ![Auth](https://img.shields.io/badge/Auth-2980B9?style=flat) | Authenticate with Claude Code via OAuth | +| `/logout` | ![Auth](https://img.shields.io/badge/Auth-2980B9?style=flat) | Log out from Claude Code | -| 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 | +### Commands in This Repository -### Text Editing +Custom commands defined in `.claude/commands/` for this project: -| 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 | +| Command | Description | Model | +|---------|-------------|-------| +| [`weather-orchestrator`](../.claude/commands/weather-orchestrator.md) | Fetch and transform weather data for Karachi | haiku | +| [`workflows/best-practice/workflow-claude-subagents`](../.claude/commands/workflows/best-practice/workflow-claude-subagents.md) | Track Claude Code subagents report changes and find what needs updating | — | --- ## 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 Interactive Mode](https://code.claude.com/docs/en/interactive-mode) - [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) diff --git a/best-practice/claude-skills-frontmatter.md b/best-practice/claude-skills-frontmatter.md deleted file mode 100644 index 0ad3a66..0000000 --- a/best-practice/claude-skills-frontmatter.md +++ /dev/null @@ -1,189 +0,0 @@ -# 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/best-practice/claude-subagents.md b/best-practice/claude-subagents.md index 19ddd49..57dd329 100644 --- a/best-practice/claude-subagents.md +++ b/best-practice/claude-subagents.md @@ -162,7 +162,7 @@ Custom agents defined in `.claude/agents/` for this project: |-------|-------|-------|-------|--------|--------| | [`presentation-curator`](../.claude/agents/presentation-curator.md) | sonnet | magenta | Read, Write, Edit, Grep, Glob | presentation/vibe-to-agentic-framework, presentation/presentation-structure, presentation/presentation-styling | — | | [`weather`](../.claude/agents/weather.md) | sonnet | green | WebFetch, Read, Write | weather-fetcher, weather-transformer | project | -| [`workflow-changelog-claude-subagents-agent`](../.claude/agents/workflows/reports/workflow-changelog-claude-subagents-agent.md) | opus | blue | All (inherited) | — | — | +| [`workflow-claude-subagents-agent`](../.claude/agents/workflows/best-practice/workflow-claude-subagents-agent.md) | opus | blue | All (inherited) | — | — | --- diff --git a/implementation/claude-subagents-implementation.md b/implementation/claude-subagents-implementation.md index 0c13049..3dd2601 100644 --- a/implementation/claude-subagents-implementation.md +++ b/implementation/claude-subagents-implementation.md @@ -76,7 +76,7 @@ $ claude The weather agent is the **Agent** in the Command → Agent → Skills orchestration pattern. It receives the workflow from the `/weather-orchestrator` command and executes it using two preloaded skills (`weather-fetcher`, `weather-transformer`) within a single execution context.

- Command Skill Agent Architecture Flow + Command Skill Agent Architecture Flow

| Component | Role | This Repo | diff --git a/reports/claude-commands-frontmatter.md b/reports/claude-commands-frontmatter.md deleted file mode 100644 index b73dac6..0000000 --- a/reports/claude-commands-frontmatter.md +++ /dev/null @@ -1,99 +0,0 @@ -# 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](../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](../best-practice/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)