Labels and capabilities

This page is the canonical reference for the label taxonomy used on issues and pull requests in this framework repository (apache/magpie). It also defines the capability model that classifies what each skill or tool in the framework actually does, independent of which subject area it sits under.

Every issue and pull request opened against this repository should carry at least one family:* label and at least one capability:* label. New tools and new skills must declare their capability up front (see The rule).

Scope caveat. This taxonomy applies to this framework repository. Skills that create issues or PRs on an adopter’s tracker (e.g. security-issue-import, security-issue-fix, issue-fix-workflow) use the adopter’s own label scheme — adopters are free to mirror this taxonomy in their own repo but are not required to.

Label dimensions

The repository’s labels fall into four orthogonal dimensions. An issue or PR typically carries one label from each dimension that applies.

1. family:* — subject

What part of the framework does this touch?

Ten of these labels mirror the canonical skill-family vocabulary — the closed set every skill declares in its family: frontmatter key, enforced as ALLOWED_FAMILIES by skill-and-tool-validator and summarised in README.md → Skill families. Two of them (setup, utilities) are the always-on families wired on every install; the other eight are opt-in (see skills/setup/SKILL.md Golden rule 8).

Three further family:* labels cover parts of the repository that are not a skill family. They exist only as issue / PR labels and never appear in a family: frontmatter key — the validator would reject them:

A change that spans both dimensions carries both labels — a new mentoring skill and its guide is family:mentoring + family:docs. The two tables above are the reference for the repository’s label set: if the label you need is not on the repository yet, a committer creates it from here rather than reaching for an approximate existing one.

2. capability — two axes (skills vs tools)

Per RFC-AI-0005, “capability” is two orthogonal vocabularies, one per entity. A skill carries one or more skill capabilities (capability:*); a tool carries one or more tool capabilities (contract:* or substrate:*). List all that apply; do not pick a single “primary”.

Axis 1 — skill capability (capability:*) — the workflow-lifecycle phase a skill performs:

Axis 2 — tool capability (contract:* / substrate:*) — the interface a tool/adapter provides. contract:<name> implements a capability contract under tools/<contract>/; substrate:<name> is framework substrate:

Coverage qualifiers

Some tool READMEs may declare a Coverage: qualifier next to a capability when the tool intentionally implements only part of a contract.

partial-read-only means the tool implements a read-only subset of named contract operations, but does not satisfy the complete contract and must not be advertised as a complete/selectable backend. partial means the same without the read-only restriction: some named operations, including writes, are implemented, but not the complete contract.

The README form is a line **Coverage:** partial (or partial-read-only). tools/vendor-neutrality-score reads it and never counts a partial tool as a backend vendor, so a partial foundation cannot turn a contract green in docs/vendor-neutrality.md.

Both capability axes are orthogonal to family:*. A single query can answer “how is our triage stack doing across PR + issue + security?” by filtering on capability:triage alone, without enumerating per-area queries.

Agent-harness support (substrate tools only). A substrate tool that integrates with the agent harness (a hook, a settings file, a launcher) declares a **Harness:** field naming the harness(es) it supports, or agnostic when it depends on none. This is the agent-harness axis of LLM-integration neutrality and is scored by tools/vendor-neutrality-score — distinct from a tool’s **Runtime:** field, which is its execution environment (e.g. “Python stdlib”). The recognised harnesses are: Claude Code, Codex, Cursor, Gemini CLI, Copilot, OpenCode, Kiro. A tool is harness-neutral when it is agnostic or supports two or more harnesses.

3. kind:* — change type (pre-existing)

4. mode:* — handling mode (pre-existing)

Standalone labels

marketing (branding artefacts), dependencies (dependency-update PRs), python:uv (Python uv-managed code), plus the default GitHub labels (bug, enhancement, documentation, good first issue, etc.).

Capability to skill map

Capabilities for every skill currently in .claude/skills/. Skills with two values (separated by +) carry both labels.

Capability to tool map

Tools under tools/. A tool’s capability is the interface it provides; a tool may carry more than one value (separated by +) when it provides more than one interface — either several contracts (e.g. tools/gmail provides mail-source, mail-archive, and mail-create) or a contract-free mix of substrates (e.g. tools/spec-inventory is substrate:framework-dev + substrate:analytics).

