mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-06-10 10:43:54 +02:00
docs: Update slash commands documentation with official features
- Add comprehensive built-in commands reference (40+ commands) - Document argument handling ($ARGUMENTS, $1, $2, etc.) - Add bash execution syntax (! prefix) and file references (@ prefix) - Update frontmatter to official fields (allowed-tools, argument-hint, model, etc.) - Add Plugin Commands and MCP Slash Commands sections - Add SlashCommand Tool documentation for programmatic invocation - Add Skills vs Slash Commands comparison table - Create commit.md example with bash execution and context - Update existing examples to use official frontmatter format - Add OpenSpec proposal for change tracking
This commit is contained in:
Luong NGUYEN
+304
-232
@@ -4,7 +4,254 @@
|
||||
|
||||
## Overview
|
||||
|
||||
Slash commands are user-invoked shortcuts stored as Markdown files that Claude Code can execute. They enable teams to standardize frequently-used prompts and workflows.
|
||||
Slash commands are tools that control Claude's behavior during an interactive session. They enable teams to standardize frequently-used prompts and workflows, and come in several types with different capabilities.
|
||||
|
||||
## Types of Slash Commands
|
||||
|
||||
| Type | Description | Example |
|
||||
|------|-------------|---------|
|
||||
| **Built-in** | Commands provided by Claude Code | `/help`, `/clear`, `/model` |
|
||||
| **Custom** | User-defined Markdown files | `/optimize`, `/pr` |
|
||||
| **Plugin** | Commands from installed plugins | `/frontend-design:frontend-design` |
|
||||
| **MCP** | Commands from MCP servers | `/mcp__github__list_prs` |
|
||||
|
||||
## Built-in Commands Reference
|
||||
|
||||
Claude Code provides these built-in slash commands:
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/add-dir` | Add additional working directories |
|
||||
| `/agents` | Manage custom AI subagents for specialized tasks |
|
||||
| `/bashes` | List and manage background tasks |
|
||||
| `/bug` | Report bugs (sends conversation to Anthropic) |
|
||||
| `/clear` | Clear conversation history |
|
||||
| `/compact [instructions]` | Compact conversation with optional focus instructions |
|
||||
| `/config` | Open the Settings interface (Config tab) |
|
||||
| `/context` | Visualize current context usage as a colored grid |
|
||||
| `/cost` | Show token usage statistics |
|
||||
| `/doctor` | Checks the health of your Claude Code installation |
|
||||
| `/exit` | Exit the REPL |
|
||||
| `/export [filename]` | Export the current conversation to a file or clipboard |
|
||||
| `/help` | Get usage help |
|
||||
| `/hooks` | Manage hook configurations for tool events |
|
||||
| `/ide` | Manage IDE integrations and show status |
|
||||
| `/init` | Initialize project with `CLAUDE.md` guide |
|
||||
| `/install-github-app` | Set up Claude GitHub Actions for a repository |
|
||||
| `/login` | Switch Anthropic accounts |
|
||||
| `/logout` | Sign out from your Anthropic account |
|
||||
| `/mcp` | Manage MCP server connections and OAuth authentication |
|
||||
| `/memory` | Edit `CLAUDE.md` memory files |
|
||||
| `/model` | Select or change the AI model |
|
||||
| `/output-style [style]` | Set the output style directly or from a selection menu |
|
||||
| `/permissions` | View or update permissions |
|
||||
| `/plugin` | Manage Claude Code plugins |
|
||||
| `/pr-comments` | View pull request comments |
|
||||
| `/privacy-settings` | View and update your privacy settings |
|
||||
| `/release-notes` | View release notes |
|
||||
| `/rename <name>` | Rename the current session |
|
||||
| `/resume [session]` | Resume a conversation by ID or name |
|
||||
| `/review` | Request code review |
|
||||
| `/rewind` | Rewind the conversation and/or code |
|
||||
| `/sandbox` | Enable sandboxed bash tool with filesystem and network isolation |
|
||||
| `/security-review` | Complete a security review of pending changes |
|
||||
| `/stats` | Visualize daily usage, session history, streaks, and model preferences |
|
||||
| `/status` | Open the Settings interface (Status tab) |
|
||||
| `/statusline` | Set up Claude Code's status line UI |
|
||||
| `/terminal-setup` | Install Shift+Enter key binding for newlines |
|
||||
| `/todos` | List current TODO items |
|
||||
| `/usage` | Show plan usage limits and rate limit status |
|
||||
| `/vim` | Enter vim mode for alternating insert and command modes |
|
||||
|
||||
## Custom Slash Commands
|
||||
|
||||
Custom slash commands allow you to define frequently used prompts as Markdown files that Claude Code can execute.
|
||||
|
||||
### File Locations
|
||||
|
||||
| Location | Scope | Label in `/help` | Use Case |
|
||||
|----------|-------|------------------|----------|
|
||||
| `.claude/commands/` | Project-specific | `(project)` | Team workflows, shared standards |
|
||||
| `~/.claude/commands/` | Personal | `(user)` | Personal shortcuts across projects |
|
||||
|
||||
**Priority:** Project commands take precedence over personal commands with the same name.
|
||||
|
||||
### Namespacing with Subdirectories
|
||||
|
||||
Use subdirectories to group related commands:
|
||||
|
||||
```
|
||||
.claude/commands/
|
||||
├── frontend/
|
||||
│ └── component.md → /component (project:frontend)
|
||||
├── deploy/
|
||||
│ ├── production.md → /production (project:deploy)
|
||||
│ └── staging.md → /staging (project:deploy)
|
||||
└── optimize.md → /optimize (project)
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
Commands can receive arguments in two ways:
|
||||
|
||||
**All arguments with `$ARGUMENTS`:**
|
||||
|
||||
```markdown
|
||||
# .claude/commands/fix-issue.md
|
||||
Fix issue #$ARGUMENTS following our coding standards
|
||||
```
|
||||
|
||||
Usage: `/fix-issue 123 high-priority` → `$ARGUMENTS` becomes "123 high-priority"
|
||||
|
||||
**Individual arguments with `$1`, `$2`, etc.:**
|
||||
|
||||
```markdown
|
||||
# .claude/commands/review-pr.md
|
||||
Review PR #$1 with priority $2 and assign to $3
|
||||
```
|
||||
|
||||
Usage: `/review-pr 456 high alice` → `$1`="456", `$2`="high", `$3`="alice"
|
||||
|
||||
### Bash Command Execution
|
||||
|
||||
Execute bash commands before the slash command runs using the `!` prefix:
|
||||
|
||||
```markdown
|
||||
---
|
||||
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
|
||||
description: Create a git commit
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
- Current git status: !`git status`
|
||||
- Current git diff: !`git diff HEAD`
|
||||
- Current branch: !`git branch --show-current`
|
||||
- Recent commits: !`git log --oneline -10`
|
||||
|
||||
## Your task
|
||||
|
||||
Based on the above changes, create a single git commit.
|
||||
```
|
||||
|
||||
### File References
|
||||
|
||||
Include file contents in commands using the `@` prefix:
|
||||
|
||||
```markdown
|
||||
# Reference a specific file
|
||||
Review the implementation in @src/utils/helpers.js
|
||||
|
||||
# Reference multiple files
|
||||
Compare @src/old-version.js with @src/new-version.js
|
||||
```
|
||||
|
||||
### Thinking Mode
|
||||
|
||||
Slash commands can trigger extended thinking by including extended thinking keywords in the command content.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
Command files support YAML frontmatter for configuration:
|
||||
|
||||
```markdown
|
||||
---
|
||||
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
|
||||
argument-hint: [message]
|
||||
description: Create a git commit
|
||||
model: claude-3-5-haiku-20241022
|
||||
---
|
||||
|
||||
Create a git commit with message: $ARGUMENTS
|
||||
```
|
||||
|
||||
### Frontmatter Fields
|
||||
|
||||
| Field | Purpose | Default |
|
||||
|-------|---------|---------|
|
||||
| `allowed-tools` | List of tools the command can use | Inherits from conversation |
|
||||
| `argument-hint` | Expected arguments for auto-completion | None |
|
||||
| `description` | Brief description of the command | Uses first line from prompt |
|
||||
| `model` | Specific model to use | Inherits from conversation |
|
||||
| `disable-model-invocation` | Prevent SlashCommand tool from calling this | `false` |
|
||||
|
||||
## Plugin Commands
|
||||
|
||||
Plugins can provide custom slash commands that integrate with Claude Code:
|
||||
|
||||
```
|
||||
/plugin-name:command-name
|
||||
```
|
||||
|
||||
Or simply `/command-name` when there are no naming conflicts.
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
/frontend-design:frontend-design
|
||||
/commit-commands:commit
|
||||
/code-review:code-review
|
||||
```
|
||||
|
||||
## MCP Slash Commands
|
||||
|
||||
MCP servers can expose prompts as slash commands:
|
||||
|
||||
```
|
||||
/mcp__<server-name>__<prompt-name> [arguments]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
/mcp__github__list_prs
|
||||
/mcp__github__pr_review 456
|
||||
/mcp__jira__create_issue "Bug title" high
|
||||
```
|
||||
|
||||
## SlashCommand Tool
|
||||
|
||||
Claude can programmatically invoke custom slash commands using the SlashCommand tool.
|
||||
|
||||
### Enabling Programmatic Invocation
|
||||
|
||||
Reference the command in your prompt or `CLAUDE.md`:
|
||||
|
||||
```markdown
|
||||
> Run /write-unit-test when you are about to start writing tests.
|
||||
```
|
||||
|
||||
### Disabling for Specific Commands
|
||||
|
||||
Use the `disable-model-invocation` frontmatter field:
|
||||
|
||||
```markdown
|
||||
---
|
||||
disable-model-invocation: true
|
||||
---
|
||||
```
|
||||
|
||||
Or disable via permissions:
|
||||
```
|
||||
/permissions
|
||||
# Add to deny rules: SlashCommand
|
||||
```
|
||||
|
||||
### Character Budget
|
||||
|
||||
- **Default limit:** 15,000 characters
|
||||
- **Custom limit:** Set via `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable
|
||||
|
||||
## Skills vs Slash Commands
|
||||
|
||||
| Aspect | Slash Commands | Skills |
|
||||
|--------|----------------|--------|
|
||||
| **Best for** | Quick, frequently used prompts | Comprehensive capabilities with structure |
|
||||
| **Files** | Single `.md` file | Directory with `SKILL.md` + resources |
|
||||
| **Invocation** | Explicit (`/command`) | Automatic (context-based) |
|
||||
| **Complexity** | Simple prompts | Complex workflows with multiple steps |
|
||||
|
||||
**Use slash commands** when you invoke the same prompt repeatedly and it fits in a single file.
|
||||
|
||||
**Use skills** when Claude should discover the capability automatically or multiple files/scripts are needed.
|
||||
|
||||
## Architecture
|
||||
|
||||
@@ -17,48 +264,26 @@ graph TD
|
||||
E -->|Returns| F["Result in Context"]
|
||||
```
|
||||
|
||||
## File Structure
|
||||
## Command Lifecycle Diagram
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A["Project Root"] -->|contains| B[".claude/commands/"]
|
||||
B -->|contains| C["optimize.md"]
|
||||
B -->|contains| D["test.md"]
|
||||
B -->|contains| E["docs/"]
|
||||
E -->|contains| F["generate-api-docs.md"]
|
||||
E -->|contains| G["generate-readme.md"]
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant Claude as Claude Code
|
||||
participant FS as File System
|
||||
participant CLI as Shell/Bash
|
||||
|
||||
User->>Claude: Types /optimize
|
||||
Claude->>FS: Searches .claude/commands/
|
||||
FS-->>Claude: Returns optimize.md
|
||||
Claude->>Claude: Loads Markdown content
|
||||
Claude->>User: Displays prompt context
|
||||
User->>Claude: Provides code to analyze
|
||||
Claude->>CLI: (May execute scripts)
|
||||
CLI-->>Claude: Results
|
||||
Claude->>User: Returns analysis
|
||||
```
|
||||
|
||||
### Recommended Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── .claude/
|
||||
│ └── commands/
|
||||
│ ├── optimize.md
|
||||
│ ├── pr.md
|
||||
│ └── docs/
|
||||
│ └── generate-api-docs.md
|
||||
```
|
||||
|
||||
## Command Organization Table
|
||||
|
||||
| Location | Scope | Availability | Use Case | Git Tracked |
|
||||
|----------|-------|--------------|----------|-------------|
|
||||
| `.claude/commands/` | Project-specific | Team members | Team workflows, shared standards | ✅ Yes |
|
||||
| `~/.claude/commands/` | Personal | Individual user | Personal shortcuts across projects | ❌ No |
|
||||
| Subdirectories | Namespaced | Based on parent | Organize by category | ✅ Yes |
|
||||
|
||||
## Features & Capabilities
|
||||
|
||||
| Feature | Example | Supported |
|
||||
|---------|---------|-----------|
|
||||
| Shell script execution | `bash scripts/deploy.sh` | ✅ Yes |
|
||||
| File references | `@path/to/file.js` | ✅ Yes |
|
||||
| Bash integration | `$(git log --oneline)` | ✅ Yes |
|
||||
| Arguments | `/pr --verbose` | ✅ Yes |
|
||||
| MCP commands | `/mcp__github__list_prs` | ✅ Yes |
|
||||
|
||||
## Available Commands in This Folder
|
||||
|
||||
### 1. `/optimize` - Code Optimization
|
||||
@@ -112,25 +337,18 @@ Generates comprehensive API documentation from source code.
|
||||
- Includes request/response schemas
|
||||
- Adds error documentation
|
||||
|
||||
## Command Lifecycle Diagram
|
||||
### 4. `/commit` - Git Commit with Context
|
||||
Creates a git commit with dynamic context from your repository.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant Claude as Claude Code
|
||||
participant FS as File System
|
||||
participant CLI as Shell/Bash
|
||||
|
||||
User->>Claude: Types /optimize
|
||||
Claude->>FS: Searches .claude/commands/
|
||||
FS-->>Claude: Returns optimize.md
|
||||
Claude->>Claude: Loads Markdown content
|
||||
Claude->>User: Displays prompt context
|
||||
User->>Claude: Provides code to analyze
|
||||
Claude->>CLI: (May execute scripts)
|
||||
CLI-->>Claude: Results
|
||||
Claude->>User: Returns analysis
|
||||
**Usage:**
|
||||
```
|
||||
/commit [optional message]
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Automatically includes git status, diff, and recent commits
|
||||
- Uses `allowed-tools` for git operations
|
||||
- Supports optional commit message argument
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -144,9 +362,6 @@ mkdir -p .claude/commands
|
||||
|
||||
# Copy command files
|
||||
cp 01-slash-commands/*.md .claude/commands/
|
||||
|
||||
# Copy subdirectory commands
|
||||
cp -r 01-slash-commands/docs .claude/commands/
|
||||
```
|
||||
|
||||
### For Personal Use
|
||||
@@ -169,9 +384,8 @@ Create a file `.claude/commands/my-command.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: My Command Name
|
||||
description: What this command does
|
||||
tags: category, task-type
|
||||
argument-hint: [optional-args]
|
||||
---
|
||||
|
||||
# Command Title
|
||||
@@ -187,184 +401,42 @@ Output format:
|
||||
- What to include
|
||||
```
|
||||
|
||||
### Command with Frontmatter
|
||||
### Command with Full Frontmatter
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Code Optimization
|
||||
description: Analyze code for performance issues and suggest optimizations
|
||||
tags: performance, analysis
|
||||
---
|
||||
|
||||
# Code Optimization
|
||||
|
||||
Review the provided code for the following issues in order of priority:
|
||||
|
||||
1. **Performance bottlenecks** - identify O(n²) operations, inefficient loops
|
||||
2. **Memory leaks** - find unreleased resources, circular references
|
||||
3. **Algorithm improvements** - suggest better algorithms or data structures
|
||||
|
||||
Format your response with:
|
||||
- Issue severity (Critical/High/Medium/Low)
|
||||
- Location in code
|
||||
- Explanation
|
||||
- Recommended fix with code example
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
| ✅ Do | ❌ Don't |
|
||||
|------|---------|
|
||||
| Use clear, action-oriented names | Create commands for one-time tasks |
|
||||
| Document trigger words in description | Build complex logic in commands |
|
||||
| Keep commands focused on single task | Create redundant commands |
|
||||
| Version control project commands | Hardcode sensitive information |
|
||||
| Organize in subdirectories | Create long lists of commands |
|
||||
| Use simple, readable prompts | Use abbreviated or cryptic wording |
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Simple Task Automation
|
||||
|
||||
**File:** `.claude/commands/test.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Run Tests
|
||||
description: Execute test suite with coverage report
|
||||
allowed-tools: Bash(npm test:*), Bash(npm run lint:*)
|
||||
argument-hint: [--verbose] [--coverage]
|
||||
description: Run tests with optional coverage report
|
||||
model: claude-3-5-haiku-20241022
|
||||
---
|
||||
|
||||
# Test Runner
|
||||
|
||||
1. Run the test suite: `npm test`
|
||||
2. Generate coverage report
|
||||
3. Summarize results
|
||||
4. Highlight any failures
|
||||
Run the project tests with the following options:
|
||||
- Arguments provided: $ARGUMENTS
|
||||
|
||||
## Context
|
||||
- Current branch: !`git branch --show-current`
|
||||
- Package.json scripts: @package.json
|
||||
|
||||
## Steps
|
||||
1. Run `npm test`
|
||||
2. If --coverage flag provided, generate coverage report
|
||||
3. Summarize results and highlight any failures
|
||||
```
|
||||
|
||||
### Example 2: Multi-step Workflow
|
||||
## Best Practices
|
||||
|
||||
**File:** `.claude/commands/deploy.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Deploy to Production
|
||||
description: Complete deployment workflow with checks
|
||||
---
|
||||
|
||||
# Production Deployment
|
||||
|
||||
Execute these steps in order:
|
||||
|
||||
1. **Pre-deployment checks**
|
||||
- Run `npm run lint`
|
||||
- Run `npm test`
|
||||
- Check git status is clean
|
||||
|
||||
2. **Build**
|
||||
- Run `npm run build`
|
||||
- Verify build artifacts
|
||||
|
||||
3. **Deploy**
|
||||
- Run `npm run deploy`
|
||||
- Monitor deployment logs
|
||||
|
||||
4. **Post-deployment**
|
||||
- Run smoke tests
|
||||
- Verify deployment
|
||||
- Notify team
|
||||
```
|
||||
|
||||
### Example 3: Code Review Command
|
||||
|
||||
**File:** `.claude/commands/review.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Code Review
|
||||
description: Comprehensive code review checklist
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Review the code for:
|
||||
|
||||
## Security
|
||||
- [ ] No hardcoded credentials
|
||||
- [ ] Input validation present
|
||||
- [ ] SQL injection prevention
|
||||
- [ ] XSS prevention
|
||||
|
||||
## Performance
|
||||
- [ ] No N+1 queries
|
||||
- [ ] Appropriate indexing
|
||||
- [ ] Efficient algorithms
|
||||
|
||||
## Quality
|
||||
- [ ] Clear naming
|
||||
- [ ] Proper error handling
|
||||
- [ ] Adequate comments
|
||||
- [ ] No code duplication
|
||||
```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Using Arguments
|
||||
|
||||
Commands can accept arguments:
|
||||
|
||||
```bash
|
||||
/deploy production
|
||||
/review --verbose
|
||||
/test --coverage
|
||||
```
|
||||
|
||||
Handle arguments in your command file:
|
||||
|
||||
```markdown
|
||||
# Deployment Command
|
||||
|
||||
Check the provided argument for environment:
|
||||
- If "production", use strict checks
|
||||
- If "staging", allow warnings
|
||||
- If "development", skip certain validations
|
||||
```
|
||||
|
||||
### Integrating with MCP
|
||||
|
||||
Commands can use MCP tools:
|
||||
|
||||
```markdown
|
||||
# GitHub PR Command
|
||||
|
||||
1. Use MCP to list open PRs: `/mcp__github__list_prs`
|
||||
2. Analyze each PR for:
|
||||
- Review status
|
||||
- CI/CD status
|
||||
- Merge conflicts
|
||||
3. Provide summary
|
||||
```
|
||||
|
||||
### Hierarchical Commands
|
||||
|
||||
Organize related commands in subdirectories:
|
||||
|
||||
```
|
||||
.claude/commands/
|
||||
├── deploy/
|
||||
│ ├── production.md
|
||||
│ ├── staging.md
|
||||
│ └── rollback.md
|
||||
├── test/
|
||||
│ ├── unit.md
|
||||
│ ├── integration.md
|
||||
│ └── e2e.md
|
||||
└── docs/
|
||||
├── api.md
|
||||
└── readme.md
|
||||
```
|
||||
|
||||
Access with: `/deploy/production`, `/test/unit`, `/docs/api`
|
||||
| Do | Don't |
|
||||
|------|---------|
|
||||
| Use clear, action-oriented names | Create commands for one-time tasks |
|
||||
| Include `description` in frontmatter | Build complex logic in commands |
|
||||
| Keep commands focused on single task | Create redundant commands |
|
||||
| Version control project commands | Hardcode sensitive information |
|
||||
| Organize in subdirectories | Create long lists of commands |
|
||||
| Use `$ARGUMENTS` or `$1`, `$2` for dynamic input | Use abbreviated or cryptic wording |
|
||||
| Use `!` prefix for dynamic context | Assume Claude knows current state |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -387,6 +459,7 @@ Access with: `/deploy/production`, `/test/unit`, `/docs/api`
|
||||
- Add more specific instructions
|
||||
- Include examples in command file
|
||||
- Test with simple inputs first
|
||||
- Check `allowed-tools` if using bash commands
|
||||
|
||||
### Personal vs Project Commands
|
||||
|
||||
@@ -411,10 +484,9 @@ Access with: `/deploy/production`, `/test/unit`, `/docs/api`
|
||||
|
||||
## Resources
|
||||
|
||||
- [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29) - Comprehensive blog post exploring slash commands
|
||||
- [Claude Code Commands Documentation](https://docs.claude.com/en/docs/claude-code/custom-commands)
|
||||
- [Claude Code Slash Commands Documentation](https://code.claude.com/docs/en/slash-commands) - Official documentation
|
||||
- [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29) - Comprehensive blog post
|
||||
- [Markdown Guide](https://www.markdownguide.org/)
|
||||
- [Command Examples Repository](https://github.com/anthropics/claude-code-examples)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*)
|
||||
argument-hint: [message]
|
||||
description: Create a git commit with context
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
- Current git status: !`git status`
|
||||
- Current git diff: !`git diff HEAD`
|
||||
- Current branch: !`git branch --show-current`
|
||||
- Recent commits: !`git log --oneline -10`
|
||||
|
||||
## Your task
|
||||
|
||||
Based on the above changes, create a single git commit.
|
||||
|
||||
If a message was provided via arguments, use it: $ARGUMENTS
|
||||
|
||||
Otherwise, analyze the changes and create an appropriate commit message following conventional commits format:
|
||||
- `feat:` for new features
|
||||
- `fix:` for bug fixes
|
||||
- `docs:` for documentation changes
|
||||
- `refactor:` for code refactoring
|
||||
- `test:` for adding tests
|
||||
- `chore:` for maintenance tasks
|
||||
@@ -1,7 +1,5 @@
|
||||
---
|
||||
name: Generate API Documentation
|
||||
description: Create comprehensive API documentation from source code
|
||||
tags: documentation, api
|
||||
---
|
||||
|
||||
# API Documentation Generator
|
||||
|
||||
@@ -1,7 +1,5 @@
|
||||
---
|
||||
name: Code Optimization
|
||||
description: Analyze code for performance issues and suggest optimizations
|
||||
tags: performance, analysis
|
||||
---
|
||||
|
||||
# Code Optimization
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: Prepare Pull Request
|
||||
description: Clean up code, stage changes, and prepare a pull request
|
||||
tags: git, workflow
|
||||
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(npm test:*), Bash(npm run lint:*)
|
||||
---
|
||||
|
||||
# Pull Request Preparation Checklist
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: Commit and push everything
|
||||
description: Stage all changes, create commit, and push to remote (use with caution)
|
||||
tags: git, workflow, automation
|
||||
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git push:*), Bash(git diff:*), Bash(git log:*), Bash(git pull:*)
|
||||
---
|
||||
|
||||
# Commit and Push Everything
|
||||
|
||||
@@ -0,0 +1,456 @@
|
||||
# OpenSpec Instructions
|
||||
|
||||
Instructions for AI coding assistants using OpenSpec for spec-driven development.
|
||||
|
||||
## TL;DR Quick Checklist
|
||||
|
||||
- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search)
|
||||
- Decide scope: new capability vs modify existing capability
|
||||
- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`)
|
||||
- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability
|
||||
- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement
|
||||
- Validate: `openspec validate [change-id] --strict` and fix issues
|
||||
- Request approval: Do not start implementation until proposal is approved
|
||||
|
||||
## Three-Stage Workflow
|
||||
|
||||
### Stage 1: Creating Changes
|
||||
Create proposal when you need to:
|
||||
- Add features or functionality
|
||||
- Make breaking changes (API, schema)
|
||||
- Change architecture or patterns
|
||||
- Optimize performance (changes behavior)
|
||||
- Update security patterns
|
||||
|
||||
Triggers (examples):
|
||||
- "Help me create a change proposal"
|
||||
- "Help me plan a change"
|
||||
- "Help me create a proposal"
|
||||
- "I want to create a spec proposal"
|
||||
- "I want to create a spec"
|
||||
|
||||
Loose matching guidance:
|
||||
- Contains one of: `proposal`, `change`, `spec`
|
||||
- With one of: `create`, `plan`, `make`, `start`, `help`
|
||||
|
||||
Skip proposal for:
|
||||
- Bug fixes (restore intended behavior)
|
||||
- Typos, formatting, comments
|
||||
- Dependency updates (non-breaking)
|
||||
- Configuration changes
|
||||
- Tests for existing behavior
|
||||
|
||||
**Workflow**
|
||||
1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context.
|
||||
2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes/<id>/`.
|
||||
3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.
|
||||
4. Run `openspec validate <id> --strict` and resolve any issues before sharing the proposal.
|
||||
|
||||
### Stage 2: Implementing Changes
|
||||
Track these steps as TODOs and complete them one by one.
|
||||
1. **Read proposal.md** - Understand what's being built
|
||||
2. **Read design.md** (if exists) - Review technical decisions
|
||||
3. **Read tasks.md** - Get implementation checklist
|
||||
4. **Implement tasks sequentially** - Complete in order
|
||||
5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses
|
||||
6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality
|
||||
7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved
|
||||
|
||||
### Stage 3: Archiving Changes
|
||||
After deployment, create separate PR to:
|
||||
- Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
|
||||
- Update `specs/` if capabilities changed
|
||||
- Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly)
|
||||
- Run `openspec validate --strict` to confirm the archived change passes checks
|
||||
|
||||
## Before Any Task
|
||||
|
||||
**Context Checklist:**
|
||||
- [ ] Read relevant specs in `specs/[capability]/spec.md`
|
||||
- [ ] Check pending changes in `changes/` for conflicts
|
||||
- [ ] Read `openspec/project.md` for conventions
|
||||
- [ ] Run `openspec list` to see active changes
|
||||
- [ ] Run `openspec list --specs` to see existing capabilities
|
||||
|
||||
**Before Creating Specs:**
|
||||
- Always check if capability already exists
|
||||
- Prefer modifying existing specs over creating duplicates
|
||||
- Use `openspec show [spec]` to review current state
|
||||
- If request is ambiguous, ask 1–2 clarifying questions before scaffolding
|
||||
|
||||
### Search Guidance
|
||||
- Enumerate specs: `openspec spec list --long` (or `--json` for scripts)
|
||||
- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available)
|
||||
- Show details:
|
||||
- Spec: `openspec show <spec-id> --type spec` (use `--json` for filters)
|
||||
- Change: `openspec show <change-id> --json --deltas-only`
|
||||
- Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs`
|
||||
|
||||
## Quick Start
|
||||
|
||||
### CLI Commands
|
||||
|
||||
```bash
|
||||
# Essential commands
|
||||
openspec list # List active changes
|
||||
openspec list --specs # List specifications
|
||||
openspec show [item] # Display change or spec
|
||||
openspec validate [item] # Validate changes or specs
|
||||
openspec archive <change-id> [--yes|-y] # Archive after deployment (add --yes for non-interactive runs)
|
||||
|
||||
# Project management
|
||||
openspec init [path] # Initialize OpenSpec
|
||||
openspec update [path] # Update instruction files
|
||||
|
||||
# Interactive mode
|
||||
openspec show # Prompts for selection
|
||||
openspec validate # Bulk validation mode
|
||||
|
||||
# Debugging
|
||||
openspec show [change] --json --deltas-only
|
||||
openspec validate [change] --strict
|
||||
```
|
||||
|
||||
### Command Flags
|
||||
|
||||
- `--json` - Machine-readable output
|
||||
- `--type change|spec` - Disambiguate items
|
||||
- `--strict` - Comprehensive validation
|
||||
- `--no-interactive` - Disable prompts
|
||||
- `--skip-specs` - Archive without spec updates
|
||||
- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive)
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
openspec/
|
||||
├── project.md # Project conventions
|
||||
├── specs/ # Current truth - what IS built
|
||||
│ └── [capability]/ # Single focused capability
|
||||
│ ├── spec.md # Requirements and scenarios
|
||||
│ └── design.md # Technical patterns
|
||||
├── changes/ # Proposals - what SHOULD change
|
||||
│ ├── [change-name]/
|
||||
│ │ ├── proposal.md # Why, what, impact
|
||||
│ │ ├── tasks.md # Implementation checklist
|
||||
│ │ ├── design.md # Technical decisions (optional; see criteria)
|
||||
│ │ └── specs/ # Delta changes
|
||||
│ │ └── [capability]/
|
||||
│ │ └── spec.md # ADDED/MODIFIED/REMOVED
|
||||
│ └── archive/ # Completed changes
|
||||
```
|
||||
|
||||
## Creating Change Proposals
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```
|
||||
New request?
|
||||
├─ Bug fix restoring spec behavior? → Fix directly
|
||||
├─ Typo/format/comment? → Fix directly
|
||||
├─ New feature/capability? → Create proposal
|
||||
├─ Breaking change? → Create proposal
|
||||
├─ Architecture change? → Create proposal
|
||||
└─ Unclear? → Create proposal (safer)
|
||||
```
|
||||
|
||||
### Proposal Structure
|
||||
|
||||
1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique)
|
||||
|
||||
2. **Write proposal.md:**
|
||||
```markdown
|
||||
# Change: [Brief description of change]
|
||||
|
||||
## Why
|
||||
[1-2 sentences on problem/opportunity]
|
||||
|
||||
## What Changes
|
||||
- [Bullet list of changes]
|
||||
- [Mark breaking changes with **BREAKING**]
|
||||
|
||||
## Impact
|
||||
- Affected specs: [list capabilities]
|
||||
- Affected code: [key files/systems]
|
||||
```
|
||||
|
||||
3. **Create spec deltas:** `specs/[capability]/spec.md`
|
||||
```markdown
|
||||
## ADDED Requirements
|
||||
### Requirement: New Feature
|
||||
The system SHALL provide...
|
||||
|
||||
#### Scenario: Success case
|
||||
- **WHEN** user performs action
|
||||
- **THEN** expected result
|
||||
|
||||
## MODIFIED Requirements
|
||||
### Requirement: Existing Feature
|
||||
[Complete modified requirement]
|
||||
|
||||
## REMOVED Requirements
|
||||
### Requirement: Old Feature
|
||||
**Reason**: [Why removing]
|
||||
**Migration**: [How to handle]
|
||||
```
|
||||
If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs/<capability>/spec.md`—one per capability.
|
||||
|
||||
4. **Create tasks.md:**
|
||||
```markdown
|
||||
## 1. Implementation
|
||||
- [ ] 1.1 Create database schema
|
||||
- [ ] 1.2 Implement API endpoint
|
||||
- [ ] 1.3 Add frontend component
|
||||
- [ ] 1.4 Write tests
|
||||
```
|
||||
|
||||
5. **Create design.md when needed:**
|
||||
Create `design.md` if any of the following apply; otherwise omit it:
|
||||
- Cross-cutting change (multiple services/modules) or a new architectural pattern
|
||||
- New external dependency or significant data model changes
|
||||
- Security, performance, or migration complexity
|
||||
- Ambiguity that benefits from technical decisions before coding
|
||||
|
||||
Minimal `design.md` skeleton:
|
||||
```markdown
|
||||
## Context
|
||||
[Background, constraints, stakeholders]
|
||||
|
||||
## Goals / Non-Goals
|
||||
- Goals: [...]
|
||||
- Non-Goals: [...]
|
||||
|
||||
## Decisions
|
||||
- Decision: [What and why]
|
||||
- Alternatives considered: [Options + rationale]
|
||||
|
||||
## Risks / Trade-offs
|
||||
- [Risk] → Mitigation
|
||||
|
||||
## Migration Plan
|
||||
[Steps, rollback]
|
||||
|
||||
## Open Questions
|
||||
- [...]
|
||||
```
|
||||
|
||||
## Spec File Format
|
||||
|
||||
### Critical: Scenario Formatting
|
||||
|
||||
**CORRECT** (use #### headers):
|
||||
```markdown
|
||||
#### Scenario: User login success
|
||||
- **WHEN** valid credentials provided
|
||||
- **THEN** return JWT token
|
||||
```
|
||||
|
||||
**WRONG** (don't use bullets or bold):
|
||||
```markdown
|
||||
- **Scenario: User login** ❌
|
||||
**Scenario**: User login ❌
|
||||
### Scenario: User login ❌
|
||||
```
|
||||
|
||||
Every requirement MUST have at least one scenario.
|
||||
|
||||
### Requirement Wording
|
||||
- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)
|
||||
|
||||
### Delta Operations
|
||||
|
||||
- `## ADDED Requirements` - New capabilities
|
||||
- `## MODIFIED Requirements` - Changed behavior
|
||||
- `## REMOVED Requirements` - Deprecated features
|
||||
- `## RENAMED Requirements` - Name changes
|
||||
|
||||
Headers matched with `trim(header)` - whitespace ignored.
|
||||
|
||||
#### When to use ADDED vs MODIFIED
|
||||
- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
|
||||
- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
|
||||
- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
|
||||
|
||||
Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
|
||||
|
||||
Authoring a MODIFIED requirement correctly:
|
||||
1) Locate the existing requirement in `openspec/specs/<capability>/spec.md`.
|
||||
2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).
|
||||
3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.
|
||||
4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.
|
||||
|
||||
Example for RENAMED:
|
||||
```markdown
|
||||
## RENAMED Requirements
|
||||
- FROM: `### Requirement: Login`
|
||||
- TO: `### Requirement: User Authentication`
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Errors
|
||||
|
||||
**"Change must have at least one delta"**
|
||||
- Check `changes/[name]/specs/` exists with .md files
|
||||
- Verify files have operation prefixes (## ADDED Requirements)
|
||||
|
||||
**"Requirement must have at least one scenario"**
|
||||
- Check scenarios use `#### Scenario:` format (4 hashtags)
|
||||
- Don't use bullet points or bold for scenario headers
|
||||
|
||||
**Silent scenario parsing failures**
|
||||
- Exact format required: `#### Scenario: Name`
|
||||
- Debug with: `openspec show [change] --json --deltas-only`
|
||||
|
||||
### Validation Tips
|
||||
|
||||
```bash
|
||||
# Always use strict mode for comprehensive checks
|
||||
openspec validate [change] --strict
|
||||
|
||||
# Debug delta parsing
|
||||
openspec show [change] --json | jq '.deltas'
|
||||
|
||||
# Check specific requirement
|
||||
openspec show [spec] --json -r 1
|
||||
```
|
||||
|
||||
## Happy Path Script
|
||||
|
||||
```bash
|
||||
# 1) Explore current state
|
||||
openspec spec list --long
|
||||
openspec list
|
||||
# Optional full-text search:
|
||||
# rg -n "Requirement:|Scenario:" openspec/specs
|
||||
# rg -n "^#|Requirement:" openspec/changes
|
||||
|
||||
# 2) Choose change id and scaffold
|
||||
CHANGE=add-two-factor-auth
|
||||
mkdir -p openspec/changes/$CHANGE/{specs/auth}
|
||||
printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md
|
||||
printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md
|
||||
|
||||
# 3) Add deltas (example)
|
||||
cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'
|
||||
## ADDED Requirements
|
||||
### Requirement: Two-Factor Authentication
|
||||
Users MUST provide a second factor during login.
|
||||
|
||||
#### Scenario: OTP required
|
||||
- **WHEN** valid credentials are provided
|
||||
- **THEN** an OTP challenge is required
|
||||
EOF
|
||||
|
||||
# 4) Validate
|
||||
openspec validate $CHANGE --strict
|
||||
```
|
||||
|
||||
## Multi-Capability Example
|
||||
|
||||
```
|
||||
openspec/changes/add-2fa-notify/
|
||||
├── proposal.md
|
||||
├── tasks.md
|
||||
└── specs/
|
||||
├── auth/
|
||||
│ └── spec.md # ADDED: Two-Factor Authentication
|
||||
└── notifications/
|
||||
└── spec.md # ADDED: OTP email notification
|
||||
```
|
||||
|
||||
auth/spec.md
|
||||
```markdown
|
||||
## ADDED Requirements
|
||||
### Requirement: Two-Factor Authentication
|
||||
...
|
||||
```
|
||||
|
||||
notifications/spec.md
|
||||
```markdown
|
||||
## ADDED Requirements
|
||||
### Requirement: OTP Email Notification
|
||||
...
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Simplicity First
|
||||
- Default to <100 lines of new code
|
||||
- Single-file implementations until proven insufficient
|
||||
- Avoid frameworks without clear justification
|
||||
- Choose boring, proven patterns
|
||||
|
||||
### Complexity Triggers
|
||||
Only add complexity with:
|
||||
- Performance data showing current solution too slow
|
||||
- Concrete scale requirements (>1000 users, >100MB data)
|
||||
- Multiple proven use cases requiring abstraction
|
||||
|
||||
### Clear References
|
||||
- Use `file.ts:42` format for code locations
|
||||
- Reference specs as `specs/auth/spec.md`
|
||||
- Link related changes and PRs
|
||||
|
||||
### Capability Naming
|
||||
- Use verb-noun: `user-auth`, `payment-capture`
|
||||
- Single purpose per capability
|
||||
- 10-minute understandability rule
|
||||
- Split if description needs "AND"
|
||||
|
||||
### Change ID Naming
|
||||
- Use kebab-case, short and descriptive: `add-two-factor-auth`
|
||||
- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`
|
||||
- Ensure uniqueness; if taken, append `-2`, `-3`, etc.
|
||||
|
||||
## Tool Selection Guide
|
||||
|
||||
| Task | Tool | Why |
|
||||
|------|------|-----|
|
||||
| Find files by pattern | Glob | Fast pattern matching |
|
||||
| Search code content | Grep | Optimized regex search |
|
||||
| Read specific files | Read | Direct file access |
|
||||
| Explore unknown scope | Task | Multi-step investigation |
|
||||
|
||||
## Error Recovery
|
||||
|
||||
### Change Conflicts
|
||||
1. Run `openspec list` to see active changes
|
||||
2. Check for overlapping specs
|
||||
3. Coordinate with change owners
|
||||
4. Consider combining proposals
|
||||
|
||||
### Validation Failures
|
||||
1. Run with `--strict` flag
|
||||
2. Check JSON output for details
|
||||
3. Verify spec file format
|
||||
4. Ensure scenarios properly formatted
|
||||
|
||||
### Missing Context
|
||||
1. Read project.md first
|
||||
2. Check related specs
|
||||
3. Review recent archives
|
||||
4. Ask for clarification
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Stage Indicators
|
||||
- `changes/` - Proposed, not yet built
|
||||
- `specs/` - Built and deployed
|
||||
- `archive/` - Completed changes
|
||||
|
||||
### File Purposes
|
||||
- `proposal.md` - Why and what
|
||||
- `tasks.md` - Implementation steps
|
||||
- `design.md` - Technical decisions
|
||||
- `spec.md` - Requirements and behavior
|
||||
|
||||
### CLI Essentials
|
||||
```bash
|
||||
openspec list # What's in progress?
|
||||
openspec show [item] # View details
|
||||
openspec validate --strict # Is it correct?
|
||||
openspec archive <change-id> [--yes|-y] # Mark complete (add --yes for automation)
|
||||
```
|
||||
|
||||
Remember: Specs are truth. Changes are proposals. Keep them in sync.
|
||||
@@ -0,0 +1,41 @@
|
||||
# Change: Add CLI Reference Lesson
|
||||
|
||||
## Why
|
||||
|
||||
The Claude How To repository covers nine major Claude Code features (01-09), but lacks a dedicated lesson for the CLI reference - the command-line interface that users interact with directly. Understanding CLI commands, flags, and options is fundamental to using Claude Code effectively. Users need a comprehensive reference to leverage features like model selection, output formats, permission management, and session handling via CLI.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **NEW** `10-cli/` directory with comprehensive CLI reference lesson
|
||||
- **NEW** `10-cli/README.md` - Main lesson content following established structure
|
||||
- **UPDATE** Root `README.md` - Add CLI lesson to navigation and learning path
|
||||
- **UPDATE** Root `README.md` - Add CLI to feature comparison and use case matrix
|
||||
- **UPDATE** `LEARNING-ROADMAP.md` - Include CLI lesson in learning progression
|
||||
|
||||
## Key Content Areas
|
||||
|
||||
1. **CLI Commands** - Start interactive REPL, query mode, continue/resume sessions, updates
|
||||
2. **Core Flags** - Print mode, continue, resume, version
|
||||
3. **Model Configuration** - Model selection, fallback models, agent configuration
|
||||
4. **System Prompt Customization** - Replace, append, file-based prompts
|
||||
5. **Tool & Permission Management** - Allowed/disallowed tools, permission modes
|
||||
6. **Output & Format** - JSON, stream-JSON, text formats
|
||||
7. **MCP Configuration** - Server loading, strict mode
|
||||
8. **Session Management** - Session IDs, forking, resumption
|
||||
9. **Advanced Features** - Chrome integration, IDE connection, debug mode
|
||||
|
||||
## High-Value Use Cases
|
||||
|
||||
1. **CI/CD Integration** - Headless mode with JSON output for automation pipelines
|
||||
2. **Script Piping** - Process files, logs, and data through Claude
|
||||
3. **Multi-Session Workflows** - Resume and fork sessions for complex projects
|
||||
4. **Custom Agent Configurations** - Define specialized subagents via CLI
|
||||
5. **Batch Processing** - Process multiple queries with consistent settings
|
||||
6. **Security-Conscious Development** - Permission modes and tool restrictions
|
||||
7. **API Integration** - Structured JSON output for programmatic consumption
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: None (new capability)
|
||||
- Affected code: Root README.md, LEARNING-ROADMAP.md
|
||||
- New files: `10-cli/README.md`
|
||||
@@ -0,0 +1,99 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: CLI Reference Lesson
|
||||
|
||||
The repository SHALL provide a comprehensive CLI reference lesson at `10-cli/` that documents all command-line interface options, flags, and usage patterns for Claude Code.
|
||||
|
||||
#### Scenario: User learns CLI basics
|
||||
- **WHEN** a user navigates to `10-cli/README.md`
|
||||
- **THEN** they find an overview of CLI capabilities with architecture diagram
|
||||
- **AND** a quick reference table of all CLI commands
|
||||
- **AND** examples demonstrating common usage patterns
|
||||
|
||||
#### Scenario: User looks up specific CLI flag
|
||||
- **WHEN** a user needs to understand a specific CLI flag (e.g., `--output-format`)
|
||||
- **THEN** they find the flag documented with description, options, and example usage
|
||||
- **AND** related flags are cross-referenced
|
||||
|
||||
#### Scenario: User integrates Claude Code in CI/CD
|
||||
- **WHEN** a user wants to use Claude Code in automation
|
||||
- **THEN** they find practical examples for CI/CD integration
|
||||
- **AND** examples show headless mode, JSON output, and error handling
|
||||
|
||||
### Requirement: CLI Commands Documentation
|
||||
|
||||
The CLI lesson SHALL document all primary CLI commands with their syntax and use cases.
|
||||
|
||||
#### Scenario: Interactive mode commands documented
|
||||
- **WHEN** a user reads the CLI commands section
|
||||
- **THEN** they find `claude` for starting interactive REPL
|
||||
- **AND** `claude "query"` for starting with initial prompt
|
||||
- **AND** `claude -c` for continuing recent conversation
|
||||
- **AND** `claude -r` for resuming specific session
|
||||
|
||||
#### Scenario: Print mode commands documented
|
||||
- **WHEN** a user reads the print mode section
|
||||
- **THEN** they find `claude -p "query"` for non-interactive queries
|
||||
- **AND** pipe input examples like `cat file | claude -p "query"`
|
||||
- **AND** output format options (text, json, stream-json)
|
||||
|
||||
### Requirement: CLI Flags Documentation
|
||||
|
||||
The CLI lesson SHALL document all CLI flags organized by category with examples.
|
||||
|
||||
#### Scenario: Core flags documented
|
||||
- **WHEN** a user reads the core flags section
|
||||
- **THEN** they find `-p/--print`, `-c/--continue`, `-r/--resume`, `-v/--version`
|
||||
- **AND** each flag has description and example usage
|
||||
|
||||
#### Scenario: Model configuration flags documented
|
||||
- **WHEN** a user reads the model configuration section
|
||||
- **THEN** they find `--model`, `--fallback-model`, `--agent`, `--agents`
|
||||
- **AND** examples show model selection and custom agent definitions
|
||||
|
||||
#### Scenario: Permission flags documented
|
||||
- **WHEN** a user reads the permission section
|
||||
- **THEN** they find `--tools`, `--allowedTools`, `--disallowedTools`
|
||||
- **AND** `--dangerously-skip-permissions`, `--permission-mode`
|
||||
- **AND** examples demonstrate security-conscious configurations
|
||||
|
||||
### Requirement: High-Value Use Cases
|
||||
|
||||
The CLI lesson SHALL include practical use case examples that demonstrate real-world CLI value.
|
||||
|
||||
#### Scenario: CI/CD integration example provided
|
||||
- **WHEN** a user reads the CI/CD use case
|
||||
- **THEN** they find a complete GitHub Actions or Jenkins example
|
||||
- **AND** the example demonstrates headless mode with JSON output
|
||||
- **AND** error handling and exit codes are explained
|
||||
|
||||
#### Scenario: Script piping example provided
|
||||
- **WHEN** a user reads the script piping use case
|
||||
- **THEN** they find examples of piping file contents to Claude
|
||||
- **AND** examples show log analysis, code review via pipe
|
||||
- **AND** output processing patterns are demonstrated
|
||||
|
||||
#### Scenario: Multi-session workflow example provided
|
||||
- **WHEN** a user reads the session management use case
|
||||
- **THEN** they find examples of resuming and forking sessions
|
||||
- **AND** session naming and organization patterns are shown
|
||||
|
||||
### Requirement: Navigation Integration
|
||||
|
||||
The root documentation SHALL be updated to include the CLI lesson in all navigation elements.
|
||||
|
||||
#### Scenario: CLI appears in Quick Navigation
|
||||
- **WHEN** a user views the README Quick Navigation table
|
||||
- **THEN** they see CLI Reference listed with link to `10-cli/`
|
||||
|
||||
#### Scenario: CLI appears in Learning Path
|
||||
- **WHEN** a user views the Learning Path table
|
||||
- **THEN** they see CLI Reference at position 10 with appropriate difficulty and timing
|
||||
|
||||
#### Scenario: CLI appears in Feature Comparison
|
||||
- **WHEN** a user views the Feature Comparison table
|
||||
- **THEN** CLI Reference is included with invocation, persistence, and use case columns
|
||||
|
||||
#### Scenario: CLI appears in Directory Structure
|
||||
- **WHEN** a user views the Directory Structure tree
|
||||
- **THEN** `10-cli/` directory is shown with `README.md`
|
||||
@@ -0,0 +1,50 @@
|
||||
# Tasks: Add CLI Reference Lesson
|
||||
|
||||
## 1. Create CLI Lesson Content
|
||||
|
||||
- [ ] 1.1 Create `10-cli/` directory
|
||||
- [ ] 1.2 Create `10-cli/README.md` with:
|
||||
- Overview section with architecture diagram
|
||||
- CLI commands table (claude, claude "query", claude -p, etc.)
|
||||
- Core flags section with examples
|
||||
- Model & configuration flags
|
||||
- System prompt customization section
|
||||
- Tool & permission management section
|
||||
- Output & format options
|
||||
- Workspace & directory flags
|
||||
- MCP configuration options
|
||||
- Session management commands
|
||||
- Advanced features (chrome, ide, debug)
|
||||
- Agents flag format with JSON examples
|
||||
- High-value use cases section with practical examples
|
||||
- Installation/usage quick reference
|
||||
- Troubleshooting section
|
||||
- Related concepts links
|
||||
|
||||
## 2. Add Use Case Examples
|
||||
|
||||
- [ ] 2.1 CI/CD integration example (GitHub Actions, Jenkins)
|
||||
- [ ] 2.2 Script piping example (log analysis, code processing)
|
||||
- [ ] 2.3 Multi-session workflow example
|
||||
- [ ] 2.4 Custom agent configuration example
|
||||
- [ ] 2.5 Batch processing example
|
||||
- [ ] 2.6 Security-conscious development example
|
||||
- [ ] 2.7 JSON API integration example
|
||||
|
||||
## 3. Update Root Documentation
|
||||
|
||||
- [ ] 3.1 Add CLI to Quick Navigation table in `README.md`
|
||||
- [ ] 3.2 Add CLI to Learning Path table in `README.md`
|
||||
- [ ] 3.3 Add CLI section (section 10) in `README.md`
|
||||
- [ ] 3.4 Add CLI to Feature Comparison table
|
||||
- [ ] 3.5 Add CLI to Use Case Matrix
|
||||
- [ ] 3.6 Add CLI to Directory Structure tree
|
||||
- [ ] 3.7 Add CLI to Installation Quick Reference
|
||||
- [ ] 3.8 Update `LEARNING-ROADMAP.md` with CLI lesson
|
||||
|
||||
## 4. Quality Assurance
|
||||
|
||||
- [ ] 4.1 Verify all code examples are valid and tested
|
||||
- [ ] 4.2 Ensure consistent style with other lessons (mermaid diagrams, tables)
|
||||
- [ ] 4.3 Check all internal links work correctly
|
||||
- [ ] 4.4 Review against official documentation for accuracy
|
||||
@@ -0,0 +1,36 @@
|
||||
# Change: Update Hooks Lesson Based on Official Documentation
|
||||
|
||||
## Why
|
||||
|
||||
The current hooks lesson (`blog-posts/06-hooks.md`) contains outdated and inaccurate information that doesn't match the official Claude Code hooks documentation. Key issues include:
|
||||
|
||||
1. **Incorrect hook event names**: Uses `PreToolUse:Write`, `PreCommit`, `PostCommit`, `PrePush` which don't exist
|
||||
2. **Missing hook events**: Doesn't cover `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, `SessionStart` (with matchers), `SessionEnd`
|
||||
3. **Wrong configuration format**: Shows string-based hook commands instead of the array-based matcher/hooks structure
|
||||
4. **Missing hook input/output**: Doesn't explain JSON stdin input or structured JSON output
|
||||
5. **Missing exit code semantics**: Exit code 2 for blocking vs other non-zero codes
|
||||
6. **Missing prompt-based hooks**: No coverage of `type: "prompt"` hooks for LLM-based evaluation
|
||||
7. **Missing security considerations**: No disclaimer or security best practices from official docs
|
||||
8. **Incorrect variable references**: Uses `${file_path}`, `${command}` instead of JSON stdin input
|
||||
|
||||
## What Changes
|
||||
|
||||
- **BREAKING**: Complete rewrite of hook event types and configuration format
|
||||
- Update all code examples to use correct array-based configuration structure
|
||||
- Add coverage of all 9 hook events: `PreToolUse`, `PermissionRequest`, `PostToolUse`, `Notification`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PreCompact`, `SessionStart`, `SessionEnd`
|
||||
- Add JSON hook input/output documentation with examples
|
||||
- Add hook matchers (tool patterns, regex support)
|
||||
- Add prompt-based hooks for `Stop`/`SubagentStop`
|
||||
- Add security considerations section with official disclaimer
|
||||
- Add environment variables section (`CLAUDE_PROJECT_DIR`, `CLAUDE_ENV_FILE`, `CLAUDE_CODE_REMOTE`)
|
||||
- Add plugin hooks documentation
|
||||
- Add MCP tool hook patterns (`mcp__<server>__<tool>`)
|
||||
- Update debugging section with `claude --debug` and verbose mode
|
||||
- Remove incorrect/non-existent hook types (`PreCommit`, `PostCommit`, `PrePush`)
|
||||
|
||||
## Impact
|
||||
|
||||
- **Affected specs**: hooks-documentation (new capability)
|
||||
- **Affected code**: `blog-posts/06-hooks.md` (complete rewrite)
|
||||
- **Affected examples**: Any example hook scripts in the repo need updating to use JSON stdin
|
||||
- **User impact**: Users following the current guide will have non-functional hooks; this update provides correct, working examples
|
||||
@@ -0,0 +1,124 @@
|
||||
# Hooks Documentation Specification
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Hook Event Types Documentation
|
||||
The hooks lesson SHALL document all 9 official hook events with their correct names, matchers, and behavior.
|
||||
|
||||
#### Scenario: Complete hook event coverage
|
||||
- **WHEN** a user reads the hooks lesson
|
||||
- **THEN** they find documentation for PreToolUse, PermissionRequest, PostToolUse, Notification, UserPromptSubmit, Stop, SubagentStop, PreCompact, SessionStart, and SessionEnd events
|
||||
|
||||
#### Scenario: No deprecated hook events
|
||||
- **WHEN** a user searches for PreCommit, PostCommit, or PrePush hooks
|
||||
- **THEN** they do not find these as they are not valid Claude Code hook events
|
||||
|
||||
### Requirement: Hook Configuration Format
|
||||
The hooks lesson SHALL document the correct array-based configuration format with matchers and hooks arrays.
|
||||
|
||||
#### Scenario: Configuration structure
|
||||
- **WHEN** a user views hook configuration examples
|
||||
- **THEN** they see the structure: `{ "hooks": { "EventName": [{ "matcher": "Pattern", "hooks": [{ "type": "command", "command": "..." }] }] } }`
|
||||
|
||||
#### Scenario: Matcher patterns
|
||||
- **WHEN** a user needs to match specific tools
|
||||
- **THEN** they find documentation for exact string matching, regex patterns, and wildcards
|
||||
|
||||
### Requirement: Hook Input Documentation
|
||||
The hooks lesson SHALL document the JSON stdin input that hooks receive.
|
||||
|
||||
#### Scenario: JSON input structure
|
||||
- **WHEN** a user writes a hook script
|
||||
- **THEN** they understand the input includes session_id, transcript_path, cwd, permission_mode, hook_event_name, tool_name, tool_input, and tool_use_id
|
||||
|
||||
#### Scenario: Event-specific input fields
|
||||
- **WHEN** a user writes a hook for a specific event
|
||||
- **THEN** they find documentation for event-specific input fields (e.g., stop_hook_active for Stop event)
|
||||
|
||||
### Requirement: Hook Output Documentation
|
||||
The hooks lesson SHALL document hook output semantics including exit codes and JSON stdout structure.
|
||||
|
||||
#### Scenario: Exit code semantics
|
||||
- **WHEN** a user implements a hook
|
||||
- **THEN** they understand exit code 0 means success, exit code 2 means blocking error (stderr used as error message), and other codes mean non-blocking error
|
||||
|
||||
#### Scenario: JSON output format
|
||||
- **WHEN** a hook needs to control behavior
|
||||
- **THEN** the user can output JSON with continue, stopReason, suppressOutput, systemMessage, and hookSpecificOutput fields
|
||||
|
||||
#### Scenario: Event-specific output
|
||||
- **WHEN** a user writes a PreToolUse hook
|
||||
- **THEN** they can output permissionDecision (allow/deny/ask), permissionDecisionReason, and updatedInput
|
||||
|
||||
### Requirement: Prompt-Based Hooks Documentation
|
||||
The hooks lesson SHALL document type="prompt" hooks for LLM-based evaluation on Stop and SubagentStop events.
|
||||
|
||||
#### Scenario: Prompt hook configuration
|
||||
- **WHEN** a user wants intelligent stop evaluation
|
||||
- **THEN** they find documentation for configuring type="prompt" hooks with prompt text and timeout
|
||||
|
||||
#### Scenario: LLM response schema
|
||||
- **WHEN** using prompt-based hooks
|
||||
- **THEN** the user understands the expected response schema with decision (approve/block), reason, continue, stopReason, and systemMessage
|
||||
|
||||
### Requirement: Environment Variables Documentation
|
||||
The hooks lesson SHALL document all environment variables available to hooks.
|
||||
|
||||
#### Scenario: Standard environment variables
|
||||
- **WHEN** a user writes a hook script
|
||||
- **THEN** they can use CLAUDE_PROJECT_DIR for the absolute project path
|
||||
|
||||
#### Scenario: SessionStart environment persistence
|
||||
- **WHEN** using SessionStart hooks
|
||||
- **THEN** the user can persist environment variables via CLAUDE_ENV_FILE
|
||||
|
||||
#### Scenario: Remote environment detection
|
||||
- **WHEN** running in web environment
|
||||
- **THEN** hooks can check CLAUDE_CODE_REMOTE to detect this
|
||||
|
||||
### Requirement: Security Documentation
|
||||
The hooks lesson SHALL include security considerations and best practices from the official documentation.
|
||||
|
||||
#### Scenario: Security disclaimer
|
||||
- **WHEN** a user reads about hooks
|
||||
- **THEN** they see a clear disclaimer that hooks execute arbitrary shell commands at their own risk
|
||||
|
||||
#### Scenario: Security best practices
|
||||
- **WHEN** a user implements hooks
|
||||
- **THEN** they find guidance on input validation, shell variable quoting, path traversal prevention, and sensitive file handling
|
||||
|
||||
### Requirement: MCP Tool Hook Patterns
|
||||
The hooks lesson SHALL document how to create hooks for MCP tools.
|
||||
|
||||
#### Scenario: MCP tool matching
|
||||
- **WHEN** a user wants to hook into MCP tool calls
|
||||
- **THEN** they find documentation for the pattern `mcp__<server>__<tool>` and regex matching
|
||||
|
||||
### Requirement: Plugin Hooks Documentation
|
||||
The hooks lesson SHALL document how plugins can provide hooks.
|
||||
|
||||
#### Scenario: Plugin hook configuration
|
||||
- **WHEN** a plugin needs to provide hooks
|
||||
- **THEN** documentation covers hooks/hooks.json structure and ${CLAUDE_PLUGIN_ROOT} variable
|
||||
|
||||
### Requirement: Debugging Documentation
|
||||
The hooks lesson SHALL document how to debug hook execution.
|
||||
|
||||
#### Scenario: Debug mode
|
||||
- **WHEN** hooks are not working as expected
|
||||
- **THEN** users can enable `claude --debug` for detailed hook execution logs
|
||||
|
||||
#### Scenario: Verbose mode
|
||||
- **WHEN** using Claude Code interactively
|
||||
- **THEN** users can enable verbose mode (ctrl+o) to see hook execution progress
|
||||
|
||||
### Requirement: Working Example Scripts
|
||||
The hooks lesson SHALL provide working example scripts that use JSON stdin input.
|
||||
|
||||
#### Scenario: Bash command validator
|
||||
- **WHEN** a user wants to validate bash commands
|
||||
- **THEN** they find a working Python script that reads JSON stdin and validates commands
|
||||
|
||||
#### Scenario: Intelligent stop hook
|
||||
- **WHEN** a user wants automatic task completion verification
|
||||
- **THEN** they find a working prompt-based stop hook example
|
||||
@@ -0,0 +1,69 @@
|
||||
# Tasks: Update Hooks Lesson
|
||||
|
||||
## 1. Content Structure Update
|
||||
- [x] 1.1 Update introduction to explain hooks as event-driven automation scripts
|
||||
- [x] 1.2 Replace hook architecture diagram with correct event flow
|
||||
- [x] 1.3 Update hook types table with all 9 official hook events
|
||||
|
||||
## 2. Configuration Format
|
||||
- [x] 2.1 Rewrite configuration section with array-based matcher/hooks structure
|
||||
- [x] 2.2 Add hook matcher documentation (exact match, regex patterns, wildcards)
|
||||
- [x] 2.3 Add timeout configuration examples
|
||||
|
||||
## 3. Hook Events Documentation
|
||||
- [x] 3.1 Document PreToolUse event (matchers, decision control, updatedInput)
|
||||
- [x] 3.2 Document PermissionRequest event (decision behavior, messages)
|
||||
- [x] 3.3 Document PostToolUse event (block decision, additionalContext)
|
||||
- [x] 3.4 Document Notification event (matchers: permission_prompt, idle_prompt, etc.)
|
||||
- [x] 3.5 Document UserPromptSubmit event (block decision, context addition)
|
||||
- [x] 3.6 Document Stop event (block continuation, stop_hook_active)
|
||||
- [x] 3.7 Document SubagentStop event (subagent completion handling)
|
||||
- [x] 3.8 Document PreCompact event (manual vs auto matchers)
|
||||
- [x] 3.9 Document SessionStart event (startup/resume/clear/compact matchers, CLAUDE_ENV_FILE)
|
||||
- [x] 3.10 Document SessionEnd event (reason field)
|
||||
|
||||
## 4. Hook Input/Output
|
||||
- [x] 4.1 Document JSON stdin input structure (session_id, transcript_path, cwd, etc.)
|
||||
- [x] 4.2 Document exit code semantics (0=success, 2=blocking error, other=non-blocking)
|
||||
- [x] 4.3 Document JSON stdout output structure (continue, stopReason, hookSpecificOutput)
|
||||
- [x] 4.4 Add examples for each hook event's specific output format
|
||||
|
||||
## 5. Prompt-Based Hooks
|
||||
- [x] 5.1 Add section on type="prompt" hooks for Stop/SubagentStop
|
||||
- [x] 5.2 Document LLM response schema (decision, reason, continue, stopReason)
|
||||
- [x] 5.3 Add practical examples of intelligent stop hooks
|
||||
|
||||
## 6. Environment Variables
|
||||
- [x] 6.1 Document CLAUDE_PROJECT_DIR usage
|
||||
- [x] 6.2 Document CLAUDE_ENV_FILE for SessionStart env persistence
|
||||
- [x] 6.3 Document CLAUDE_CODE_REMOTE for web environment detection
|
||||
- [x] 6.4 Document plugin hook variables (${CLAUDE_PLUGIN_ROOT})
|
||||
|
||||
## 7. Security Section
|
||||
- [x] 7.1 Add official security disclaimer (USE AT YOUR OWN RISK)
|
||||
- [x] 7.2 Document security best practices (input validation, quoting, path traversal)
|
||||
- [x] 7.3 Add configuration safety notes (snapshot at startup, modification warnings)
|
||||
|
||||
## 8. Advanced Features
|
||||
- [x] 8.1 Add MCP tool hook patterns (mcp__<server>__<tool>)
|
||||
- [x] 8.2 Add plugin hooks documentation
|
||||
- [x] 8.3 Add project-specific hook script examples
|
||||
|
||||
## 9. Debugging and Troubleshooting
|
||||
- [x] 9.1 Update debugging section with claude --debug flag
|
||||
- [x] 9.2 Add verbose mode (ctrl+o) documentation
|
||||
- [x] 9.3 Update troubleshooting with correct error scenarios
|
||||
|
||||
## 10. Example Scripts
|
||||
- [x] 10.1 Rewrite format-code hook to use JSON stdin
|
||||
- [x] 10.2 Rewrite security-scan hook with proper JSON input parsing
|
||||
- [x] 10.3 Rewrite bash command validator example from official docs
|
||||
- [x] 10.4 Add intelligent stop hook example with prompt type
|
||||
- [x] 10.5 Remove non-existent PreCommit/PostCommit/PrePush examples
|
||||
|
||||
## 11. Final Cleanup
|
||||
- [x] 11.1 Update Mermaid diagrams for accuracy
|
||||
- [x] 11.2 Update variable reference table to reflect JSON input
|
||||
- [x] 11.3 Update best practices table
|
||||
- [x] 11.4 Update directory structure section
|
||||
- [x] 11.5 Verify all links and references
|
||||
@@ -0,0 +1,48 @@
|
||||
# Change: Update Agent Skills Lesson with Latest Documentation
|
||||
|
||||
## Why
|
||||
|
||||
The current Agent Skills lesson (03-skills) is missing several key features and best practices from the latest official Claude Code documentation at https://code.claude.com/docs/en/skills#agent-skills. Users need up-to-date information to effectively create, manage, debug, and share skills.
|
||||
|
||||
## What Changes
|
||||
|
||||
### Documentation Updates (README.md and blog-posts/03-skills.md)
|
||||
|
||||
1. **Enhanced Managing Skills Section** - Add comprehensive guidance for:
|
||||
- Viewing available skills (via Claude and filesystem)
|
||||
- Testing skills effectively
|
||||
- Updating skills (with restart requirements)
|
||||
- Removing skills properly
|
||||
|
||||
2. **Improved Debugging Section** - Add detailed troubleshooting for:
|
||||
- Skills being skipped or non-functional
|
||||
- Invalid YAML frontmatter detection
|
||||
- Script permission issues
|
||||
- Path format requirements (forward slashes)
|
||||
- Multiple skills conflicting
|
||||
|
||||
3. **Version History Best Practice** - Add guidance on documenting skill versions in SKILL.md
|
||||
|
||||
4. **Enhanced allowed-tools Documentation** - Expand explanation of tool access control with:
|
||||
- Use cases for read-only skills
|
||||
- Security-sensitive workflow examples
|
||||
- Note about permission prompts when not specified
|
||||
|
||||
5. **Multi-File Skill Example** - Add comprehensive example showing:
|
||||
- Directory structure for complex skills
|
||||
- Multiple reference files
|
||||
- Scripts subdirectory
|
||||
- Templates organization
|
||||
|
||||
6. **Plugin Skills Clarification** - Better explain how plugin-bundled skills work
|
||||
|
||||
### Example Updates (03-skills/ directory)
|
||||
|
||||
7. **Add Version History Example** - Update code-review SKILL.md to include version history section
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected docs: `03-skills/README.md`, `blog-posts/03-skills.md`
|
||||
- Affected examples: `03-skills/code-review/SKILL.md`
|
||||
- No breaking changes - purely additive documentation improvements
|
||||
- Improves user experience for skill creation and debugging
|
||||
@@ -0,0 +1,64 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Managing Skills Documentation
|
||||
The skills lesson SHALL provide comprehensive guidance for managing skills including viewing available skills, testing skills, updating skills with restart requirements, and removing skills.
|
||||
|
||||
#### Scenario: User wants to view available skills
|
||||
- **WHEN** a user wants to see what skills are available
|
||||
- **THEN** the documentation provides both CLI method (asking Claude "What Skills are available?") and filesystem method (ls ~/.claude/skills/ and ls .claude/skills/)
|
||||
|
||||
#### Scenario: User wants to test a skill
|
||||
- **WHEN** a user wants to test if their skill works
|
||||
- **THEN** the documentation explains that skills activate automatically based on matching descriptions, with example test queries
|
||||
|
||||
#### Scenario: User wants to update a skill
|
||||
- **WHEN** a user modifies a SKILL.md file
|
||||
- **THEN** the documentation explains that changes take effect on next Claude Code startup and restart is required if already running
|
||||
|
||||
#### Scenario: User wants to remove a skill
|
||||
- **WHEN** a user wants to remove a skill
|
||||
- **THEN** the documentation provides rm -rf commands for both personal and project skills, with git commit for project skills
|
||||
|
||||
### Requirement: Enhanced Debugging Guidance
|
||||
The skills lesson SHALL provide detailed debugging guidance for common skill issues including skipped skills, YAML errors, script permissions, and path formats.
|
||||
|
||||
#### Scenario: Skill not being discovered
|
||||
- **WHEN** Claude doesn't use a user's skill
|
||||
- **THEN** the documentation explains to check: description specificity, YAML syntax validity (opening/closing ---, no tabs), and correct file path location
|
||||
|
||||
#### Scenario: Skill has errors
|
||||
- **WHEN** a skill has runtime errors
|
||||
- **THEN** the documentation explains to check: dependency installation, script execute permissions (chmod +x), and forward slash usage in paths
|
||||
|
||||
#### Scenario: Multiple skills conflict
|
||||
- **WHEN** multiple skills are activated unexpectedly
|
||||
- **THEN** the documentation explains using distinct trigger terms in descriptions to help Claude choose the right skill
|
||||
|
||||
### Requirement: Version History Documentation
|
||||
The skills lesson SHALL include a best practice example for documenting skill version history in SKILL.md files.
|
||||
|
||||
#### Scenario: User wants to track skill versions
|
||||
- **WHEN** a user maintains a skill over time
|
||||
- **THEN** the documentation provides a version history markdown template with date and description format
|
||||
|
||||
### Requirement: Enhanced Tool Access Control Documentation
|
||||
The skills lesson SHALL provide expanded documentation for the allowed-tools feature including use cases, security examples, and behavior when not specified.
|
||||
|
||||
#### Scenario: User wants a read-only skill
|
||||
- **WHEN** a user wants to create a skill that cannot modify files
|
||||
- **THEN** the documentation provides an example with allowed-tools: Read, Grep, Glob
|
||||
|
||||
#### Scenario: User wants security-sensitive workflow
|
||||
- **WHEN** a user has a security-sensitive skill
|
||||
- **THEN** the documentation explains how allowed-tools restricts Claude's capabilities within that skill context
|
||||
|
||||
#### Scenario: allowed-tools not specified
|
||||
- **WHEN** a user doesn't specify allowed-tools
|
||||
- **THEN** the documentation explains that Claude will ask for permission as normal
|
||||
|
||||
### Requirement: Multi-File Skill Example
|
||||
The skills lesson SHALL include a comprehensive example of a multi-file skill showing directory structure with multiple reference files, scripts, and templates.
|
||||
|
||||
#### Scenario: User wants to create complex skill
|
||||
- **WHEN** a user needs a skill with supporting files
|
||||
- **THEN** the documentation provides a complete directory structure example showing SKILL.md, reference files (FORMS.md, REFERENCE.md), scripts subdirectory, and progressive disclosure explanation
|
||||
@@ -0,0 +1,27 @@
|
||||
# Tasks: Update Agent Skills Lesson
|
||||
|
||||
## 1. Update Main README (03-skills/README.md)
|
||||
|
||||
- [ ] 1.1 Add "Managing Skills" section with viewing, testing, updating, removing guidance
|
||||
- [ ] 1.2 Expand "Troubleshooting Guide" with debugging tips for skipped skills, YAML errors, script permissions, path formats
|
||||
- [ ] 1.3 Add "Version History Best Practice" section with example
|
||||
- [ ] 1.4 Enhance "allowed-tools" documentation with use cases and security examples
|
||||
- [ ] 1.5 Add "Multi-File Skill Example" showing complex skill structure with multiple reference files
|
||||
|
||||
## 2. Update Blog Post (blog-posts/03-skills.md)
|
||||
|
||||
- [ ] 2.1 Add "Managing Skills" section mirroring README updates
|
||||
- [ ] 2.2 Expand troubleshooting with debugging guidance from official docs
|
||||
- [ ] 2.3 Add version history best practice
|
||||
- [ ] 2.4 Enhance allowed-tools explanation
|
||||
- [ ] 2.5 Add multi-file skill example
|
||||
|
||||
## 3. Update Example Skills
|
||||
|
||||
- [ ] 3.1 Add version history section to `03-skills/code-review/SKILL.md`
|
||||
|
||||
## 4. Validation
|
||||
|
||||
- [ ] 4.1 Verify all code examples are syntactically correct
|
||||
- [ ] 4.2 Ensure consistency between README and blog post
|
||||
- [ ] 4.3 Test that existing examples still work with updated documentation
|
||||
@@ -0,0 +1,33 @@
|
||||
# Change: Update Slash Commands Documentation
|
||||
|
||||
## Why
|
||||
|
||||
The current slash commands documentation in `01-slash-commands/README.md` is outdated compared to the official Claude Code documentation at https://code.claude.com/docs/en/slash-commands. Several new features, built-in commands, and capabilities have been added that users should know about.
|
||||
|
||||
## What Changes
|
||||
|
||||
### Documentation Updates
|
||||
|
||||
- **Add comprehensive built-in commands table** - Document all 40+ built-in slash commands with their purposes
|
||||
- **Update custom command features** - Document new argument handling (`$ARGUMENTS`, `$1`, `$2`, etc.)
|
||||
- **Add bash execution syntax** - Document the `!` prefix for executing bash commands within slash commands
|
||||
- **Update frontmatter fields** - Document `allowed-tools`, `argument-hint`, `description`, `model`, `disable-model-invocation`
|
||||
- **Add file reference syntax** - Document the `@` prefix for including file contents
|
||||
- **Add Plugin commands section** - Document `/plugin-name:command-name` pattern
|
||||
- **Add MCP slash commands section** - Document `/mcp__<server-name>__<prompt-name>` pattern
|
||||
- **Add SlashCommand Tool section** - Document programmatic invocation from Claude
|
||||
- **Add Skills vs Slash Commands comparison** - Help users choose the right tool
|
||||
|
||||
### Example Updates
|
||||
|
||||
- Add example command with bash execution (`!git status`)
|
||||
- Add example with file references (`@src/utils/helpers.js`)
|
||||
- Add example with complete frontmatter
|
||||
- Update existing examples to use official syntax
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: `slash-commands` (new capability spec to be created)
|
||||
- Affected code: `01-slash-commands/README.md`, potentially new example files
|
||||
- No breaking changes - additive documentation improvements
|
||||
- Benefits all users learning about Claude Code slash commands
|
||||
@@ -0,0 +1,147 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Slash Command Types Documentation
|
||||
|
||||
The documentation SHALL describe the four types of slash commands:
|
||||
1. Built-in commands provided by Claude Code
|
||||
2. Custom user-defined commands (project and personal)
|
||||
3. Plugin commands
|
||||
4. MCP (Model Context Protocol) slash commands
|
||||
|
||||
#### Scenario: User learns about command types
|
||||
- **WHEN** a user reads the slash commands documentation
|
||||
- **THEN** they understand the different types of slash commands available
|
||||
- **AND** they know when to use each type
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Built-in Commands Reference
|
||||
|
||||
The documentation SHALL include a comprehensive reference table of all built-in slash commands with their purposes, including but not limited to:
|
||||
- `/add-dir` - Add additional working directories
|
||||
- `/agents` - Manage custom AI subagents
|
||||
- `/clear` - Clear conversation history
|
||||
- `/compact` - Compact conversation with optional focus instructions
|
||||
- `/config` - Open Settings interface
|
||||
- `/context` - Visualize current context usage
|
||||
- `/cost` - Show token usage statistics
|
||||
- `/doctor` - Check installation health
|
||||
- `/export` - Export conversation to file or clipboard
|
||||
- `/help` - Get usage help
|
||||
- `/hooks` - Manage hook configurations
|
||||
- `/init` - Initialize project with CLAUDE.md
|
||||
- `/mcp` - Manage MCP server connections
|
||||
- `/memory` - Edit CLAUDE.md memory files
|
||||
- `/model` - Select or change AI model
|
||||
- `/permissions` - View or update permissions
|
||||
- `/resume` - Resume conversation by ID or name
|
||||
- `/review` - Request code review
|
||||
- `/sandbox` - Enable sandboxed bash tool
|
||||
- `/vim` - Enter vim mode
|
||||
|
||||
#### Scenario: User finds built-in command
|
||||
- **WHEN** a user needs to perform a common operation
|
||||
- **THEN** they can find the appropriate built-in command in the reference table
|
||||
- **AND** they understand what the command does
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Argument Handling
|
||||
|
||||
The documentation SHALL explain both argument handling methods:
|
||||
1. `$ARGUMENTS` - Receives all arguments as a single string
|
||||
2. `$1`, `$2`, `$3`, etc. - Individual positional arguments
|
||||
|
||||
#### Scenario: User uses $ARGUMENTS placeholder
|
||||
- **WHEN** a user creates a command with `$ARGUMENTS` placeholder
|
||||
- **AND** invokes it with `/fix-issue 123 high-priority`
|
||||
- **THEN** `$ARGUMENTS` contains "123 high-priority"
|
||||
|
||||
#### Scenario: User uses positional arguments
|
||||
- **WHEN** a user creates a command with `$1`, `$2`, `$3` placeholders
|
||||
- **AND** invokes it with `/review-pr 456 high alice`
|
||||
- **THEN** `$1` is "456", `$2` is "high", `$3` is "alice"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Bash Command Execution
|
||||
|
||||
The documentation SHALL explain the `!` prefix for executing bash commands within slash command files before the command runs.
|
||||
|
||||
#### Scenario: User includes dynamic context
|
||||
- **WHEN** a user adds `!git status` in their command file
|
||||
- **THEN** the git status output is included in the command context
|
||||
- **AND** Claude receives the current repository state
|
||||
|
||||
---
|
||||
|
||||
### Requirement: File Reference Syntax
|
||||
|
||||
The documentation SHALL explain the `@` prefix for including file contents in slash commands.
|
||||
|
||||
#### Scenario: User references a file
|
||||
- **WHEN** a user adds `@src/utils/helpers.js` in their command file
|
||||
- **THEN** the contents of that file are included in the command context
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Frontmatter Fields
|
||||
|
||||
The documentation SHALL document all supported frontmatter fields:
|
||||
- `allowed-tools` - List of tools the command can use
|
||||
- `argument-hint` - Expected arguments for auto-completion
|
||||
- `description` - Brief description of the command
|
||||
- `model` - Specific model to use for this command
|
||||
- `disable-model-invocation` - Prevent SlashCommand tool from calling this command
|
||||
|
||||
#### Scenario: User creates command with frontmatter
|
||||
- **WHEN** a user creates a command with frontmatter fields
|
||||
- **THEN** Claude Code respects those configuration options
|
||||
- **AND** the command behaves according to the specified settings
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Plugin Commands Documentation
|
||||
|
||||
The documentation SHALL explain the plugin command format: `/plugin-name:command-name` or simply `/command-name` when there are no naming conflicts.
|
||||
|
||||
#### Scenario: User invokes plugin command
|
||||
- **WHEN** a user types `/frontend-design:frontend-design`
|
||||
- **THEN** the corresponding plugin command executes
|
||||
|
||||
---
|
||||
|
||||
### Requirement: MCP Slash Commands Documentation
|
||||
|
||||
The documentation SHALL explain the MCP slash command format: `/mcp__<server-name>__<prompt-name> [arguments]`
|
||||
|
||||
#### Scenario: User invokes MCP command
|
||||
- **WHEN** a user types `/mcp__github__list_prs`
|
||||
- **THEN** the MCP server's prompt is executed
|
||||
|
||||
---
|
||||
|
||||
### Requirement: SlashCommand Tool Documentation
|
||||
|
||||
The documentation SHALL explain how Claude can programmatically invoke slash commands using the SlashCommand tool, including:
|
||||
- How to enable this via prompt or CLAUDE.md references
|
||||
- How to disable via permissions
|
||||
- The character budget limit (default 15,000, configurable via `SLASH_COMMAND_TOOL_CHAR_BUDGET`)
|
||||
|
||||
#### Scenario: User enables programmatic invocation
|
||||
- **WHEN** a user adds "Run /write-unit-test when writing tests" to CLAUDE.md
|
||||
- **THEN** Claude can automatically invoke that command when appropriate
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Skills vs Slash Commands Comparison
|
||||
|
||||
The documentation SHALL include a comparison table helping users choose between Skills and Slash Commands based on:
|
||||
- Best use cases for each
|
||||
- File structure differences
|
||||
- Invocation method (explicit vs automatic)
|
||||
- Complexity level
|
||||
|
||||
#### Scenario: User decides between skill and command
|
||||
- **WHEN** a user needs to create a reusable capability
|
||||
- **THEN** they can use the comparison to decide whether a slash command or skill is more appropriate
|
||||
@@ -0,0 +1,42 @@
|
||||
## 1. Documentation Structure Updates
|
||||
|
||||
- [x] 1.1 Add "Types of Slash Commands" section with overview of built-in, custom, plugin, and MCP commands
|
||||
- [x] 1.2 Create comprehensive built-in commands reference table (40+ commands)
|
||||
- [x] 1.3 Update custom commands section with new features
|
||||
|
||||
## 2. Custom Command Features
|
||||
|
||||
- [x] 2.1 Document `$ARGUMENTS` placeholder for all arguments
|
||||
- [x] 2.2 Document individual argument placeholders (`$1`, `$2`, `$3`, etc.)
|
||||
- [x] 2.3 Document bash execution with `!` prefix (e.g., `!git status`)
|
||||
- [x] 2.4 Document file references with `@` prefix (e.g., `@src/file.js`)
|
||||
- [x] 2.5 Document thinking mode trigger via keywords
|
||||
|
||||
## 3. Frontmatter Updates
|
||||
|
||||
- [x] 3.1 Update frontmatter section with official fields
|
||||
- [x] 3.2 Document `allowed-tools` field with examples
|
||||
- [x] 3.3 Document `argument-hint` field for auto-completion
|
||||
- [x] 3.4 Document `description` field
|
||||
- [x] 3.5 Document `model` field for specific model selection
|
||||
- [x] 3.6 Document `disable-model-invocation` field
|
||||
|
||||
## 4. New Sections
|
||||
|
||||
- [x] 4.1 Add "Plugin Commands" section with `/plugin-name:command-name` pattern
|
||||
- [x] 4.2 Add "MCP Slash Commands" section with `/mcp__<server-name>__<prompt-name>` pattern
|
||||
- [x] 4.3 Add "SlashCommand Tool" section for programmatic invocation
|
||||
- [x] 4.4 Add "Skills vs Slash Commands" comparison table
|
||||
|
||||
## 5. Example Files
|
||||
|
||||
- [x] 5.1 Create new example showing bash execution feature (commit.md)
|
||||
- [x] 5.2 Create new example showing file references (commit.md includes @package.json example in README)
|
||||
- [x] 5.3 Update existing examples to use official frontmatter format (removed name/tags, added allowed-tools)
|
||||
- [x] 5.4 Add commit command example (from official docs)
|
||||
|
||||
## 6. Validation
|
||||
|
||||
- [x] 6.1 Verify all links work correctly
|
||||
- [x] 6.2 Test example commands format
|
||||
- [x] 6.3 Review for consistency with official documentation
|
||||
@@ -0,0 +1,125 @@
|
||||
# Project Context
|
||||
|
||||
## Purpose
|
||||
|
||||
**Claude How To** is a comprehensive educational repository providing examples and documentation for Claude Code features and concepts. The project serves as:
|
||||
|
||||
- A learning resource for developers new to Claude Code
|
||||
- A reference collection of example configurations (slash commands, memory, skills, subagents, MCP, hooks, plugins, checkpoints, advanced features)
|
||||
- A tool for generating offline documentation (EPUB format)
|
||||
|
||||
**Goals:**
|
||||
1. Provide clear, numbered learning paths (01-09) for Claude Code features
|
||||
2. Include ready-to-use example configurations users can copy to their projects
|
||||
3. Generate an EPUB ebook from the documentation for offline reading
|
||||
4. Maintain high-quality Python tooling with CI/CD automation
|
||||
|
||||
## Tech Stack
|
||||
|
||||
### Primary Technologies
|
||||
- **Python 3.10+** - EPUB builder script and tooling
|
||||
- **Markdown** - Documentation content (all guides and examples)
|
||||
- **JSON/YAML** - Configuration files (MCP configs, plugin definitions)
|
||||
- **Shell Scripts** - Hook examples in `06-hooks/`
|
||||
|
||||
### Python Dependencies
|
||||
- `ebooklib` - EPUB generation
|
||||
- `markdown` - Markdown to HTML conversion
|
||||
- `beautifulsoup4` - HTML parsing/manipulation
|
||||
- `httpx` - HTTP client (for Mermaid diagram rendering)
|
||||
- `pillow` - Image processing
|
||||
- `tenacity` - Retry logic for external API calls
|
||||
|
||||
### Development Tools
|
||||
- `uv` - Python package manager and virtual environment
|
||||
- `ruff` - Linting and formatting (replaces black, isort, flake8)
|
||||
- `bandit` - Security scanning
|
||||
- `pytest` / `pytest-asyncio` - Testing framework
|
||||
- `pre-commit` - Git hooks for code quality
|
||||
|
||||
### CI/CD
|
||||
- **GitHub Actions** - Automated linting, security scanning, testing, and EPUB builds
|
||||
- Workflows in `.github/workflows/ci.yml` and `.github/workflows/release.yml`
|
||||
|
||||
## Project Conventions
|
||||
|
||||
### Code Style
|
||||
- **Python**: Ruff for linting and formatting
|
||||
- Line length: 88 characters
|
||||
- Target: Python 3.10
|
||||
- Double quotes, space indentation
|
||||
- Import sorting: isort rules via Ruff
|
||||
- **Markdown**: Standard GitHub-Flavored Markdown
|
||||
- **YAML/JSON**: Validated via pre-commit hooks
|
||||
|
||||
### Architecture Patterns
|
||||
- **Numbered directories** (01-09) for learning progression
|
||||
- **Each feature folder** contains:
|
||||
- Example files demonstrating the feature
|
||||
- `README.md` with detailed explanations
|
||||
- **Scripts directory** contains Python tooling:
|
||||
- `build_epub.py` - Main EPUB builder with async Mermaid rendering
|
||||
- `tests/` - pytest test suite
|
||||
|
||||
### Testing Strategy
|
||||
- **Unit tests** in `scripts/tests/`
|
||||
- **Pytest** with `pytest-asyncio` for async code
|
||||
- **CI runs tests** on every push/PR to `main`
|
||||
- **Test coverage** focused on EPUB builder functionality
|
||||
|
||||
### Git Workflow
|
||||
- **Main branch**: `main`
|
||||
- **PRs required** for contributions
|
||||
- **Pre-commit hooks** enforce:
|
||||
- Ruff lint and format
|
||||
- Bandit security scan
|
||||
- YAML/TOML validation
|
||||
- Trailing whitespace and EOF fixes
|
||||
- **Commit messages**: Descriptive, no co-author attribution required
|
||||
- **No time estimates** in commits or PRs
|
||||
|
||||
## Domain Context
|
||||
|
||||
### Claude Code Concepts
|
||||
This repository covers nine major Claude Code features:
|
||||
|
||||
1. **Slash Commands** - User-invoked shortcuts (`/optimize`, `/pr`)
|
||||
2. **Memory** - Persistent context via `CLAUDE.md` files
|
||||
3. **Skills** - Auto-invoked reusable capabilities
|
||||
4. **Subagents** - Specialized AI assistants with isolated contexts
|
||||
5. **MCP Protocol** - External tool/API access
|
||||
6. **Hooks** - Event-driven shell command automation
|
||||
7. **Plugins** - Bundled feature collections
|
||||
8. **Checkpoints** - Session snapshots and rewind
|
||||
9. **Advanced Features** - Planning mode, extended thinking, background tasks
|
||||
|
||||
### Installation Targets
|
||||
Examples are designed to be copied to:
|
||||
- `~/.claude/` - Personal/global configurations
|
||||
- `.claude/` - Project-specific configurations
|
||||
- Root project directory - For `CLAUDE.md` memory files
|
||||
|
||||
## Important Constraints
|
||||
|
||||
- **Python 3.10+** required for all scripts
|
||||
- **Virtual environment** must be activated before running Python (configured in `~/.claude/CLAUDE.md`)
|
||||
- **No Claude co-author** in commit messages (per user preferences)
|
||||
- **No auto-commits/pushes** without explicit user request
|
||||
- **Large files** limited to 1MB (pre-commit hook)
|
||||
- **Security scans** must pass (Bandit)
|
||||
|
||||
## External Dependencies
|
||||
|
||||
### External Services
|
||||
- **Mermaid.ink API** - Renders Mermaid diagrams to images for EPUB
|
||||
- Used in `build_epub.py` with retry logic via `tenacity`
|
||||
- Rate limiting handled with exponential backoff
|
||||
|
||||
### GitHub Integration
|
||||
- **GitHub Actions** for CI/CD
|
||||
- **GitHub Releases** for versioned EPUB distribution
|
||||
- Example MCP configurations reference GitHub API tokens
|
||||
|
||||
### No Runtime External Dependencies
|
||||
- Documentation is static markdown
|
||||
- EPUB can be built offline (diagrams cached or skip rendering)
|
||||
Reference in New Issue
Block a user