Add new frontmatter fields from Claude Code 2.1.0
Update documentation and apply new frontmatter capabilities: Documentation: - Add user-invocable, context, agent, hooks fields to writing-skills.md - Add disallowedTools, permissionMode, hooks fields to writing-agents.md - Add model, context, hooks, allowed-tools fields to writing-commands.md - Document skill hot-reload, built-in agents, background execution Skills: - Add user-invocable: false to gitea (CLI reference) - Add user-invocable: false to repo-conventions (standards reference) Commands: - Add context: fork to heavy exploration commands (improve, plan-issues, create-repo, update-claude-md) - Add missing argument-hint to roadmap, manifesto, improve Agents: - Add disallowedTools: [Edit, Write] to code-reviewer for safety Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -67,6 +67,90 @@ All sections are important:
|
||||
- **When to Use**: Prevents misuse and guides selection
|
||||
- **Behavior**: Sets expectations for operation
|
||||
|
||||
## YAML Frontmatter
|
||||
|
||||
Agent files support YAML frontmatter for configuration. While the body content defines the agent's personality and instructions, frontmatter controls its technical behavior.
|
||||
|
||||
### Required Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `name` | Agent identifier (lowercase, hyphens). Should match directory name. |
|
||||
| `description` | What the agent does. Used for matching when spawning agents. |
|
||||
|
||||
### Optional Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `model` | Model to use: `haiku`, `sonnet`, `opus`, or `inherit` (default). |
|
||||
| `skills` | Comma-separated list of skills the agent can access. |
|
||||
| `disallowedTools` | Explicitly block specific tools from this agent. |
|
||||
| `permissionMode` | Permission behavior: `default`, `bypassPermissions`, or custom. |
|
||||
| `hooks` | Define PreToolUse, PostToolUse, or Stop hooks scoped to this agent. |
|
||||
|
||||
### Example Frontmatter
|
||||
|
||||
**Basic agent:**
|
||||
```yaml
|
||||
---
|
||||
name: code-reviewer
|
||||
description: Review code for quality, bugs, and style issues.
|
||||
model: sonnet
|
||||
skills: gitea, code-review
|
||||
---
|
||||
```
|
||||
|
||||
**Agent with tool restrictions:**
|
||||
```yaml
|
||||
---
|
||||
name: read-only-analyst
|
||||
description: Analyze code without making changes.
|
||||
model: haiku
|
||||
skills: code-review
|
||||
disallowedTools:
|
||||
- Edit
|
||||
- Write
|
||||
- Bash
|
||||
---
|
||||
```
|
||||
|
||||
**Agent with hooks:**
|
||||
```yaml
|
||||
---
|
||||
name: database-admin
|
||||
description: Manage database operations safely.
|
||||
model: opus
|
||||
hooks:
|
||||
- type: PreToolUse
|
||||
matcher: Bash
|
||||
command: echo "Validating database command..."
|
||||
- type: Stop
|
||||
command: echo "Database operation completed"
|
||||
---
|
||||
```
|
||||
|
||||
### Permission Modes
|
||||
|
||||
The `permissionMode` field controls how the agent handles tool permissions:
|
||||
|
||||
| Mode | Behavior |
|
||||
|------|----------|
|
||||
| `default` | Inherits parent's permission settings (standard behavior) |
|
||||
| `bypassPermissions` | Skip permission prompts (use for trusted, well-tested agents) |
|
||||
|
||||
Use `bypassPermissions` sparingly—only for agents that are thoroughly tested and operate within safe boundaries.
|
||||
|
||||
## Built-in Agents
|
||||
|
||||
Claude Code provides built-in agents that you can leverage instead of creating custom ones:
|
||||
|
||||
| Agent | Purpose | When to Use |
|
||||
|-------|---------|-------------|
|
||||
| **Explore** | Codebase exploration and search | Finding files, understanding structure, searching code. Powered by Haiku for efficiency. |
|
||||
| **Plan** | Implementation planning | Designing approaches, breaking down tasks, architectural decisions. |
|
||||
|
||||
Consider using built-in agents before creating custom ones—they're optimized for common tasks.
|
||||
|
||||
## How Agents Combine Skills
|
||||
|
||||
Agents gain their expertise by combining multiple skills. Each skill contributes domain knowledge to the agent's overall capability.
|
||||
@@ -187,6 +271,28 @@ Agents can explore codebases independently, building understanding without pollu
|
||||
- Exploration might involve many file reads and searches
|
||||
- Results should be summarized, not shown in full
|
||||
|
||||
### 5. Background Execution
|
||||
|
||||
Agents can run in the background while you continue working. Background agents execute asynchronously and notify the main thread when complete.
|
||||
|
||||
```
|
||||
User working Background Agent
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ Continue coding │ │ Running tests │
|
||||
│ on feature │ │ in background │
|
||||
│ │ │ │
|
||||
│ (not blocked) │ notify │ (async work) │
|
||||
│ │ ◄───────── │ │
|
||||
└─────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
- Task is long-running (test suites, large codebase analysis)
|
||||
- You want to continue working while the agent operates
|
||||
- Results are needed later, not immediately
|
||||
|
||||
Background agents can send messages to wake up the main agent when they have results or need attention.
|
||||
|
||||
## When to Use an Agent vs Direct Skill Invocation
|
||||
|
||||
### Use Direct Skill Invocation When:
|
||||
@@ -573,14 +679,26 @@ Improve based on usage:
|
||||
|
||||
## Checklist: Before Submitting a New Agent
|
||||
|
||||
### Structure
|
||||
- [ ] File is at `agents/<name>/AGENT.md`
|
||||
- [ ] Name follows kebab-case convention
|
||||
- [ ] Agent has a clear, recognizable role
|
||||
- [ ] Skills list is deliberate (not too many, not too few)
|
||||
- [ ] Model selection is deliberate (not just `inherit` by default)
|
||||
|
||||
### Frontmatter
|
||||
- [ ] `name` and `description` fields are set
|
||||
- [ ] `model` selection is deliberate (not just `inherit` by default)
|
||||
- [ ] `skills` list is deliberate (not too many, not too few)
|
||||
- [ ] Consider `disallowedTools` if agent should be restricted
|
||||
- [ ] Consider `permissionMode` for trusted agents
|
||||
- [ ] Consider `hooks` for validation or logging
|
||||
|
||||
### Content
|
||||
- [ ] Capabilities are specific and achievable
|
||||
- [ ] "When to Use" guidance is clear
|
||||
- [ ] Behavioral rules prevent problems
|
||||
|
||||
### Integration
|
||||
- [ ] Consider if built-in agents (Explore, Plan) could be used instead
|
||||
- [ ] Agent is referenced by at least one command
|
||||
- [ ] ARCHITECTURE.md is updated
|
||||
|
||||
|
||||
@@ -43,10 +43,21 @@ argument-hint: <required-arg> [optional-arg]
|
||||
---
|
||||
```
|
||||
|
||||
| Field | Purpose | Required |
|
||||
|-------|---------|----------|
|
||||
| `description` | One-line summary for help/listings | Yes |
|
||||
| `argument-hint` | Shows expected arguments | If arguments needed |
|
||||
#### Required Fields
|
||||
|
||||
| Field | Purpose |
|
||||
|-------|---------|
|
||||
| `description` | One-line summary for help/listings |
|
||||
|
||||
#### Optional Fields
|
||||
|
||||
| Field | Purpose |
|
||||
|-------|---------|
|
||||
| `argument-hint` | Shows expected arguments (e.g., `<issue-number>`, `[title]`) |
|
||||
| `model` | Model to use: `haiku`, `sonnet`, `opus`. Overrides session default. |
|
||||
| `context` | Execution context. Use `fork` to run in isolated sub-agent context. |
|
||||
| `hooks` | Define PreToolUse, PostToolUse, or Stop hooks scoped to this command. |
|
||||
| `allowed-tools` | Restrict which tools the command can use. |
|
||||
|
||||
### 2. Body (Markdown Instructions)
|
||||
|
||||
@@ -83,6 +94,50 @@ argument-hint: <issue-number>
|
||||
7. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
|
||||
```
|
||||
|
||||
## Advanced Frontmatter Examples
|
||||
|
||||
**Command with specific model:**
|
||||
```yaml
|
||||
---
|
||||
description: Plan complex feature implementation.
|
||||
argument-hint: <feature-description>
|
||||
model: opus
|
||||
---
|
||||
```
|
||||
|
||||
**Command with isolated context (prevents context pollution):**
|
||||
```yaml
|
||||
---
|
||||
description: Analyze codebase architecture deeply.
|
||||
context: fork
|
||||
model: haiku
|
||||
---
|
||||
```
|
||||
|
||||
**Command with hooks:**
|
||||
```yaml
|
||||
---
|
||||
description: Deploy to production environment.
|
||||
hooks:
|
||||
- type: PreToolUse
|
||||
matcher: Bash
|
||||
command: echo "Validating deployment command..."
|
||||
- type: Stop
|
||||
command: ./scripts/notify-deployment.sh
|
||||
---
|
||||
```
|
||||
|
||||
**Read-only command with tool restrictions:**
|
||||
```yaml
|
||||
---
|
||||
description: Generate codebase report without modifications.
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Glob
|
||||
- Grep
|
||||
---
|
||||
```
|
||||
|
||||
## Argument Handling
|
||||
|
||||
Commands can accept arguments from the user. Arguments are passed via positional variables: `$1`, `$2`, etc.
|
||||
@@ -643,16 +698,29 @@ Update references:
|
||||
|
||||
## Checklist: Before Submitting a New Command
|
||||
|
||||
### Structure
|
||||
- [ ] File is at `commands/<name>.md`
|
||||
- [ ] Name follows kebab-case verb convention
|
||||
- [ ] Frontmatter includes description
|
||||
- [ ] Frontmatter includes argument-hint (if arguments needed)
|
||||
|
||||
### Frontmatter (Required)
|
||||
- [ ] `description` is set with clear one-line summary
|
||||
- [ ] `argument-hint` is set (if command takes arguments)
|
||||
|
||||
### Frontmatter (Consider)
|
||||
- [ ] `model` if command benefits from specific model (e.g., `opus` for complex planning)
|
||||
- [ ] `context: fork` if command does heavy exploration that would pollute context
|
||||
- [ ] `allowed-tools` if command should be restricted to certain tools
|
||||
- [ ] `hooks` if command needs validation or post-execution actions
|
||||
|
||||
### Content
|
||||
- [ ] Workflow steps are clear and numbered
|
||||
- [ ] Commands and tools are specified explicitly
|
||||
- [ ] Skills are included via `@~/.claude/skills/<name>/SKILL.md` file references
|
||||
- [ ] Approval points exist before significant actions
|
||||
- [ ] Edge cases are handled (no data, invalid input)
|
||||
- [ ] Output formatting is specified
|
||||
|
||||
### Integration
|
||||
- [ ] ARCHITECTURE.md is updated with new command
|
||||
|
||||
## See Also
|
||||
|
||||
@@ -29,8 +29,12 @@ Every `SKILL.md` file **must** start with YAML frontmatter. This is how Claude d
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `allowed-tools` | **Restricts** which tools Claude can use when this skill is active. If omitted, no restrictions apply. |
|
||||
| `model` | Specific model to use when skill is active (e.g., `claude-sonnet-4-20250514`). |
|
||||
| `allowed-tools` | **Restricts** which tools Claude can use when this skill is active. If omitted, no restrictions apply. Supports YAML-style lists. |
|
||||
| `model` | Specific model to use when skill is active (e.g., `sonnet`, `opus`, `haiku`). |
|
||||
| `user-invocable` | Whether the skill appears in the `/` command menu. Defaults to `true`. Set to `false` for reference-only skills. |
|
||||
| `context` | Execution context. Use `fork` to run skill in an isolated sub-agent context, preventing context pollution. |
|
||||
| `agent` | Agent type to use for execution. Allows skills to specify which agent handles them. |
|
||||
| `hooks` | Define PreToolUse, PostToolUse, or Stop hooks scoped to this skill's lifecycle. |
|
||||
|
||||
### Writing Effective Descriptions
|
||||
|
||||
@@ -55,6 +59,7 @@ description: View, create, and manage Gitea issues and pull requests using tea C
|
||||
---
|
||||
name: gitea
|
||||
description: View, create, and manage Gitea issues and pull requests using tea CLI. Use when working with issues, PRs, viewing issue details, creating pull requests, or when the user mentions tea, gitea, or issue numbers.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Gitea CLI (tea)
|
||||
@@ -62,6 +67,51 @@ description: View, create, and manage Gitea issues and pull requests using tea C
|
||||
[Rest of skill content...]
|
||||
```
|
||||
|
||||
### Advanced Frontmatter Examples
|
||||
|
||||
**Reference skill (not directly invocable):**
|
||||
```yaml
|
||||
---
|
||||
name: gitea
|
||||
description: CLI reference for Gitea operations.
|
||||
user-invocable: false
|
||||
---
|
||||
```
|
||||
|
||||
**Skill with isolated context:**
|
||||
```yaml
|
||||
---
|
||||
name: codebase-analysis
|
||||
description: Deep codebase exploration and analysis.
|
||||
context: fork
|
||||
model: haiku
|
||||
---
|
||||
```
|
||||
|
||||
**Skill with tool restrictions (YAML-style list):**
|
||||
```yaml
|
||||
---
|
||||
name: read-only-review
|
||||
description: Code review without modifications.
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Glob
|
||||
- Grep
|
||||
---
|
||||
```
|
||||
|
||||
**Skill with hooks:**
|
||||
```yaml
|
||||
---
|
||||
name: database-operations
|
||||
description: Database schema and migration operations.
|
||||
hooks:
|
||||
- type: PreToolUse
|
||||
matcher: Bash
|
||||
command: echo "Validating database command..."
|
||||
---
|
||||
```
|
||||
|
||||
## Subagents and Skills
|
||||
|
||||
Subagents **do not automatically inherit skills** from the main conversation. To give a subagent access to skills, list them in the agent's `skills` field:
|
||||
@@ -153,6 +203,14 @@ Skills are **model-invoked**: Claude decides which skills to use based on your r
|
||||
2. **On request**: Claude matches your request against skill descriptions using semantic similarity
|
||||
3. **Activation**: When a match is found, Claude asks to use the skill before loading the full content
|
||||
|
||||
### Hot Reload
|
||||
|
||||
Skills support **automatic hot-reload**. When you create or modify a skill file in `~/.claude/skills/` or `.claude/skills/`, the changes are immediately available without restarting Claude Code. This enables rapid iteration when developing skills.
|
||||
|
||||
### Visibility in Command Menu
|
||||
|
||||
By default, skills in `/skills/` directories appear in the `/` slash command menu. Users can invoke them directly like commands. To hide a skill from the menu (e.g., for reference-only skills), add `user-invocable: false` to the frontmatter.
|
||||
|
||||
### Subagent Access
|
||||
|
||||
Subagents (defined in `.claude/agents/`) must explicitly list which skills they can use:
|
||||
@@ -493,6 +551,13 @@ Keep skills current:
|
||||
- [ ] `description` lists specific capabilities
|
||||
- [ ] `description` includes "Use when..." with trigger terms
|
||||
|
||||
### Optional Frontmatter (Consider)
|
||||
- [ ] `user-invocable: false` if skill is reference-only (e.g., CLI docs)
|
||||
- [ ] `context: fork` if skill does heavy exploration that would pollute context
|
||||
- [ ] `model` if skill benefits from a specific model (e.g., `haiku` for speed)
|
||||
- [ ] `allowed-tools` if skill should be restricted to certain tools
|
||||
- [ ] `hooks` if skill needs validation or logging
|
||||
|
||||
### File Structure
|
||||
- [ ] File is at `skills/<name>/SKILL.md`
|
||||
- [ ] Name follows kebab-case convention
|
||||
|
||||
Reference in New Issue
Block a user