writing-agents
2
总安装量
2
周安装量
#68881
全站排名
安装命令
npx skills add https://github.com/ian-pascoe/dotfiles --skill writing-agents
Agent 安装分布
opencode
2
claude-code
2
windsurf
1
codex
1
antigravity
1
gemini-cli
1
Skill 文档
Writing Agents
Overview
Agents are specialized AI assistants with custom prompts, models, and tool access. Configure via markdown files or JSON.
When to Use
- Creating a new agent for specific tasks
- Editing agent prompts, permissions, or tool access
- Choosing between primary vs subagent mode
- Setting up task permissions for orchestration
- Reviewing agent configuration quality
Don’t use for: skill files (use writing-skills), system prompts without agent context, or MCP server config.
File Locations
~/.config/opencode/agent/<name>.md # Global agents
.opencode/agent/<name>.md # Project-local agents
opencode.json â agent.<name> # JSON config (either location)
Filename becomes agent name (e.g., review.md â review agent).
Frontmatter Reference
| Field | Required | Values | Notes |
|---|---|---|---|
description |
Yes | string | Brief description for agent selection |
mode |
No | primary, subagent, all |
Default: all |
model |
No | provider/model-id |
Inherits from parent if unset |
temperature |
No | 0.0-1.0 | 0.0-0.2 focused, 0.6-1.0 creative |
maxSteps |
No | integer | Limit agentic iterations |
hidden |
No | boolean | Hide from @ autocomplete (subagents only) |
disable |
No | boolean | Disable the agent |
tools |
No | object | Enable/disable specific tools |
permission |
No | object | Configure ask/allow/deny per tool |
Mode Selection
| Mode | Use Case |
|---|---|
primary |
Main agents user switches between (Tab key) |
subagent |
Invoked by primary agents or via @ mention |
all |
Available in both contexts (default) |
Tool Configuration
tools:
write: false # Disable write tool
edit: false # Disable edit tool
bash: false # Disable bash tool
mymcp_*: false # Wildcards for MCP tools
Permission Configuration
permission:
edit: deny # deny | ask | allow
bash:
"*": ask # Default for all commands
"git status": allow # Specific command override
"git push*": ask # Glob patterns supported
webfetch: deny
task:
"*": deny # Block all subagent invocation
"my-helper-*": allow # Allow specific subagents
Rule evaluation: Last matching rule wins. Put * first, specifics after.
Markdown Template
---
description: <what it does and when to use>
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
write: false
edit: false
bash: false
permission:
edit: deny
---
<system prompt content>
Focus on:
- Point 1
- Point 2
JSON Template
{
"agent": {
"my-agent": {
"description": "What it does",
"mode": "subagent",
"model": "anthropic/claude-sonnet-4-20250514",
"prompt": "{file:./prompts/my-agent.txt}",
"tools": {
"write": false,
"edit": false
},
"permission": {
"bash": {
"*": "ask",
"git diff": "allow"
}
}
}
}
}
Common Patterns
Read-Only Reviewer
tools:
write: false
edit: false
bash: false
Restricted Bash Access
permission:
bash:
"*": ask
"git status": allow
"git log*": allow
"git diff*": allow
Orchestrator with Task Limits
permission:
task:
"*": deny
"my-workers-*": allow
Common Mistakes
| Mistake | Fix |
|---|---|
| Missing description | Always provide clear description |
Using hidden on primary agent |
hidden only works on subagents |
Expecting * to be evaluated last |
Last rule wins – put * first |
| Setting model on subagent | Subagents inherit parent model if unset |
| Narrative prompt style | Focus on role and constraints, not conversation |
Validation Checklist
- Description clearly states purpose and trigger conditions
- Mode matches intended usage (primary vs subagent)
- Tools restricted appropriately for the role
- Permissions use correct ask/allow/deny values
- Bash permission rules ordered correctly (
*first) - Prompt focuses on role, constraints, and focus areas