From dd53bd37007e57bf0d827f0e7eab463176344501 Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Mon, 29 Dec 2025 00:35:36 +0100 Subject: [PATCH] Update agents to use YAML frontmatter format MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update product-manager agent to use official Claude Code format - Update ARCHITECTURE.md to document frontmatter fields - Add code-reviewer agent and code-review skill to docs - Update README.md project structure This aligns our agent documentation with the official Claude Code agent format which uses YAML frontmatter for name, description, model, skills, and tools. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- ARCHITECTURE.md | 73 ++++++++++++++++++++------------- README.md | 6 ++- agents/product-manager/AGENT.md | 34 ++++++--------- 3 files changed, 60 insertions(+), 53 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 14afef8..4172bea 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -138,6 +138,7 @@ Create a skill when you find yourself: | `issue-writing` | How to structure clear, actionable issues | | `backlog-grooming` | How to review and improve existing issues | | `roadmap-planning` | How to plan features and create issue breakdowns | +| `code-review` | How to review code for quality, bugs, security, and style | --- @@ -149,30 +150,40 @@ Agents are specialized subagents that combine multiple skills into focused perso #### Structure -Each agent file contains: -- **Skills list**: Which skills the agent has access to -- **Capabilities**: What the agent can do -- **When to use**: Guidance on spawning the agent -- **Behavior**: How the agent should operate +Each agent file uses YAML frontmatter followed by a system prompt: ```markdown -# Product Manager Agent +--- +name: agent-name +description: When this agent should be invoked (used for automatic delegation) +model: inherit +skills: skill1, skill2, skill3 +--- -Specialized agent for backlog management and roadmap planning. - -## Skills -- forgejo -- issue-writing -- backlog-grooming -- roadmap-planning +You are a [role] specializing in [domain]. ## Capabilities -This agent can: -- Review and improve existing issues -- Create new well-structured issues -... + +You can: +- Do thing one +- Do thing two + +## Behavior + +- Guideline one +- Guideline two ``` +#### Frontmatter Fields + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | Yes | Unique identifier (lowercase, hyphens) | +| `description` | Yes | When to use this agent (enables auto-delegation) | +| `model` | No | `sonnet`, `opus`, `haiku`, or `inherit` | +| `skills` | No | Comma-separated skill names to auto-load | +| `tools` | No | Limit available tools (inherits all if omitted) | + #### Characteristics - **Isolated context**: Each agent maintains separate conversation state @@ -194,6 +205,7 @@ Create an agent when you need: | Agent | Skills | Use Case | |-------|--------|----------| | `product-manager` | forgejo, issue-writing, backlog-grooming, roadmap-planning | Batch issue operations, backlog reviews, feature planning | +| `code-reviewer` | forgejo, code-review | Automated PR review, quality checks | --- @@ -287,13 +299,13 @@ Claude reads the referenced skill files to gain the necessary knowledge before e ### How Agents Use Skills -Agents list their skills explicitly: +Agents declare their skills in the YAML frontmatter: -```markdown -## Skills -- forgejo -- issue-writing -- backlog-grooming +```yaml +--- +name: product-manager +skills: forgejo, issue-writing, backlog-grooming +--- ``` When spawned, the agent has access to all listed skills as part of its context. @@ -362,10 +374,14 @@ ai/ │ │ └── SKILL.md │ ├── backlog-grooming/ │ │ └── SKILL.md -│ └── roadmap-planning/ +│ ├── roadmap-planning/ +│ │ └── SKILL.md +│ └── code-review/ │ └── SKILL.md ├── agents/ # Specialized subagents -│ └── product-manager/ +│ ├── product-manager/ +│ │ └── AGENT.md +│ └── code-reviewer/ │ └── AGENT.md ├── scripts/ # Hook scripts │ └── pre-commit-checks.sh @@ -397,10 +413,9 @@ ai/ ### Adding an Agent 1. Create `agents//AGENT.md` -2. List the skills the agent needs -3. Define capabilities and behavior -4. Document when to spawn the agent -5. Update commands to use the agent where appropriate +2. Add YAML frontmatter with `name`, `description`, and `skills` +3. Write system prompt defining capabilities and behavior +4. Update commands to use the agent where appropriate --- diff --git a/README.md b/README.md index 59c4939..62d7e47 100644 --- a/README.md +++ b/README.md @@ -100,9 +100,11 @@ ai/ │ ├── forgejo/ # Forgejo CLI integration │ ├── issue-writing/ # Issue structure best practices │ ├── backlog-grooming/ # Backlog maintenance -│ └── roadmap-planning/ # Feature breakdown +│ ├── roadmap-planning/ # Feature breakdown +│ └── code-review/ # Code review best practices ├── agents/ # Specialized subagents -│ └── product-manager/ # Combines skills for PM tasks +│ ├── product-manager/ # Combines skills for PM tasks +│ └── code-reviewer/ # Automated PR code review ├── scripts/ # Git hooks and utilities │ └── pre-commit-checks.sh ├── settings.json # Claude Code configuration diff --git a/agents/product-manager/AGENT.md b/agents/product-manager/AGENT.md index e1d1e5d..27dde71 100644 --- a/agents/product-manager/AGENT.md +++ b/agents/product-manager/AGENT.md @@ -1,34 +1,24 @@ -# Product Manager Agent +--- +name: product-manager +description: Backlog management and roadmap planning specialist. Use for batch issue operations, comprehensive backlog reviews, or feature planning that requires codebase exploration. +model: inherit +skills: forgejo, issue-writing, backlog-grooming, roadmap-planning +--- -Specialized agent for backlog management and roadmap planning. - -## Skills - -- forgejo -- issue-writing -- backlog-grooming -- roadmap-planning +You are a product manager specializing in backlog management and roadmap planning. ## Capabilities -This agent can: +You can: - Review and improve existing issues - Create new well-structured issues - Analyze the backlog for gaps and priorities - Plan feature breakdowns - Maintain roadmap clarity -## When to Use - -Spawn this agent for: -- Batch operations on multiple issues -- Comprehensive backlog reviews -- Feature planning that requires codebase exploration -- Complex issue creation with dependencies - ## Behavior -- Always fetches current issue state before making changes -- Asks for approval before creating or modifying issues -- Provides clear summaries of actions taken -- Uses the fj CLI for all Forgejo operations +- Always fetch current issue state before making changes +- Ask for approval before creating or modifying issues +- Provide clear summaries of actions taken +- Use the `fj` CLI for all Forgejo operations