Maintenance automation

Maintenance logic SHOULD live in an Agent Skill, client command, CI job, or external tool that reads and writes the pack.

For knowledge packs, common automation is compilation: incrementally turn sources/ into wiki/, compiled/, and indexes/, then write the process to runs/.

If the maintenance workflow needs a full Skill, start with Skills interop. For script interface details, see the maintenance script contract.

Boundary rule

Do not make clients execute code from a knowledge pack during discovery or activation.

Recommended placement

Asset	Recommended home	Reason
PDF ingestion script	Agent Skill scripts/ or client tool	It is a method.
Knowledge compiler	Agent Skill scripts/, client tool, or CI	It turns sources into wiki pages, runtime views, and indexes.
Citation linter	Agent Skill scripts/, CI, or client tool	It performs validation.
JSON schema for extracted claims	Knowledge pack schemas/	It describes data shape.
Static prompt template for a review workflow	Agent Skill or assets/ with clear non-executable status	It is procedural if it tells the agent what to do.
Generated lint output	Knowledge pack runs/	It is audit evidence.
Discovery or answer-quality test cases	Knowledge pack evals/	They define expected behavior.

Compiler interface contract

If a maintenance tool performs compilation, prefer a stable subcommand or arguments:

agent-knowledge compile \
  --pack ./acme-product-brief \
  --changed sources/reports/q1.md \
  --output-run runs/compile-2026-05-01T10-30-00Z.json

The compiler SHOULD:

• support --dry-run to show which wiki/, compiled/, and indexes/ files would change
• record input file hashes, output files, operations, and diagnostics
• preserve source maps so important claims trace back to sources/ anchors
• update the affected set incrementally to avoid unrelated page drift
• suggest needs-review, stale, or disputed when gates fail
• never run automatically during pack discovery or activation

One-off commands

For simple maintenance, document pinned one-off commands in the maintaining Skill or project docs:

npx markdownlint-cli2@0.14.0 "wiki/**/*.md" "compiled/**/*.md"
uvx ruff@0.8.0 check tools/knowledge_lint.py

Rules:

• pin versions when the command affects review results
• state prerequisites explicitly
• move complex command sequences into tested scripts
• write results to runs/ when they affect pack status

Script interface contract

When a Skill or client tool provides scripts for knowledge maintenance, scripts SHOULD be agent-friendly:

• no interactive prompts
• --help with concise usage and examples
• structured output, preferably JSON for machine use
• diagnostics on stderr, data on stdout
• deterministic paths relative to the pack root
• --dry-run for writes or destructive changes
• bounded output with --limit, --offset, or --output
• idempotent operations where possible

Example linter invocation:

python scripts/lint_knowledge.py \
  --pack ./acme-product-brief \
  --grounding required \
  --output runs/lint-2026-05-01.json

Example JSON result:

{
  "status": "needs-review",
  "findings": [
    {
      "severity": "error",
      "path": "compiled/facts.md",
      "message": "Pricing claim is missing a source anchor."
    }
  ]
}

Example compile result:

{
  "run_id": "compile-2026-05-01T10-30-00Z",
  "status": "needs-review",
  "inputs": [
    {
      "path": "sources/reports/q1.md",
      "sha256": "..."
    }
  ],
  "outputs": [
    {
      "path": "wiki/concepts/offline-queue.md",
      "operation": "updated"
    },
    {
      "path": "compiled/facts.md",
      "operation": "updated"
    }
  ],
  "diagnostics": [
    {
      "severity": "warning",
      "path": "wiki/open-questions/pricing.md",
      "message": "Pricing information is missing an official source."
    }
  ]
}

Self-contained scripts

If a maintenance Skill bundles scripts, prefer self-contained dependency declarations:

• Python scripts can use PEP 723 metadata and run with uv run.
• Node tools can use pinned npx package@version for one-off commands.
• Deno scripts can pin npm: or jsr: imports.
• Go tools can use go run module@version.

Agent Knowledge does not require any of these runtimes. They belong to the maintaining toolchain, not the data format.

Status changes

Automation MAY propose a status change. Clients MUST NOT silently mark a pack ready unless owner policy allows it.

Recommended policy:

Transition	Automation allowed?	Human review
draft -> needs-review	Yes	Optional
needs-review -> ready	Only with explicit policy	Recommended
ready -> stale	Yes, if source freshness check fails	Notify owner
ready -> disputed	Yes, if contradiction is detected	Required to resolve
any -> archived	No by default	Required

Runs are evidence, not authority

runs/ records what a tool did. It does not replace the reviewed knowledge in wiki/ or compiled/.

A resolver may surface run findings as warnings, but the current pack status and selected context still come from KNOWLEDGE.md and maintained files.