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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user