Skeleton

Skeleton

Ops manual for catalog, audit, validate, and init in a skeleton-enabled repo.

Agent doc routing (token-cheap)

1. If .skeleton/catalog.md is missing, run skeleton catalog.
2. Skim the catalog (path + one-line summary).
3. For a candidate, read only the source-of-truth line / first ~20 lines.
4. Open the full paper only if that line is truly relevant.

Human docs: getting started · config · troubleshooting.

When to use

• Edit skeleton.toml or .skeleton/customize/<slug>.md
• Run skeleton audit, skeleton validate, or skeleton catalog
• Sync or update skills from an external toolbox repo
• Avoid editing synced toolbox skill copies in the consumer repo

Catalog honesty is enforced by audit docs (ssot-summary / near-dupe) — do not assume one-liners stay accurate without that gate.

Doc-meta: one authored last-reviewed (human claim). Git is last-edit — no parallel edit stamp. When hash review proof is enabled, .skeleton/review-lock.json binds that claim to the exact document and review-deps bytes. daysUntilStale remains an optional re-read cadence. Details: doc system.

Not for: normal feature work that only reads toolbox skills (optional customize hooks can inject on skill reads).

Layout

skeleton.toml           # preferred root config (scan, stale, docsLint)
.skeleton/
├── catalog.md          # generated, gitignored — run `skeleton catalog`
├── review-lock.json    # review hashes when reviewProof.mode = "hash"
├── plugins/            # optional audit plugins (.ts + .mjs)
└── customize/          # per-slug overrides for toolbox-bound skills
    └── <slug>.md

Legacy .skeleton/config.yaml still loads if no skeleton.toml is present.

Customize hooks (optional)

Hooks are an optional improvement, not required for audit/validate/catalog.

skeleton init may merge IDE hooks that run a cwd-local node node_modules/@csark0812/skeleton/dist/cli.js hook customize on skill reads. Inside this repo the hook runs bun src/cli.ts hook customize.

• Hook injects .skeleton/customize/<slug>.md when path is /SKILL.md or under a skill tree
• Never edit synced toolbox SKILL.md files in the consumer repo — override in .skeleton/customize/<slug>.md
• Manual fallback: skeleton customize resolve <slug>

Details: docs/developer/customize.md

Setup

npm install -D @csark0812/skeleton
npx skeleton init --skills

Edit skeleton.toml scan trees for this repo shape.

Workflow

1. Add <!-- source-of-truth: one-line summary --> (or visible source-of-truth: …) to canonical docs
2. Run skeleton catalog
3. Add review-deps paths or globs where repository changes can invalidate the paper
4. Run skeleton audit docs (or audit self)

After a complete human re-read, record review evidence for explicit paths only:

skeleton audit docs --paths=docs/example.md --fix=doc-meta --confirm-reviewed

Do not run this command as a mechanical date cleanup. Bare --fix changes anchors and legacy SSOT markers only.

CLI

register was removed — add a source-of-truth marker and run skeleton catalog.

Plugins: docs/developer/plugins.md

Machine consumers: audit --json emits one versioned result document. Validate it with the exported schemas/result.schema.json; use @csark0812/skeleton/result-types for TypeScript. validate changed is plain text only, with affected documents, matching dependencies, native gates, and a final pass/fail line.