A tool’s capability is the interface it provides, not which skills happen to consume it (RFC-AI-0005). tools/github provides the contract:tracker interface; tools/cve-tool-vulnogram provides contract:cve-authority; tools/privacy-llm is substrate:privacy. Use a contract:<name> value when the tool implements a capability contract under tools/<contract>/, and a substrate:<name> value for framework substrate. A tool may carry more than one value whenever it genuinely exposes several interfaces — the multi-value rows in the table above are the authoritative list, and they are a normal case rather than an exception (forge bridges such as tools/github, tools/fossil, and tools/sourcehut; the mail backends tools/gmail, tools/maildir, and tools/ponymail; and the framework-dev tools that double as analytics).

MCP servers, classified by capability

Several tools wrap a Model Context Protocol (MCP) server as their concrete backend. An MCP server is not a separate axis — it is classified by the capability its wrapping tool provides; the MCP is just the transport, interchangeable with a CLI or REST backend behind the same contract. A skill never names an MCP server — it targets the capability, and the tool routes to whichever backend the adopter wired in. The framework consumes five:

Each wrapping tool declares this relationship in its own README with an **MCP:** <server> (mcp__<prefix>__*) marker (see tools/AGENTS.md) — that per-tool marker is the source of truth; this table mirrors it for a one-glance overview.

Non-MCP backends fulfil the same contracts: JIRA is reached over REST and gh is the CLI fallback, both contract:tracker. See docs/prerequisites.md for connection setup.

MCP servers are installed for the user, not the project. They are registered at user scope (claude mcp add … -s user), so a single registration serves every repository on the machine. Consequently they are usable by any agent session — not only Magpie-adopting projects or Magpie-related work. Magpie surfaces the registration command and verifies it during setup, but the server itself is a plain, project-agnostic MCP: once registered it is available to any agentic session the same way a globally-installed CLI would be. Nothing about using one ties a session to Magpie.

The rule

When you create any of the following on this repository, declare the capability:

A GitHub issue

Apply at least one family:* AND one capability label — a skill capability (capability:*) for skill work, a tool capability (contract:* / substrate:*) for tool work. If the issue genuinely spans capabilities, apply all that apply.

A pull request

Same: family:* AND the matching capability. Match the capability the change is implementing, not the file paths it happens to touch. A PR that adjusts the validator config to support a new triage rule is capability:triage (the change’s purpose), not substrate:framework-dev (the file it edited).

The tool-capability labels are pre-applied within an hour of a PR being opened: the scheduled .github/workflows/labeler.yml labels each new PR once, with the **Capability:** of every tool directory it touches, from .github/labeler.yml, which tools/dev/generate-labeler-config.py generates from the tool READMEs. That is a starting point, not the answer: remove a label the change does not implement, and add the skill capability yourself. Bot PRs and sweeps that would gain more than eight labels are left unlabelled.

A new tool under tools/

Declare the tool’s capability in the first paragraph of its README using the line:

**Capability:** contract:NAME

…or substrate:NAME for framework substrate. If the tool serves more than one, list them (contract:a + substrate:b). Pick the contract:<name> that matches the capability contract the tool implements, or the substrate:<name> kind that fits.

A new skill under .claude/skills/

Declare the capability in the skill’s frontmatter:

---
name: my-new-skill
description: |
  ...
capability: capability:NAME
---

The write-skill skill prompts for this on every new-skill scaffold.

A new doc under docs/

Capability-specific docs (e.g. a guide for a single skill family) should link to this page and name the capability in their first paragraph. Cross-cutting docs (MISSION.md, top-level READMEs) need no capability marker.

Why this exists

The original family:* labels split issues by subject — useful for “what part of the codebase is this?” but unable to answer “what kind of thing is this?”. The capability:* dimension fills that gap and is orthogonal: a triage-rule change in PR management (family:pr-management + capability:triage) and a triage-rule change in security (family:security + capability:triage) become trivially findable as a cohort even though they live in different families.

Capability is also a forcing function for skill design: if a new skill doesn’t fit any of the ten skill-capability buckets cleanly, that’s a signal worth inspecting before the skill ships.