Skip to content

content-guide.md

Latest commit

 

History

History
234 lines (173 loc) · 6.5 KB

content-guide.md

File metadata and controls

234 lines (173 loc) · 6.5 KB

Content Guide

How to create docs and skills for Context Hub.

Directory Structure

Content is organized by author (vendor/org), then by type (docs or skills), then by entry name:

my-content/
  acme/
    docs/
      widgets/
        DOC.md                    # single-language doc
        references/
          advanced.md             # additional reference file
      client/
        javascript/
          DOC.md                  # multi-language: JS variant
        python/
          DOC.md                  # multi-language: Python variant
      api/
        v1/
          DOC.md                  # multi-version: v1
        v2/
          DOC.md                  # multi-version: v2
    skills/
      deploy/
        SKILL.md                  # a skill

Single-language docs

Place DOC.md directly in the entry directory:

author/docs/entry-name/DOC.md

Multi-language docs

Create a subdirectory per language:

author/docs/entry-name/javascript/DOC.md
author/docs/entry-name/python/DOC.md

Multi-version docs

When an API has breaking changes across major versions, create a subdirectory per version:

author/docs/entry-name/
  v1/
    DOC.md                  # versions: "1.0.0"
  v2/
    DOC.md                  # versions: "2.0.0"

Both DOC.md files must share the same name in frontmatter. The build groups them into a single registry entry with multiple versions. The highest version becomes the recommendedVersion — what agents get by default.

You can combine multi-version with multi-language:

author/docs/entry-name/
  v1/
    javascript/
      DOC.md
    python/
      DOC.md
  v2/
    javascript/
      DOC.md
    python/
      DOC.md

Agents request a specific version with --version:

chub get author/entry-name                    # latest version (recommended)
chub get author/entry-name --version 1.0.0    # specific version

If a requested version doesn't exist, the CLI lists available versions.

Skills

Place SKILL.md in the entry directory:

author/skills/entry-name/SKILL.md

Reference files

Additional files (examples, advanced topics, error references) go alongside the entry file:

author/docs/widgets/
  DOC.md
  references/
    advanced.md
    errors.md

These are discoverable via chub get (shown in the footer) and fetchable with --file or --full.

Frontmatter

Every DOC.md and SKILL.md starts with YAML frontmatter.

DOC.md frontmatter

---
name: widgets
description: "Acme widget API for creating and managing widgets"
metadata:
  languages: "javascript"
  versions: "2.0.0"
  revision: 1
  updated-on: "2026-01-01"
  source: maintainer
  tags: "acme,widgets,api"
---
Field Required Description
name Yes Entry name (used in the ID: author/name)
description Yes Short description for search results
metadata.languages Yes Language of this doc variant
metadata.versions Yes Package/SDK version this doc covers (the version on npm or pypi)
metadata.revision Yes Content revision number (monotonically increasing, starts at 1)
metadata.updated-on Yes Date this content was last revised
metadata.source Yes Trust level: official, maintainer, or community
metadata.tags No Comma-separated tags for filtering

SKILL.md frontmatter

---
name: deploy
description: "Deployment automation skill for CI/CD pipelines"
metadata:
  revision: 1
  updated-on: "2026-01-01"
  source: community
  tags: "deploy,ci,automation"
---

Skills have the same fields as docs except languages and versions are not required (skills are language-agnostic).

Versioning Guide

Package version vs API version

The versions field always refers to the package/SDK version — the version number on npm or pypi. This is what agents can detect from package.json or requirements.txt.

If a library has a separate API versioning scheme (like Stripe's dated API versions 2024-12-18.acacia), document that within the content body. The frontmatter versions stays as the package version.

API-level versioning

When an API has fundamentally different versions (different endpoints, different auth, different request/response shapes), use the entry name to distinguish them:

stripe/docs/payments-api-v1/DOC.md    # name: payments-api-v1
stripe/docs/payments-api-v2/DOC.md    # name: payments-api-v2

These become separate entries in the registry (stripe/payments-api-v1 and stripe/payments-api-v2), each with their own package version tracking.

Updating content

When you improve content for the same package version (fix examples, add details, clarify wording):

  1. Bump revision (e.g., 1 → 2)
  2. Update updated-on to today's date
  3. Keep versions the same

Together, revision and updated-on give agents a clear signal of content freshness.

Writing Content

Content is markdown, written for LLM consumption. Keep these in mind:

  • Be direct. Agents don't need introductions or marketing. Start with what the API does and how to use it.
  • Show code first. A working example is worth more than a paragraph of explanation.
  • Cover the common case. Don't exhaustively document every option. Cover what agents will actually need 90% of the time.
  • Use reference files for depth. Put advanced topics, error handling, and edge cases in separate reference files rather than making the main doc too long.

Building

Use chub build to compile your content directory into a registry:

chub build my-content/                           # build to my-content/dist/
chub build my-content/ -o dist/                  # custom output directory
chub build my-content/ --validate-only           # validate without building

The build process:

  1. Discovers all DOC.md and SKILL.md files
  2. Validates frontmatter (checks required fields)
  3. Generates registry.json with entry metadata
  4. Copies content files to the output directory

Validation

Run --validate-only to check your content without building:

chub build my-content/ --validate-only

This reports the number of docs and skills found, and flags any frontmatter errors.

Using built content locally

Point your config at the build output to use it alongside the public registry:

# ~/.chub/config.yaml
sources:
  - name: community
    url: https://cdn.aichub.org/v1
  - name: my-team
    path: /path/to/my-content/dist

Now chub search and chub get cover both public and your local content.