RFC: Make agents self-describing — tags + when_to_use as the single source of truth

[msitarzewski]

RFC: Make agents self-describing — tags + when_to_use as the single source of truth

Status: Draft for discussion (per CONTRIBUTING's "Discussion-first for schema/tooling" rule)
Supersedes / unifies: several dormant proposals — see Prior art below.

TL;DR

Add two frontmatter fields to every agent — tags (capability keywords) and when_to_use (a one-line routing trigger) — and make the README roster, search, and tool integrations generate from them instead of being hand-maintained. This kills doc drift, improves agent routing across Claude Code / Codex / Hermes, and powers the search + MCP ideas the community already proposed. New agents must include both fields (CI-enforced on submission, with a minimal quality bar); the existing 203 are backfilled on a non-blocking track from data we already have — then the fields are required for everyone.

Why now

We just hit 203 agents / 14 divisions. Two recurring pains keep surfacing:

1. Doc drift. The README roster and counts are hand-maintained. They went stale (144→147→203) and 19 agents were missing from the tables until a manual sweep. This will keep happening.
2. No capability layer. Agents are filed by division, but real tasks span divisions, and tools that route to agents (Claude subagent delegation, Codex, Hermes, MCP servers) have nothing structured to match on — only a prose description that's written as identity, not when to use.

The root cause is the same: the data that describes an agent's capability and when to reach for it lives in the README (or nowhere), not with the agent. This RFC moves it to the source.

Prior art (this RFC consolidates, with thanks)

This isn't new — it's scattered across dormant threads. Crediting and unifying them:

Thread	Author	Covers
Discussion #227 — Agent Tags for cross-division discovery	@kienbui1995	the tags field (this RFC adopts it)
Discussion #225 — Agent Search CLI	@kienbui1995	a consumer: search.sh over tags/description
Discussion #354 + PR #352 — MCP server: query/search/compose	@mchawda	a consumer: runtime agent registry + routing
Discussion #374 — query-interpretation feedback loop	@lastmeta	a consumer: better vague-query → agent matching
Discussion #462 + PR #361 — auto-generated README index	@cyberpinkman	the generation half (this RFC extends it)
PR #117 — npm SDK AgentFrontmatter type	@el-j	formalizing the schema in code

The only genuinely new piece here is when_to_use (splitting the routing trigger out of description). Everything else is gluing the above into one coherent model.

Proposed schema

Two new required-going-forward fields (see enforcement below). Crisp, non-overlapping semantics so they don't drift into three blurbs:

---
name: Backend Architect
description: Senior backend architect specializing in scalable system design, database architecture, and cloud infrastructure.   # WHAT it is (identity) — unchanged
when_to_use: Reach for this when designing server-side systems, APIs, microservices, or cloud infrastructure.                    # WHEN to invoke it (routing trigger) — NEW
tags: [api-design, databases, scalability, microservices, cloud]                                                                # capability keywords — NEW
color: blue
emoji: 🏗️
vibe: ...
---

Field	Role	Consumed by
description	identity — what it is	README, all converters (unchanged)
when_to_use (new, required)	trigger — when to invoke	Claude subagent delegation, Codex description, Hermes "When to Use", MCP routing
tags (new, required)	capability keywords	search CLI (#225), MCP search (#352), README "Specialty" column, cross-division discovery
vibe	personality hook	OpenClaw IDENTITY, README flavor (unchanged)

Enforcement (the key decision)

The fields are only worth adding if coverage is complete — a generated roster / search / router that's missing when_to_use for 40% of agents is broken. "Optional forever" guarantees exactly that half-populated outcome. So the fields are required going forward — but enforced in a way that never turns CI red on the 203 legacy agents:

• New agents → required, enforced on submission. The CI lint already diffs changed files and can detect an added agent file (new file mode). A new agent without when_to_use + tags fails CI with a clear message. The author writes them — which is higher-quality than us inferring from their description anyway. This is enforcement on the person who knows the agent best, from day one.
• Existing 203 → backfilled on a non-blocking track. The required-field rule applies to added files only, so editing a not-yet-backfilled legacy agent never fails. As each is backfilled it's done.
• Once coverage hits 100% → required globally. The new-vs-legacy distinction is dropped and the linter requires the fields on every file. The "optional/warn" state is purely transitional, not the destination.

Quality bar (presence ≠ quality)

Requiring a field tends to produce lazy values (tags: [ai, general]). So enforcement is paired with a minimal substance check in the linter, in the spirit of the originality check and the persona-section gate:

• when_to_use: a real sentence (≥ ~6 words); must not just restate the agent name.
• tags: a list of ≥ 3, lowercase-kebab-case.

Non-negotiables (kept)

• Still one markdown file. Two more meaningful fields — a one-line when_to_use and a short tags list — is a modest, value-adding ask (they make the agent route better), not build-system friction. A clear template + actionable CI errors keep the first-time-contributor path smooth.
• No committed generated output. The generated README block lives between markers and is verified in CI (--check), same pattern as feat: generate README agent index from source files #361; nothing under integrations/ changes.
• No new mandatory tooling for contributors. No npm, no build step required to add an agent.

Downstream payoff (what generating from frontmatter unlocks)

1. README roster + counts become generated (extends feat: generate README agent index from source files #361/Proposal: Auto-generated Agent Index for README.md #462). One source of truth → drift is impossible, not just discouraged. CI rejects a stale roster.
2. Search (Feature: Agent Search CLI (./scripts/search.sh) #225) filters by tags across divisions.
3. MCP registry (Add MCP server integration for dynamic agent discovery #352/MCP Server Integration query, search, and compose agent teams dynamically #354) routes/searches on tags + when_to_use instead of grepping prose.
4. Better auto-routing everywhere — when_to_use maps directly into the fields target tools already use for delegation:
   • Claude Code subagent description (delegation trigger)
   • Codex description ("when Codex should use this agent")
   • Hermes SKILL.md "When to Use" section

Migration (phased, low-risk)

• Phase 0 — this RFC: agree the schema + semantics.
• Phase 1: add the fields to the template + CONTRIBUTING; ship the linter rule that requires them on newly-added agent files + the quality bar (legacy files unaffected); (optionally) reflect in Agency GithubAction and NPM #117's AgentFrontmatter type.
• Phase 2 — backfill the 203: seed tags from the README's hand-curated Specialty column and when_to_use from the When to Use column — this data already exists and was curated by hand, so the migration is mostly mechanical + a review pass. No curation is wasted; it's promoted to source-of-truth.
• Phase 3: flip the linter to require the fields globally (now that coverage is 100%); extend the feat: generate README agent index from source files #361 generator to emit the rich README roster + counts from frontmatter, CI --check guard; retire the hand-maintained tables.
• Phase 4: wire consumers — search CLI (Feature: Agent Search CLI (./scripts/search.sh) #225), MCP (Add MCP server integration for dynamic agent discovery #352) routing, and converter when_to_use mapping (Codex/Hermes/Claude).

Each phase is independently shippable and reversible.

Open questions

1. when_to_use vs. just rewriting description? Alternative: drop the new field, redefine description to be trigger-oriented, accept a slightly weaker identity line. Simpler (no schema change) but loses the clean identity/trigger split. (RFC's lean: keep them separate — the split is what makes routing good.)
2. tags: freeform or controlled vocabulary? Lean: start freeform, curate a canonical set later once usage shows the natural taxonomy.
3. Generated roster — replace or coexist with the hand tables? Lean: replace (one source of truth; avoids the two-roster problem PR feat: generate README agent index from source files #361 would otherwise create).
4. Naming bikeshed: when_to_use vs use_when vs triggers vs activation.

What this RFC is NOT proposing

• A breaking change to existing agents — the 203 are grandfathered and backfilled, never blocked; enforcement applies to new submissions first.
• Committing generated files, a build system, or mandatory contributor tooling.
• Replacing divisions — tags is additive discovery, divisions stay.

Asks for the thread

1. Thumbs-up/down on the two fields + semantics.
2. Resolve the open questions (esp. Welcome to agency-agents Discussions! #1 and Add Frontend UI Tester - Testing #3).
3. If there's appetite, I'll take Phase 1 + a one-division Phase 2 backfill as a demo PR so we can see the generated rich roster + the improved Codex/Hermes routing before committing to all 203.

[chandrudp29]

This is exactly what I built in skillhub (github.com/chandrudp29/skillhub).

I went with triggers for the routing field (your bikeshed option 3):

---

name: debug-agent
description: Systematic root cause analysis for bugs and errors
when_to_use: Use when user reports something broken or an error they can't explain
tags: [debugging, error-analysis, root-cause]
triggers: ['debug', 'bug', 'error', 'broken', 'not working', 'crash']

On install, skillhub writes .claude/skills.json — a lightweight index
agents can scan without loading every file:

{
"skills": {
"debug-agent": {
"path": "commands/debug-agent.md",
"triggers": ["debug", "bug", "error", "broken"]
}
}
}

I also posted a broader proposal in Discussions about using skillhub
as the package manager layer for agency-agents. Happy to align on the
schema — the triggers vs when_to_use naming is a one-line change.