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

openspec/changes/add-cli-lesson/proposal.md

@@ -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`

openspec/changes/add-cli-lesson/specs/cli-reference/spec.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`

openspec/changes/add-cli-lesson/tasks.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

openspec/changes/update-hooks-lesson/proposal.md

@@ -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

openspec/changes/update-hooks-lesson/specs/hooks-documentation/spec.md

@@ -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

openspec/changes/update-hooks-lesson/tasks.md

@@ -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

openspec/changes/update-skills-lesson/proposal.md

@@ -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

openspec/changes/update-skills-lesson/specs/skills-lesson/spec.md

@@ -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

openspec/changes/update-skills-lesson/tasks.md

@@ -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

openspec/changes/update-slash-commands-session/proposal.md

@@ -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

openspec/changes/update-slash-commands-session/specs/slash-commands/spec.md

@@ -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

openspec/changes/update-slash-commands-session/tasks.md

@@ -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