skills: add per-skill agents: and related: frontmatter contract#7
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
related: # ← optional
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
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
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.