Agent skill: guide onboarding of knowledge-base-compatible docs (Claude Code, Copilot, skills.sh)

[oto-macenauer-absa]

Problem

Onboarding a docs repo into the knowledge base is documented end to end (contract/SINGLE_PAGE.md, contract/HEADLESS_RULES.md, contract/ARTIFACT.md, the two action READMEs), but a maintainer working in an AI-assisted editor still has to find those files, read them in the right order and hand-translate them into a workflow file, a kb-docs.json and possibly a headless build. Agents left to their own devices routinely over-build: they invent a scripts/pack.sh, write a manifest for a single-page repo that needs none, or copy the release workflow from an old fork with dist.tar.gz / marketplace.json in it.

The repo already owns the source of truth for all of this. It should also own the agent-facing instructions for applying it, so that "make this repo publish to the knowledge base" is a one-prompt task in Claude Code or GitHub Copilot and produces exactly what the contract asks for and nothing else.

Proposal

Add an Agent Skill to this repository, skills/kb-docs/ (name to be settled; must be a valid skill name), that guides an agent through onboarding a repo's documentation into the knowledge base.

What the skill does

1. Classifies the repo using the same three-way table as contract/SINGLE_PAGE.md: markdown files only → single-page; an existing static docs site (mkdocs, Starlight, Docusaurus…) → packaged; hosted elsewhere and not packageable → iframe (explicit stopgap, points the user at the deployment repo's apps.json instead of changing the docs repo).
2. Single-page path: writes one workflow file that calls actions/publish-single-page-docs@v1 with the inputs derived from the repo's markdown (docs, slug, name, description, icon, tags). Nothing else: no manifest, no build script, no package.json changes.
3. Packaged path: adds the headless build flag to the existing build, writes kb-docs.json against contract/kb-docs.schema.json, and writes one workflow file that runs the repo's own build and calls actions/publish-docs@v1. Checks the built HTML against contract/HEADLESS_RULES.md (relative paths, no <base>, data-kb-headless, design tokens) and reports what is missing rather than patching the site theme blindly.
4. Verifies by running the same checks the actions run (the action's validation is the oracle; the skill does not re-implement it) and tells the user how to trigger the first release and where the artifact shows up.
5. Troubleshoots by pointing to the existing ## Troubleshooting section of contract/SINGLE_PAGE.md and the actions' READMEs, extended where the skill's own dry runs surface gaps (missing contents: write, no release to attach to, kb-docs.tar.gz present but manifest slug mismatch, self-hosted runner needing npm-registry/node-mirror per contract/DEPLOYMENT.md).

Minimal-output rule

The skill must produce the minimum the contract requires and refuse to add more:

• single-page: exactly one file (.github/workflows/publish-docs.yml)
• packaged: kb-docs.json + one workflow file + the smallest build-flag change
• never a helper script, wrapper, Makefile target, or vendored copy of the schema or action code
• never a dist.tar.gz, marketplace.json, bundle.json or any other pre-v1 name

This rule goes in the skill body as an explicit instruction, and the skill's evals (below) assert it.

Skill layout and best practices

Follow the Agent Skills spec (SKILL.md with name + description frontmatter, progressive disclosure, references split into files loaded on demand):

skills/kb-docs/
  SKILL.md                      # when to trigger, decision table, the two paths, minimal-output rule, verify + troubleshoot pointers
  references/
    single-page.md              # copy-paste workflow + input table, mirrors contract/SINGLE_PAGE.md
    packaged.md                 # headless flag, kb-docs.json fields, workflow, HEADLESS_RULES checklist
    troubleshooting.md          # symptom → cause → fix, one table, links back to contract/
  examples/
    single-page.publish-docs.yml
    packaged.publish-docs.yml
    kb-docs.json

• description written for triggering: names the knowledge base, kb-docs.json, kb-docs.tar.gz, publish-single-page-docs, "onboard docs", "publish documentation to the knowledge base".
• SKILL.md under ~150 lines; anything longer moves to references/. No scripts directory: the actions already do the work, the skill only guides.
• Examples are copied verbatim from contract/ and the action READMEs (or generated from them in CI) so the skill cannot drift from the contract. A CI check diffs skills/kb-docs/examples/* against their sources.
• Use skill-creator-style evals: three fixture repos (markdown-only, mkdocs site, hosted-elsewhere), each with a prompt and an assertion on the produced file set. The minimal-output rule is asserted as "no files outside the allowed list".

Compatibility

• Claude Code: installable into .claude/skills/ (project) or ~/.claude/skills/ (user).
• GitHub Copilot: installable into .github/skills/ (Copilot coding agent and Copilot CLI read the same SKILL.md format).
• skills.sh: the repo layout must work with npx skills add AbsaOSS/knowledge-base — skills discovered under skills/*/SKILL.md, installed into whichever agents the user selects. Document the one-line install in the skill README and in README.md's onboarding section. Verify with a fresh checkout that npx skills add finds exactly this skill.
• Frontmatter limited to the fields every consumer understands (name, description, optional license, metadata); no Claude-only allowed-tools unless it degrades gracefully elsewhere.

Docs alignment

• contract/SINGLE_PAGE.md and contract/HEADLESS_RULES.md gain a short "With an AI agent" note pointing at the skill and the install command; they remain the normative text.
• README.md onboarding section lists the skill as the fastest route, after the three-type table.
• Skill prose follows the same voice and structure as contract/ (tables for choices, one code block per step, troubleshooting as symptom → fix).

Scope

• skills/kb-docs/SKILL.md + references/ + examples/ as above
• CI: example files diffed against their contract/ and action-README sources; SKILL.md frontmatter validated (name/description present, name matches directory)
• Evals: three fixture repos with prompt + expected file set; minimal-output assertion
• Verified installs: Claude Code (.claude/skills), Copilot (.github/skills), npx skills add AbsaOSS/knowledge-base
• README.md, contract/SINGLE_PAGE.md, contract/HEADLESS_RULES.md cross-reference the skill
• Try it on AbsaOSS/knowledge-base-example-single-page and AbsaOSS/knowledge-base-docs-example from a clean state; both should reproduce their current workflow files with no extra output

Notes

• The skill guides; the actions validate. If a check is worth having, it belongs in actions/lib/, and the skill tells the agent to run the action's self-test, not to reimplement the check.
• iframe stays a stopgap. The skill explains it and stops; it does not write anything for that path.