Skip to content

feat(skills): persona/JTBD taxonomy, curl-able hosting, catalog browser, b2c-operator plugin#508

Draft
clavery wants to merge 1 commit into
mainfrom
feature/skills-presentation-refactor
Draft

feat(skills): persona/JTBD taxonomy, curl-able hosting, catalog browser, b2c-operator plugin#508
clavery wants to merge 1 commit into
mainfrom
feature/skills-presentation-refactor

Conversation

@clavery

@clavery clavery commented Jun 17, 2026

Copy link
Copy Markdown
Collaborator

Refactor of how we present and deliver agent skills, adapting Sentry-for-AI's curl-first distribution while keeping our local-skill harness model. Plan of record: PLAN_SKILL_PRESENTATION.md.

What changed

Taxonomy (hybrid metadata)

  • Per-skill persona / category / tags now live in each SKILL.md frontmatter (source of truth, edited with content). The SDK parser ignores them, so this is non-breaking across all IDE targets.
  • Closed vocabulary in skills/taxonomy.schema.json (CI-enforced — frontmatter can't invent buckets).
  • Generated consumer manifest skills/taxonomy.generated.json (committed, DO-NOT-EDIT, freshness-checked in CI).
  • Two active personas: developer (41) + operator (16) = 57 governed skills. merchant is defined but active: false (deferred).

Curl-able hosting

  • The docs build now publishes the entire skills/** tree (SKILL.md + every references/*.md) plus a machine-readable skills-index.json and an agent-friendly skills.txt, with absolute URLs and a "use curl -sL, not WebFetch" fidelity note. Cold agents / CI can fetch guidance with no install.

Interactive catalog

  • New <skills-catalog /> Vue browser embedded on /guide/agent-skills: persona→category tree, tag cloud, search, and one-click copy curl per skill or for all matches. Build-time data loader (SSR-safe, no runtime fetch).

Doc page split

  • /guide/agent-skills is now a quick-start-first showcase (keeps its slug — the most-linked URL); exhaustive per-IDE install detail moved to a new /guide/install-skills page. Inbound anchors repointed.

b2c-operator persona plugin

  • A new plugin assembled by scripts/assemble-personas.mjs from the 16 operator-tagged skills (deploys, sandboxes, jobs, logs, debugging, edge/MRT, access admin) drawn across b2c-cli/b2c. Generated + committed (DO-NOT-EDIT), with a CI drift check. Each skill is still authored once in its home plugin.
  • Registered across skills/plugins.json (flagged generated so it's published but not double-counted), .claude-plugin/marketplace.json, the SDK SkillSet/SKILL_SOURCES/ReleaseInfo, version sync, and a CLI overlap warning.

Tooling & guards (new CI skills job)

  • scripts/validate-skills.mjs --check (frontmatter + reference-link resolution + manifest freshness), assemble-personas.mjs --check (drift), check-skills-hosting.mjs (curl URLs resolve), check-doc-anchors.mjs (page-split anchor guard).

Incidental fixes

  • 6 pre-existing off-by-one cross-plugin links in b2c-scapi-shopper/b2c-scapi-admin (../../b2c-cli../../../b2c-cli).
  • A stale #reading-log-files anchor in docs/cli/logs.md.

Follow-ups (deferred by design)

  • merchant persona activation + a b2c-merchant bundle (only 3 merchant skills today).
  • A b2c-developer bundle (low value — near-union of existing plugins).

…er, b2c-operator plugin

Refactor agent-skill presentation and delivery, adapting Sentry-for-AI's
curl-first distribution while keeping our local-skill harness model.

- Taxonomy (hybrid): per-skill persona/category/tags in SKILL.md frontmatter
  (source of truth), closed vocabulary in skills/taxonomy.schema.json
  (CI-enforced), generated skills/taxonomy.generated.json consumer manifest.
  Two active personas — developer (41) + operator (16) = 57 governed skills.
- Curl hosting: docs build publishes the whole skills/** tree + skills-index.json
  + skills.txt with absolute URLs and a "curl, don't WebFetch" fidelity note.
- Interactive catalog: <skills-catalog /> Vue browser (persona tree + tag cloud
  + per-card/batch copy curl) embedded on /guide/agent-skills.
- Page split: install detail moved to /guide/install-skills; showcase slug kept.
- b2c-operator plugin: a generated, committed bundle of the 16 operator skills,
  registered across plugins.json/marketplace/SDK SkillSet/CLI.
- Validators: scripts/validate-skills.mjs (--check), assemble-personas.mjs
  (--check drift), check-skills-hosting.mjs, check-doc-anchors.mjs; new CI job.
- Fix 6 pre-existing off-by-one cross-plugin links in the SCAPI skills and a
  stale anchor in cli/logs.md.

Plan of record: PLAN_SKILL_PRESENTATION.md
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.

1 participant