feat(skills): persona/JTBD taxonomy, curl-able hosting, catalog browser, b2c-operator plugin#508
Open
clavery wants to merge 3 commits into
Open
feat(skills): persona/JTBD taxonomy, curl-able hosting, catalog browser, b2c-operator plugin#508clavery wants to merge 3 commits into
clavery wants to merge 3 commits into
Conversation
…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
…-server curl Address review feedback on the skills presentation refactor: - Pivot b2c-operator from a generated re-bundle to a hand-authored plugin of unique operator runbooks (b2c-production-release, b2c-incident-triage) that compose the b2c-cli commands. Removes the assembler + personas.json + the "install instead of" caveat; the plugin now installs alongside b2c-cli. Skills are grounded in the official B2C ops docs (code deployment, log-file taxonomy, incident troubleshooting). - Add multi-persona overlap: skills keep one primary persona plus optional alsoFor[]; the catalog filter and chip counts match either. Cross-over CLI skills (code/logs/debug/sandbox, config/slas) now surface under both roles. - Curl framing aligned with Sentry: instruction-style "Use curl to download, read, and follow: <url>" + a why-curl note; skills.txt gains an ask-first header. Serve the skill tree/index during `vitepress dev` so curl works locally (buildEnd only runs on build). - Simplify the catalog UI: discovery-first cards, search + persona chips (no tag sidebar), 2-up readable grid, full un-truncated names, per-card "Copy for agent" (no batch copy). - Page titles: "Agent Skills + MCP" / "Installing Agent Plugins"; home "Install Agent Skills + MCP".
…tation-refactor # Conflicts: # docs/.vitepress/config.mts # docs/.vitepress/theme/index.ts # docs/guide/agent-skills.md # docs/index.md # skills/b2c-cli/skills/b2c-config/SKILL.md # skills/b2c-cli/skills/b2c-docs/SKILL.md # skills/b2c/skills/b2c-custom-job-steps/SKILL.md # skills/b2c/skills/b2c-scapi-admin/SKILL.md
clavery
marked this pull request as ready for review
July 14, 2026 13:39
clavery
requested review from
patricksullivansf,
wei-liu-sf and
yhsieh1
as code owners
July 14, 2026 13:39
Contributor
📘 Docs previewYour documentation changes are published at: https://d3uhw92m2zac57.cloudfront.net/pr-508/ Commit This preview updates on every push and is removed when the PR is closed. |
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
1 participant
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.
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)
persona/category/tagsnow live in eachSKILL.mdfrontmatter (source of truth, edited with content). The SDK parser ignores them, so this is non-breaking across all IDE targets.skills/taxonomy.schema.json(CI-enforced — frontmatter can't invent buckets).skills/taxonomy.generated.json(committed, DO-NOT-EDIT, freshness-checked in CI).merchantis defined butactive: false(deferred).Curl-able hosting
skills/**tree (SKILL.md + everyreferences/*.md) plus a machine-readableskills-index.jsonand an agent-friendlyskills.txt, with absolute URLs and a "usecurl -sL, not WebFetch" fidelity note. Cold agents / CI can fetch guidance with no install.Interactive catalog
<skills-catalog />Vue browser embedded on/guide/agent-skills: persona→category tree, tag cloud, search, and one-click copycurlper skill or for all matches. Build-time data loader (SSR-safe, no runtime fetch).Doc page split
/guide/agent-skillsis now a quick-start-first showcase (keeps its slug — the most-linked URL); exhaustive per-IDE install detail moved to a new/guide/install-skillspage. Inbound anchors repointed.b2c-operatorpersona pluginscripts/assemble-personas.mjsfrom the 16 operator-tagged skills (deploys, sandboxes, jobs, logs, debugging, edge/MRT, access admin) drawn acrossb2c-cli/b2c. Generated + committed (DO-NOT-EDIT), with a CI drift check. Each skill is still authored once in its home plugin.skills/plugins.json(flaggedgeneratedso it's published but not double-counted),.claude-plugin/marketplace.json, the SDKSkillSet/SKILL_SOURCES/ReleaseInfo, version sync, and a CLI overlap warning.Tooling & guards (new CI
skillsjob)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
b2c-scapi-shopper/b2c-scapi-admin(../../b2c-cli→../../../b2c-cli).#reading-log-filesanchor indocs/cli/logs.md.Follow-ups (deferred by design)
merchantpersona activation + ab2c-merchantbundle (only 3 merchant skills today).b2c-developerbundle (low value — near-union of existing plugins).