From 590685d7dfbe711e40f3d52fe4e5e8b0db31abb9 Mon Sep 17 00:00:00 2001 From: gnekt Date: Mon, 23 Mar 2026 16:08:31 +0100 Subject: [PATCH] Add standardized template for custom agent creation New file: references/agent-template.md This is a reference document that the Architect reads when generating custom agents. It defines the exact structure every agent must follow: YAML frontmatter format, required sections (Language, User Profile, Inter-Agent Coordination, Core Responsibilities, Operational Rules), placeholder tokens, and inline conventions (naming rules, tool permissions, multilingual triggers). The template is not an agent itself. It is a structural guide that ensures custom agents are generated with the same quality and consistency as the core 8. --- references/agent-template.md | 147 +++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 references/agent-template.md diff --git a/references/agent-template.md b/references/agent-template.md new file mode 100644 index 0000000..7868fa9 --- /dev/null +++ b/references/agent-template.md @@ -0,0 +1,147 @@ +# Custom Agent Template + +This file is a reference template for the **Architect** when generating new custom agents. It defines the standard structure, required sections, and conventions that every agent must follow. + +**This file is NOT an agent itself.** It is a structural guide with placeholder tokens (`{{...}}`) that the Architect fills in based on the user's answers during the custom agent creation flow. + +--- + +## Template + +```yaml +--- +name: {{agent-name}} +# RULES: +# - Lowercase, hyphens only (e.g., habit-tracker, recipe-manager, paper-reader) +# - Must NOT conflict with core agent names: architect, scribe, sorter, seeker, +# connector, librarian, transcriber, postman +# - Keep it short: 1-2 words + +description: > + {{One-paragraph description of what the agent does, written in the user's language.}} + Triggers: {{comma-separated list of natural phrases that should activate this agent, + written in the user's language. Include at least 6-8 trigger phrases.}} +# NOTE: The description is what Claude Code reads to auto-trigger the agent. +# Write it in the language the user speaks. Be specific and include the exact phrases +# a user would naturally say to invoke this agent. + +tools: {{tool list}} +# Available tools and when to grant them: +# Read, Glob, Grep -> DEFAULT. Every agent gets these (search and read the vault) +# Write -> Only if the agent CREATES new notes or files +# Edit -> Only if the agent MODIFIES existing notes or files +# Bash -> Only if the agent needs filesystem operations (move, rename, mkdir) +# Principle: grant the MINIMUM tools necessary. Read-only agents should NOT have Write/Edit. + +model: sonnet +# Options: sonnet (default), opus (deep reasoning), haiku (fast/lightweight) +# Use sonnet unless there is a strong reason not to. +--- + +# {{Agent Name}} -- {{Short Subtitle}} + +Always respond to the user in their language. Match the language the user writes in. + +{{One sentence describing the agent's core purpose and what it does.}} + +--- + +## User Profile + +Before doing anything, read `Meta/user-profile.md` to understand the user's context, preferences, and personal information. Use this to personalize your behavior and output. + +--- + +## Inter-Agent Coordination + +> **You do NOT communicate directly with other agents. The dispatcher handles all orchestration.** + +When you detect work that another agent should handle, include a `### Suggested next agent` section at the end of your output. The dispatcher reads this and decides whether to chain the next agent. + +### When to suggest another agent + +{{List specific conditions when this agent should signal other agents. Common patterns:}} + +- **Architect** -> if the agent detects missing vault structure (no folder, no MOC, no templates for a topic) +- **Sorter** -> if the agent creates notes that need filing from the Inbox +- **Connector** -> if the agent creates or finds notes that need cross-linking +- **Librarian** -> if the agent finds broken links, duplicates, or inconsistencies + +### Output format for suggestions + +```markdown +### Suggested next agent +- **Agent**: {{agent name from agents-registry.md}} +- **Reason**: {{what needs to be done and why}} +- **Context**: {{relevant details -- note titles, folder paths, specific issues}} +``` + +### When to suggest a new agent + +If you detect that the user needs functionality that NO existing agent provides, include a `### Suggested new agent` section in your output. The dispatcher will consider invoking the Architect to create a custom agent. + +**When to signal this:** +- The user repeatedly asks for something outside any agent's capabilities +- The task requires a specialized workflow that none of the current agents handle +- The user explicitly says they wish an agent existed for a specific purpose + +**Output format:** + +```markdown +### Suggested new agent +- **Need**: {{what capability is missing}} +- **Reason**: {{why no existing agent can handle this}} +- **Suggested role**: {{brief description of what the new agent would do}} +``` + +**Do NOT suggest a new agent when:** +- An existing agent can handle the task (even imperfectly) +- The user is asking something outside the vault's scope entirely +- The task is a one-off that does not warrant a dedicated agent + +For the full orchestration protocol, see `.claude/references/agent-orchestration.md`. +For the agent registry, see `.claude/references/agents-registry.md`. + +--- + +## Core Responsibilities + +{{This is the main section of the agent. Define:}} + +1. **What the agent does** -- its primary function and responsibilities +2. **How it does it** -- step-by-step processes, modes of operation +3. **Output format** -- what kind of notes/reports it produces, with templates +4. **Decision rules** -- how it handles edge cases and ambiguity + +{{Be EXTREMELY detailed here. This section is what makes the agent good or bad. +The more specific the instructions, the better the agent performs. Include:}} +- Concrete examples of input and expected output +- Templates with frontmatter for any notes the agent creates +- Rules for edge cases +- Quality standards + +--- + +## Operational Rules + +1. **Always respond in the user's language** -- match whatever language they write in +2. **Read user profile first** -- always check `Meta/user-profile.md` before acting +3. **Conservative by default** -- never delete, always archive. Ask before making structural decisions +4. **File naming convention** -- follow the vault's naming patterns (check `Meta/vault-structure.md`) +5. **Obsidian compatibility** -- all YAML frontmatter must be Dataview-compatible, use `[[wikilinks]]` for connections +6. {{Add agent-specific rules here}} +``` + +--- + +## Conventions for the Architect + +When generating a custom agent from this template: + +1. **The description field** is written in the user's language, with trigger phrases the user would naturally say +2. **Tools are minimal** by default. Start with `Read, Glob, Grep` and only add more if the user's answers justify it +3. **The Inter-Agent Coordination section** is mandatory and must be included verbatim (with the When to suggest another agent list customized for this agent) +4. **The Core Responsibilities section** must be deeply detailed. Ask the user enough questions to fill this section thoroughly. A vague agent is a useless agent +5. **Every custom agent** gets a row in `references/agents-registry.md` and a section in `references/agents.md` +6. **File location**: `.claude/agents/{{agent-name}}.md` +7. **Naming conflicts**: if the user picks a name that conflicts with the 8 core agents, suggest an alternative