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.

A target section's presence triggers an emit. Drop the COPILOT: block to stop generating Copilot files. There is no field-level conversion — what you write is what gets written.

Bundled targets (override paths in ~/.config/supagents/config.yaml):

Target	Global output	Project output	Suffix
CLAUDE	~/.claude/agents/	.claude/agents/	.md
GEMINI	~/.gemini/agents/	.gemini/agents/	.md
COPILOT	~/.copilot/agents/	.github/agents/	.agent.md
CURSOR	~/.cursor/agents/	.cursor/agents/	.md
OPENCODE	~/.config/opencode/agents/	.opencode/agents/	.md
KILO	~/.config/kilo/agents/	.kilo/agents/	.md

3. CLI

supagents init NAME [-g | -p] [--force]
supagents build    [-g | -p] [--dry-run | --check] [--target T]... [--config PATH] [-v]
supagents clean    [-g | -p] [--dry-run]           [--target T]... [--config PATH]
supagents list     [-g | -p]                       [--target T]... [--config PATH]

• build is idempotent — unchanged outputs aren't rewritten (mtimes preserved).
• --check exits 1 if any output would change. Useful as a CI guard against stale generated files. Mutually exclusive with --dry-run.
• --target is repeatable, case-insensitive; unknown targets are rejected.
• clean deletes only files carrying the supagents generation marker — hand-written siblings are preserved.
• Exit codes: 0 clean, 1 per-target errors or --check drift, 2 fatal parse errors.

4. Common workflows

Add a new agent (project scope):

supagents init code_investigator --project          # writes .agents/supagents/code_investigator.md with all six target blocks
$EDITOR .agents/supagents/code_investigator.md      # tweak frontmatter, write the persona body
supagents build --project                           # emit per-target files

Drop a target without losing the source: delete the XXX: block from the source frontmatter and run supagents clean to remove the orphaned outputs.

CI guard: add supagents build --check to CI — fails if checked-in generated files are stale relative to their source.

Pre-commit: the bundled hook id is supagents-build (see .pre-commit-hooks.yaml). It watches .agents/supagents/ and rewrites generated outputs in place.

5. Pitfalls

• Edit the source, not the output. Outputs lead with # Generated by supagents from <rel-path>. Do not edit; edit the source instead. Edits to a marker-bearing file are overwritten on the next build. Hand-written siblings without the marker are preserved by clean.
• Filename rejected. Code_Investigator.md, code_investigator.MD, or code investigator.md all fail validation. Lowercase letters, digits, -, _ only.
• Frontmatter case matters. Lowercase outside a target section is shared, not per-target. UPPERCASE inside a target is a directive, not an emitted key.

6. References

• README.md — full feature tour, pre-commit integration, configuration.
• src/supagents/config.py — target defaults, scope helpers, config schema.
• src/supagents/core.py — parsing, planning, idempotent writes (SOURCE_FILENAME_RE, marker constants).
• tests/fixtures/code_investigator.md — minimal source covering CLAUDE/GEMINI/COPILOT blocks plus an APPEND_BODY directive.