feat(skills): add the kb-docs-add agent skill for onboarding docs - #90
Open
oto-macenauer-absa wants to merge 1 commit into
Open
feat(skills): add the kb-docs-add agent skill for onboarding docs#90oto-macenauer-absa wants to merge 1 commit into
oto-macenauer-absa wants to merge 1 commit into
Conversation
An agent asked to "get our docs into the knowledge base" had to find the contract, read it in the right order and hand-translate it — and tended to over-build: a pack script, a manifest for a single-page repo, a workflow copied from a pre-v1 fork. The repo owns the source of truth, so it now also owns the agent-facing path through it. skills/kb-docs-add/ follows the Agent Skills spec, so the same directory loads in Claude Code, GitHub Copilot and via `npx skills add`. It classifies the repo (single-page / packaged / iframe), writes only the files the contract requires, and maps every message the actions emit to its fix. It ships no scripts: the actions keep owning validation, packing and upload. Its examples are the contract's own code blocks, and tests/skill.spec.js fails if they drift or the frontmatter stops being portable. Eval fixtures (three repos + evals.json) live under tests/fixtures/ so the installed skill stays small. Skill-driven runs on them and on clean copies of both example repos reproduced the committed workflows. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PYtmxSeSXFg4wEXRcKCmAi
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.
What
Adds the
kb-docs-addagent skill: a guided path through the onboarding contract for Claude Code, GitHub Copilot and any otherSKILL.mdreader, installable withnpx skills add AbsaOSS/knowledge-base --skill kb-docs-add. The skill classifies a docs repo (single-page / packaged / iframe), writes only the files the contract requires, and maps every message the publishing actions emit to its fix. It is guidance only: the actions keep owning validation, packing and upload, and the skill's examples are the contract's own code blocks so they cannot drift.Changes
skills/kb-docs-add/SKILL.md— classify → write the minimum → verify → troubleshoot; portable frontmatter only (name,description,license,metadata)skills/kb-docs-add/references/{single-page,packaged,troubleshooting}.md— per-path detail, loaded on demand; troubleshooting maps every action / knowledge-base build message to cause and fixskills/kb-docs-add/examples/— the single-page workflow, packaged workflow andkb-docs.json, extracted verbatim fromcontract/SINGLE_PAGE.mdandcontract/HEADLESS_RULES.mdskills/README.md— install table per agent and the authoring rulestests/skill.spec.js— frontmatter satisfies the Agent Skills spec, no executable files shipped, every referenced file exists, examples byte-identical to the contract, brand token values matchSTYLE_GUIDE.md, docs carry the install commandtests/fixtures/kb-docs-add/— three fixture repos (markdown-only, mkdocs site, hosted elsewhere) andevals.jsonwith prompts and assertionsREADME.md,contract/SINGLE_PAGE.md,contract/HEADLESS_RULES.md,CLAUDE.md— cross-reference the skill; the contract stays the normative textVerification
npm test— green (151 passed, including the 15 new static checks)npx skills add <local checkout> --skill kb-docs-add -a claude-code -a github-copilot -y— skill discovered and installed into.agents/skills/with a.claude/skills/symlinkknowledge-base-example-single-pageandknowledge-base-docs-example(publish workflow removed): 36/37 assertions. Both real repos reproduced their committed workflow shape; the single-page fixture produced exactly one file; the hosted-elsewhere fixture produced none. The one miss is a grader false positive on a pre-existingdist.tar.gzmention in the docs-example's own prose.Closes #89
🤖 Generated with Claude Code
https://claude.ai/code/session_01PYtmxSeSXFg4wEXRcKCmAi