@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/extensions/plugin-dev/skills/command-development/references/frontmatter-reference.md

@@ -0,0 +1,508 @@
+# Command Frontmatter Reference
+
+Complete reference for YAML frontmatter fields in slash commands.
+
+## Frontmatter Overview
+
+YAML frontmatter is optional metadata at the start of command files:
+
+```markdown
+---
+description: Brief description
+allowed-tools: Read, Write
+model: sonnet
+argument-hint: [arg1] [arg2]
+---
+
+Command prompt content here...
+```
+
+All fields are optional. Commands work without any frontmatter.
+
+## Field Specifications
+
+### description
+
+**Type:** String
+**Required:** No
+**Default:** First line of command prompt
+**Max Length:** ~60 characters recommended for `/help` display
+
+**Purpose:** Describes what the command does, shown in `/help` output
+
+**Examples:**
+
+```yaml
+description: Review code for security issues
+```
+
+```yaml
+description: Deploy to staging environment
+```
+
+```yaml
+description: Generate API documentation
+```
+
+**Best practices:**
+
+- Keep under 60 characters for clean display
+- Start with verb (Review, Deploy, Generate)
+- Be specific about what command does
+- Avoid redundant "command" or "slash command"
+
+**Good:**
+
+- ✅ "Review PR for code quality and security"
+- ✅ "Deploy application to specified environment"
+- ✅ "Generate comprehensive API documentation"
+
+**Bad:**
+
+- ❌ "This command reviews PRs" (unnecessary "This command")
+- ❌ "Review" (too vague)
+- ❌ "A command that reviews pull requests for code quality, security issues, and best practices" (too long)
+
+### allowed-tools
+
+**Type:** Comma-separated string
+**Required:** No
+**Default:** Inherits from conversation permissions
+
+**Purpose:** Restrict or specify which tools command can use
+
+**Formats:**
+
+**Single tool:**
+
+```yaml
+allowed-tools: Read
+```
+
+**Multiple tools (comma-separated):**
+
+```yaml
+allowed-tools: Read, Write, Edit
+```
+
+```yaml
+allowed-tools: Read, Write, Bash(git:*)
+```
+
+**Tool Patterns:**
+
+**Specific tools:**
+
+```yaml
+allowed-tools: Read, Grep, Edit
+```
+
+**Bash with command filter:**
+
+```yaml
+allowed-tools: Bash(git:*)           # Only git commands
+allowed-tools: Bash(npm:*)           # Only npm commands
+allowed-tools: Bash(docker:*)        # Only docker commands
+```
+
+**All tools (not recommended):**
+
+```yaml
+allowed-tools: "*"
+```
+
+**When to use:**
+
+1. **Security:** Restrict command to safe operations
+
+   ```yaml
+   allowed-tools: Read, Grep # Read-only command
+   ```
+
+2. **Clarity:** Document required tools
+
+   ```yaml
+   allowed-tools: Bash(git:*), Read
+   ```
+
+3. **Bash execution:** Enable bash command output
+   ```yaml
+   allowed-tools: Bash(git status:*), Bash(git diff:*)
+   ```
+
+**Best practices:**
+
+- Be as restrictive as possible
+- Use command filters for Bash (e.g., `git:*` not `*`)
+- Only specify when different from conversation permissions
+- Document why specific tools are needed
+
+### model
+
+**Type:** String
+**Required:** No
+**Default:** Inherits from conversation
+**Values:**
+
+- Shorthand: `sonnet`, `opus`, `haiku`
+- Full model ID: Format is `claude-<family>-<version>-<date>` (e.g., `claude-sonnet-4-5-20250929`)
+
+Both formats are accepted. Shorthand names use the current default version of each model family.
+
+> **Note:** Anthropic releases new model versions periodically. For current model IDs, consult [Claude Models Overview](https://docs.anthropic.com/en/docs/about-claude/models). Prefer shorthand names unless you need a specific version.
+
+**Purpose:** Specify which Claude model executes the command
+
+**Examples:**
+
+```yaml
+model: haiku # Fast, efficient for simple tasks
+```
+
+```yaml
+model: sonnet # Balanced performance (default)
+```
+
+```yaml
+model: opus # Maximum capability for complex tasks
+```
+
+**When to use:**
+
+**Use `haiku` for:**
+
+- Simple, formulaic commands
+- Fast execution needed
+- Low complexity tasks
+- Frequent invocations
+
+```yaml
+---
+description: Format code file
+model: haiku
+---
+```
+
+**Use `sonnet` for:**
+
+- Standard commands (default)
+- Balanced speed/quality
+- Most common use cases
+
+```yaml
+---
+description: Review code changes
+model: sonnet
+---
+```
+
+**Use `opus` for:**
+
+- Complex analysis
+- Architectural decisions
+- Deep code understanding
+- Critical tasks
+
+```yaml
+---
+description: Analyze system architecture
+model: opus
+---
+```
+
+**Best practices:**
+
+- Omit unless specific need
+- Use `haiku` for speed when possible
+- Reserve `opus` for genuinely complex tasks
+- Test with different models to find right balance
+
+### argument-hint
+
+**Type:** String
+**Required:** No
+**Default:** None
+
+**Purpose:** Document expected arguments for users and autocomplete
+
+**Format:**
+
+```yaml
+argument-hint: [arg1] [arg2] [optional-arg]
+```
+
+**Examples:**
+
+**Single argument:**
+
+```yaml
+argument-hint: [pr-number]
+```
+
+**Multiple required arguments:**
+
+```yaml
+argument-hint: [environment] [version]
+```
+
+**Optional arguments:**
+
+```yaml
+argument-hint: [file-path] [options]
+```
+
+**Descriptive names:**
+
+```yaml
+argument-hint: [source-branch] [target-branch] [commit-message]
+```
+
+**Best practices:**
+
+- Use square brackets `[]` for each argument
+- Use descriptive names (not `arg1`, `arg2`)
+- Indicate optional vs required in description
+- Match order to positional arguments in command
+- Keep concise but clear
+
+**Examples by pattern:**
+
+**Simple command:**
+
+```yaml
+---
+description: Fix issue by number
+argument-hint: [issue-number]
+---
+Fix issue #$1...
+```
+
+**Multi-argument:**
+
+```yaml
+---
+description: Deploy to environment
+argument-hint: [app-name] [environment] [version]
+---
+
+Deploy $1 to $2 using version $3...
+```
+
+**With options:**
+
+```yaml
+---
+description: Run tests with options
+argument-hint: [test-pattern] [options]
+---
+
+Run tests matching $1 with options: $2
+```
+
+### disable-model-invocation
+
+**Type:** Boolean
+**Required:** No
+**Default:** false
+
+**Purpose:** Prevent Skill tool from programmatically invoking command
+
+**Examples:**
+
+```yaml
+disable-model-invocation: true
+```
+
+**When to use:**
+
+1. **Manual-only commands:** Commands requiring user judgment
+
+   ```yaml
+   ---
+   description: Approve deployment to production
+   disable-model-invocation: true
+   ---
+   ```
+
+2. **Destructive operations:** Commands with irreversible effects
+
+   ```yaml
+   ---
+   description: Delete all test data
+   disable-model-invocation: true
+   ---
+   ```
+
+3. **Interactive workflows:** Commands needing user input
+   ```yaml
+   ---
+   description: Walk through setup wizard
+   disable-model-invocation: true
+   ---
+   ```
+
+**Default behavior (false):**
+
+- Command available to Skill tool
+- Claude can invoke programmatically
+- Still available for manual invocation
+
+**When true:**
+
+- Command only invokable by user typing `/command`
+- Not available to Skill tool
+- Safer for sensitive operations
+
+**Best practices:**
+
+- Use sparingly (limits Claude's autonomy)
+- Document why in command comments
+- Consider if command should exist if always manual
+
+## Complete Examples
+
+### Minimal Command
+
+No frontmatter needed:
+
+```markdown
+Review this code for common issues and suggest improvements.
+```
+
+### Simple Command
+
+Just description:
+
+```markdown
+---
+description: Review code for issues
+---
+
+Review this code for common issues and suggest improvements.
+```
+
+### Standard Command
+
+Description and tools:
+
+```markdown
+---
+description: Review Git changes
+allowed-tools: Bash(git:*), Read
+---
+
+Current changes: `git diff --name-only`
+
+Review each changed file for:
+
+- Code quality
+- Potential bugs
+- Best practices
+```
+
+### Complex Command
+
+All common fields:
+
+```markdown
+---
+description: Deploy application to environment
+argument-hint: [app-name] [environment] [version]
+allowed-tools: Bash(kubectl:*), Bash(helm:*), Read
+model: sonnet
+---
+
+Deploy $1 to $2 environment using version $3
+
+Pre-deployment checks:
+
+- Verify $2 configuration
+- Check cluster status: `kubectl cluster-info`
+- Validate version $3 exists
+
+Proceed with deployment following deployment runbook.
+```
+
+### Manual-Only Command
+
+Restricted invocation:
+
+```markdown
+---
+description: Approve production deployment
+argument-hint: [deployment-id]
+disable-model-invocation: true
+allowed-tools: Bash(gh:*)
+---
+
+<!--
+MANUAL APPROVAL REQUIRED
+This command requires human judgment and cannot be automated.
+-->
+
+Review deployment $1 for production approval:
+
+Deployment details: `gh api /deployments/$1`
+
+Verify:
+
+- All tests passed
+- Security scan clean
+- Stakeholder approval
+- Rollback plan ready
+
+Type "APPROVED" to confirm deployment.
+```
+
+## Validation
+
+### Common Errors
+
+**Invalid YAML syntax:**
+
+```yaml
+---
+description: Missing quote
+allowed-tools: Read, Write
+model: sonnet
+--- # ❌ Missing closing quote above
+```
+
+**Fix:** Validate YAML syntax
+
+**Incorrect tool specification:**
+
+```yaml
+allowed-tools: Bash # ❌ Missing command filter
+```
+
+**Fix:** Use `Bash(git:*)` format
+
+**Invalid model name:**
+
+```yaml
+model: gpt4 # ❌ Not a valid Claude model
+```
+
+**Fix:** Use shorthand (`sonnet`, `opus`, `haiku`) or full model ID (see [Claude Models Overview](https://docs.anthropic.com/en/docs/about-claude/models))
+
+### Validation Checklist
+
+Before committing command:
+
+- [ ] YAML syntax valid (no errors)
+- [ ] Description under 60 characters
+- [ ] allowed-tools uses proper format
+- [ ] model is valid value if specified
+- [ ] argument-hint matches positional arguments
+- [ ] disable-model-invocation used appropriately
+
+## Best Practices Summary
+
+1. **Start minimal:** Add frontmatter only when needed
+2. **Document arguments:** Always use argument-hint with arguments
+3. **Restrict tools:** Use most restrictive allowed-tools that works
+4. **Choose right model:** Use haiku for speed, opus for complexity
+5. **Manual-only sparingly:** Only use disable-model-invocation when necessary
+6. **Clear descriptions:** Make commands discoverable in `/help`
+7. **Test thoroughly:** Verify frontmatter works as expected