Agent tooling

The packaged kits

• node_modules/@oddkin/components/agent/GUIDE.md and node_modules/@oddkin/ai/agent/GUIDE.md: a short entry guide (within an 8 KiB budget) linking one reference per element under references/.
• agent/llms.txt: the same index in the llms.txt format.
• agent/kit.json: the manifest, with a fingerprint of every input, so a stale kit is detectable.

Point your agent’s instructions (an AGENTS.md line, for example) at the guide of each package you use. Publishing a file does not make every assistant read it.

This site publishes the same kits for the version it documents: its llms.txt lists each package’s guide and references, one link per component, with the files under /agent/.

What the kits are generated from

custom-elements.json (the standard Custom Elements Manifest) and oddkin.metadata.json: when to use each element and when not, accessibility and keyboard notes, customization levels, style mappings to tokens, and examples. Both are package exports, so tools can read them directly.

A kit for your own library

oddkin-kit (in @oddkin/analyzer) writes the same kit for your library from the metadata the analyzer publishes, checks it, and keeps a managed section of AGENTS.md that points agents at the kits. Run it in the workspace root:

# The kit your package ships, in <package>/agent/ (list "agent" in the package's "files")
npx oddkin-kit package
# Check it against the package's metadata; --package <name> checks an installed package's kit
npx oddkin-kit package --check
# The managed section of AGENTS.md; text outside its markers is kept
npx oddkin-kit agents-md --write

A stale, missing, or over-budget kit, or a stale AGENTS.md section, exits with 1, so CI can run the checks. A kit a package ships depends only on what the package publishes, so a project that installs it regenerates the same files.

Interfaces as data

An agent that produces structured output can describe an interface as a composition document. validateComposition() checks it against JSON Schemas generated from the metadata, and renderComposition() renders only published elements, attributes, and properties: no scripts, no HTML strings, no on* attributes.

import { validateComposition } from '@oddkin/components/composition';

const result = validateComposition({
  version: 1,
  root: [{ element: 'odd-button', attributes: { appearance: 'primary' }, children: ['Save'] }],
});
if (!result.ok) console.table(result.diagnostics);

Limits

• There is no Oddkin MCP server or agent package yet; the kits and the metadata are the interface.
• A packaged kit describes the version installed; for your own components, write a kit with oddkin-kit.