Skip to content

Skill Tags

Jump to bottom
Scott Shwarts edited this page Jul 18, 2026 · 1 revision

Tagging skills (# Tags:)

Shipped in 0.33.0.

The problem

Once you have more than a handful of skills, a flat list gets hard to work with — for you and for an agent picking which skill to run. You want a second axis to group them: email, ops, morning-brief, deterministic, whatever fits how you think about your corpus.

# Tags: gives you that axis without touching what a skill does.

How to use it

Add a # Tags: line to a skill's frontmatter — comma-separated:

# Skill: morning-brief
# Tags: morning-brief, ops, email
# Status: Approved

default: run
run:
    ...

Tags are normalized for you: lowercased, trimmed, de-duplicated. So # Tags: Email, email , OPS becomes email, ops. Order is preserved; duplicates are dropped.

That's the whole feature on the authoring side. There's no separate registry to maintain — the tags live in the skill body, right next to everything else about it.

What you get

  • Dashboard grouping. The skills list is faceted by tag — filter chips (All / each tag / untagged) plus a tag pill on each row. Scanning a big corpus becomes "show me the ops skills."
  • Agent comprehension. Tags ride in the skill's contract (skill_list returns tags on every entry — an empty array when untagged; skill_preflight carries them too). An agent choosing among many skills can chunk the menu into families instead of reading every description — which measurably helps selection on large, flat lists.

What tags do not do — read this

Tags are pure classification. They have zero effect on execution, dispatch, approval, or which skill the runtime selects. A tag is never an authorization input or a routing key. This is deliberate — it's what makes them safe to add freely.

Two consequences worth knowing:

  • Approval-neutral. The # Tags: line is excluded from the approval signing hash (the same carve-out # Status: has). So editing, adding, or removing a tag does not invalidate an operator's signature and does not drop the skill back to Draft. You can re-tag an approved skill freely — a tag can't change what the skill does, so re-approval would be busywork. (Contrast # Deadline:, which is in the hash, because it changes the skill's safety envelope.)
  • Runtime-derived. Like # Description:, tags are a projection of the skill body — the runtime derives them from the frontmatter. A custom SkillStore that doesn't persist a tags field still gets correct tags, because they come from the source, not the store.

Gotchas

  • Filtering skill_list by tag server-side isn't wired yet. The tags field is present in the contract and the dashboard facets on it, but skill_list({ filter: { tags } }) is a later addition — for now, filter client-side / in the dashboard.
  • Tags are classification, not capability. If you're reaching for a tag to gate what a skill may do (who can run it, what it can touch), that's the wrong tool — use approval + the shell/fs/secret allowlists. Tags are for humans and agents to find skills, nothing more.

Clone this wiki locally