Use agent supagents

Skill fmind/agent-supagents/skills/use-agent-supagents

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.From its SKILL.md

Install

npx -y skills add fmind/agent-supagents --skill use-agent-supagents

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

5.9 KB, as published. Nobody here has run it

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.