Initial commit

skills/create-slash-commands/references/tool-restrictions.md

@@ -0,0 +1,376 @@
+# Tool Restrictions Reference
+
+Official documentation on restricting tool access in slash commands.
+
+## Why Restrict Tools
+
+Tool restrictions provide:
+- **Security**: Prevent accidental destructive operations
+- **Focus**: Limit scope for specialized commands
+- **Safety**: Ensure commands only perform intended operations
+
+## allowed-tools Field
+
+**Location**: YAML frontmatter
+
+**Format**: Array of tool names or patterns
+
+**Default**: If omitted, all tools available
+
+## Basic Patterns
+
+### Array Format
+
+```yaml
+---
+description: My command
+allowed-tools: [Read, Edit, Write]
+---
+```
+
+### Single Tool
+
+```yaml
+---
+description: Thinking command
+allowed-tools: SequentialThinking
+---
+```
+
+## Bash Command Restrictions
+
+**Source**: Official Claude Code documentation
+
+Restrict bash commands to specific patterns using wildcards.
+
+### Git-Only Commands
+
+```yaml
+---
+description: Create a git commit
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+---
+```
+
+**Allows**:
+- `git add <anything>`
+- `git status <anything>`
+- `git commit <anything>`
+
+**Prevents**:
+- `rm -rf`
+- `curl <url>`
+- Any non-git bash commands
+
+### NPM Script Restrictions
+
+```yaml
+---
+description: Run tests and lint
+allowed-tools: Bash(npm test:*), Bash(npm run lint:*)
+---
+```
+
+**Allows**:
+- `npm test`
+- `npm test -- --watch`
+- `npm run lint`
+- `npm run lint:fix`
+
+**Prevents**:
+- `npm install malicious-package`
+- `npm run deploy`
+- Other npm commands
+
+### Multiple Bash Patterns
+
+```yaml
+---
+description: Development workflow
+allowed-tools: Bash(git status:*), Bash(npm test:*), Bash(npm run build:*)
+---
+```
+
+Combines multiple bash command patterns.
+
+## Common Tool Restriction Patterns
+
+### Pattern 1: Git Workflows
+
+**Use case**: Commands that create commits, check status, etc.
+
+```yaml
+---
+description: Create a git commit
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(git commit:*)
+---
+
+Current status: ! `git status`
+Changes: ! `git diff HEAD`
+
+Create a commit for these changes.
+```
+
+**Security benefit**: Cannot accidentally run destructive commands like `rm -rf` or `curl malicious-site.com`
+
+### Pattern 2: Read-Only Analysis
+
+**Use case**: Commands that analyze code without modifying it
+
+```yaml
+---
+description: Analyze codebase for pattern
+allowed-tools: [Read, Grep, Glob]
+---
+
+Search codebase for: $ARGUMENTS
+```
+
+**Security benefit**: Cannot write files or execute code
+
+### Pattern 3: Thinking-Only Commands
+
+**Use case**: Deep analysis or planning without file operations
+
+```yaml
+---
+description: Analyze problem from first principles
+allowed-tools: SequentialThinking
+---
+
+Analyze the current problem from first principles.
+```
+
+**Focus benefit**: Claude focuses purely on reasoning, no file operations
+
+### Pattern 4: Controlled File Operations
+
+**Use case**: Commands that should only read/edit specific types
+
+```yaml
+---
+description: Update documentation
+allowed-tools: [Read, Edit(*.md)]
+---
+
+Update documentation in @ $ARGUMENTS
+```
+
+**Note**: File pattern restrictions may not be supported in all versions.
+
+## Real Examples from Official Docs
+
+### Example 1: Git Commit Command
+
+**Source**: Official Claude Code documentation
+
+```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 (staged and unstaged changes): ! `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.
+```
+
+**Allowed bash commands**:
+- `git add .`
+- `git add file.js`
+- `git status`
+- `git status --short`
+- `git commit -m "message"`
+- `git commit --amend`
+
+**Blocked commands**:
+- `rm file.js`
+- `curl https://malicious.com`
+- `npm install`
+- Any non-git commands
+
+### Example 2: Code Review (No Restrictions)
+
+```markdown
+---
+description: Review this code for security vulnerabilities
+---
+
+Review this code for security vulnerabilities:
+```
+
+**No allowed-tools field** = All tools available
+
+Claude can:
+- Read files
+- Write files
+- Execute bash commands
+- Use any tool
+
+**Use when**: Command needs full flexibility
+
+## When to Restrict Tools
+
+### ✅ Restrict when:
+
+1. **Security-sensitive operations**
+   ```yaml
+   # Git operations only
+   allowed-tools: Bash(git add:*), Bash(git status:*)
+   ```
+
+2. **Focused tasks**
+   ```yaml
+   # Deep thinking only
+   allowed-tools: SequentialThinking
+   ```
+
+3. **Read-only analysis**
+   ```yaml
+   # No modifications
+   allowed-tools: [Read, Grep, Glob]
+   ```
+
+4. **Specific bash commands**
+   ```yaml
+   # Only npm scripts
+   allowed-tools: Bash(npm run test:*), Bash(npm run build:*)
+   ```
+
+### ❌ Don't restrict when:
+
+1. **Command needs flexibility**
+   - Complex workflows
+   - Exploratory tasks
+   - Multi-step operations
+
+2. **Tool needs are unpredictable**
+   - General problem-solving
+   - Debugging unknown issues
+
+3. **Already in safe environment**
+   - Sandboxed execution
+   - Non-production systems
+
+## Best Practices
+
+### 1. Use Wildcards for Command Families
+
+```yaml
+# Good - allows all git commands
+allowed-tools: Bash(git *)
+
+# Better - specific git operations
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+
+# Best - minimal necessary permissions
+allowed-tools: Bash(git status:*), Bash(git diff:*)
+```
+
+### 2. Combine Tool Types Appropriately
+
+```yaml
+# Analysis with optional git context
+allowed-tools: [Read, Grep, Bash(git status:*)]
+```
+
+### 3. Test Restrictions
+
+Create command and verify:
+- Allowed operations work
+- Blocked operations are prevented
+- Error messages are clear
+
+### 4. Document Why
+
+```yaml
+---
+description: Create git commit (restricted to git commands only for security)
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+---
+```
+
+## Tool Types
+
+### File Operations
+- `Read` - Read files
+- `Write` - Write new files
+- `Edit` - Modify existing files
+- `Grep` - Search file contents
+- `Glob` - Find files by pattern
+
+### Execution
+- `Bash(pattern:*)` - Execute bash commands matching pattern
+- `SequentialThinking` - Reasoning tool
+
+### Other
+- `Task` - Invoke subagents
+- `WebSearch` - Search the web
+- `WebFetch` - Fetch web pages
+
+## Security Patterns
+
+### Pattern: Prevent Data Exfiltration
+
+```yaml
+---
+description: Analyze code locally
+allowed-tools: [Read, Grep, Glob, SequentialThinking]
+# No Bash, WebFetch - cannot send data externally
+---
+```
+
+### Pattern: Prevent Destructive Operations
+
+```yaml
+---
+description: Review changes
+allowed-tools: [Read, Bash(git diff:*), Bash(git log:*)]
+# No Write, Edit, git reset, git push --force
+---
+```
+
+### Pattern: Controlled Deployment
+
+```yaml
+---
+description: Deploy to staging
+allowed-tools: Bash(npm run deploy:staging), Bash(git push origin:staging)
+# Cannot deploy to production accidentally
+---
+```
+
+## Limitations
+
+1. **Wildcard patterns** may vary by version
+2. **File-specific restrictions** (like `Edit(*.md)`) may not be supported
+3. **Cannot blacklist** - only whitelist
+4. **All or nothing** for tool types - can't partially restrict
+
+## Testing Tool Restrictions
+
+### Verify Restrictions Work
+
+1. Create command with restrictions
+2. Try to use restricted tool
+3. Confirm operation is blocked
+4. Check error message
+
+Example test:
+```markdown
+---
+description: Test restrictions
+allowed-tools: [Read]
+---
+
+Try to write a file - this should fail.
+```
+
+Expected: Write operations blocked with error message.