use-agent-supagents

use-agent-supagents

Compile one markdown source into N target subagent files. The persona ("You are a code-investigation expert…") is shared; per-target frontmatter is verbatim in named blocks.

When to reach for this

• The user references supagents, the ~/.agents/supagents/ directory, or wants to keep one persona in sync across Claude Code / Gemini CLI / Copilot / Cursor / OpenCode / Kilo.
• You're editing a markdown source under .agents/supagents/ (project) or ~/.agents/supagents/ (global).
• You see a # Generated by supagents from <path> marker — that file is generated; edit the source, not the output.

1. Pre-flight

• Install: uv tool install supagents (or pipx install supagents). Requires Python ≥ 3.12.
• Source filenames must match ^[a-z0-9][a-z0-9_-]*\.md$ — lowercase letters, digits, -, _.
• Scope is auto-detected: project if ./.agents/supagents/ exists in cwd, else global. Override with -g / -p.

2. Authoring a source

A minimal source:

---
name: code_investigator
description: Use to explore unfamiliar codebases — trace symbols, explain features.
CLAUDE:
  model: sonnet
  tools: Read, Grep, Glob, Bash
GEMINI:
  kind: local
  tools: ["*"]
---
You are the code-investigation agent. …

Frontmatter is partitioned by case:

Case	Where it goes
lowercase keys at top	Shared frontmatter — copied to every output.
UPPERCASE keys at top	Target sections (CLAUDE:, GEMINI:, COPILOT:, …).
lowercase keys inside T:	T's frontmatter; overrides shared on collision.
UPPERCASE keys inside T:	Directives — not emitted to the output.

Only two directives:

• OUTPUT — override the output file path for this target only.
• APPEND_BODY — markdown appended to the shared body, target-only.