Agentsmd Authoring

Optional Sections

9. Hard Constraints — Separate from soft constraints if needed
10. Examples — Show desired input/output patterns

Writing Guidelines

Do:

• Be specific and actionable — "Use @docs-writer for README changes" not "write good docs"
• Front-load the most important constraints
• Use bullet points over paragraphs
• Include the directory layout if the agent needs to navigate files
• State non-obvious conventions explicitly
• Keep total length under 100 lines for child profiles, under 150 for complex root profiles

Don't:

• Repeat information available in opencode.jsonc (tool config, MCP servers)
• Include implementation details that change frequently
• Write aspirational content — only document what's true now
• Use vague instructions like "be careful" or "use best practices"
• Put secrets, API keys, or sensitive paths in AGENTS.md

Template

# <Profile Name>

<One-line description of what this profile does.>

## Purpose
<2-3 sentences explaining the use case and context.>

## Constraints
- <Hard rule 1>
- <Hard rule 2>
- <Hard rule 3>

## Workflow
1. <Step 1>
2. <Step 2>
3. <Step 3>

## Tool Policy
- Prefer <X> over <Y> for <reason>
- Do not use <Z> unless <condition>

## References
- [Link 1](url)
- [Link 2](url)

Review Checklist

• Title is clear and matches the profile's purpose
• Purpose section exists and is concise
• At least 3 specific constraints listed
• No secrets or sensitive information
• Under line limit (100 for child, 150 for root)
• No duplication with opencode.jsonc
• All referenced skills/commands actually exist