| name | use-agent-supagents |
| description | Use when authoring or building supagents sources under .agents/supagents/ — markdown that compiles to subagent files for Claude Code, Gemini CLI, GitHub Copilot, Cursor, OpenCode, and Kilo Code. |
| metadata | {"author":"fmind","url":"https://github.com/fmind/agent-supagents/tree/main/skills/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
$EDITOR .agents/supagents/code_investigator.md
supagents build --project
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.
