Skip to content

skills: add per-skill agents: and related: frontmatter contract#7

Merged
t4sh merged 1 commit into
mainfrom
skills/per-skill-agents-related
May 2, 2026
Merged

skills: add per-skill agents: and related: frontmatter contract#7
t4sh merged 1 commit into
mainfrom
skills/per-skill-agents-related

Conversation

@t4sh
Copy link
Copy Markdown
Contributor

@t4sh t4sh commented May 2, 2026

Closes #6

Adds two optional top-level frontmatter fields to SKILL.md (sibling to `name:` / `description:` / `version:`), and populates them on the 31 skills erphq/lab-sites currently composes.

What lands

Spec (in README.md)

New "Frontmatter — `agents:` and `related:` (optional, downstream-facing)" subsection under "For agents" defining:

```yaml

name: accounts-receivable
description: …
version: 1.0.0
agents: # ← optional

  • collections
  • reconciliation
  • approvals
    related: # ← optional
  • accounts-payable
  • general-ledger
  • period-close
    metadata:

```

  • `agents:` — agent capability slugs that work on this skill (reusable across apps). Renderers display as cards/chips.
  • `related:` — other skill slugs this skill commonly works with. Slugs MUST resolve to real `SKILL.md` files in this repo. Renderers use for "works with" cross-link grids.
  • Both optional — skills without populated fields render the standard page sans those sections.
  • Top-level (not nested under `metadata:`) because they describe skill relationships, not file metadata.

Data (31 SKILL.md files updated)

Populated agents+related on every SKILL.md at the `03-org-1k-plus` tier across the 5 departments lab-sites composes (8 finance + 8 supply-chain + 2 HR + 8 sales-crm + 5 IT-plumbing under `information-technology/`).

Source: lab-sites' `apps/web-lab/src/_data/erpFeatures.json` + `crmFeatures.json`. For skills composed by multiple apps (e.g. `security-roles` shows up in both ERP and CRM), values are the union across composing apps. Sorted for deterministic diffs.

Other ~50 SKILL.md files

Untouched. Optional means optional — maintainers backfill at other tiers / depts as time permits. No drift introduced; consumers gracefully render missing fields.

Why this is the right shape

  • Canonical — single source of truth for skill relationships, replacing per-consumer hand-curation
  • Drift-validatable — existing SKILL.md drift checks now cover this data automatically
  • Forward-compatible — both fields are optional; new SKILL.md files don't need to populate them on day one
  • Cross-app — `agents:` from a skill composed by 5 different apps still resolves correctly per app, since slugs are globally addressable

Downstream impact

Lab-sites can drop the `agents` / `related` columns from its `erpFeatures.json` / `crmFeatures.json` after this lands and read them from `skillSpecs.mjs` (which already loads SKILL.md frontmatter). Cleanup PR will follow on the lab-sites side.

Test plan

  • All 31 modified SKILL.md files parse as valid YAML frontmatter
  • Spot-check 5 random skills — `agents:` and `related:` insert in the right position (between `version:` and `metadata:`), with deterministic alphabetical ordering
  • Lab-sites' `pnpm verify` (which runs `check-skills-drift.mjs`) still passes when the corresponding mirrors are pulled
  • All `related:` slugs resolve to real SKILL.md files in this repo (no orphan refs introduced)

Spec aware

Surfaced during work on erphq/lab-sites#118, which built the appskills+skills→lab-sites pipeline and noted this as the highest-value upstream contract gap.

Adds two top-level optional frontmatter fields (sibling to name:,
description:, version:) for skills metadata that downstream
consumers like erphq/lab-sites need to render cross-references on
skill pages:

- agents: list of agent capability slugs that work on this skill
- related: list of other skill slugs this skill commonly works with

Today these live as hand-curated JSON in lab-sites
(apps/web-lab/src/_data/erpFeatures.json + crmFeatures.json) and
diverge per consumer. Moving them into SKILL.md frontmatter makes
them canonical, validatable (drift checks already cover SKILL.md),
and shareable across consumers.

Both fields are optional — skills without them render the standard
page sans cross-references. Live at top level (not under metadata:)
because they're about skill relationships, not file metadata.

This commit:

- Documents the contract in README.md (new "Frontmatter — agents:
  and related: (optional, downstream-facing)" subsection under
  "For agents")
- Populates agents+related on the 31 SKILL.md files at the
  03-org-1k-plus tier that erphq/lab-sites currently composes
  (sourced from lab-sites' existing JSON, unioning across apps that
  compose each skill — e.g. security-roles is composed by both ERP
  and CRM, so its agents/related are the union of both apps' values)

Other ~50 SKILL.md files at other tiers / depts not lab-sites uses
are left unmodified. Optional means optional — backfill as time
permits, no rush. When lab-sites' agents/related stay in sync with
upstream, lab-sites can drop the fields from its local JSON and
read them from skillSpecs.mjs.

Closes #6
@t4sh t4sh merged commit 069cf58 into main May 2, 2026
3 checks passed
@t4sh t4sh deleted the skills/per-skill-agents-related branch May 2, 2026 05:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add per-skill agents: and related: frontmatter contract

1 participant