setup-knowledge-system

Files (29)

• SKILL.md
• definition.md · resources/automations/kb-reconcile/
• README.md · resources/knowledge-system-interface/v1/
• capture-blocked.schema.json · resources/knowledge-system-interface/v1/
• capture-draft.schema.json · resources/knowledge-system-interface/v1/
• capture-request.schema.json · resources/knowledge-system-interface/v1/
• endpoint-registry.json · resources/knowledge-system-interface/v1/
• capture-blocked.json · resources/knowledge-system-interface/v1/examples/
• capture-draft.json · resources/knowledge-system-interface/v1/examples/
• capture-request.json · resources/knowledge-system-interface/v1/examples/
• project-snapshot-operation.json · resources/knowledge-system-interface/v1/examples/
• project-snapshot-request.json · resources/knowledge-system-interface/v1/examples/
• project-snapshot.json · resources/knowledge-system-interface/v1/examples/
• request.json · resources/knowledge-system-interface/v1/examples/
• snapshot-token-validation-operation.json · resources/knowledge-system-interface/v1/examples/
• snapshot-token-validation-request.json · resources/knowledge-system-interface/v1/examples/
• snapshot-token-validation-result.json · resources/knowledge-system-interface/v1/examples/
• snapshot.json · resources/knowledge-system-interface/v1/examples/
• produce-project-snapshot.py · resources/knowledge-system-interface/v1/
• project-snapshot-operation.schema.json · resources/knowledge-system-interface/v1/
• project-snapshot-request.schema.json · resources/knowledge-system-interface/v1/
• project-snapshot.schema.json · resources/knowledge-system-interface/v1/
• request.schema.json · resources/knowledge-system-interface/v1/
• snapshot-token-validation-operation.schema.json · resources/knowledge-system-interface/v1/
• snapshot-token-validation-request.schema.json · resources/knowledge-system-interface/v1/
• snapshot-token-validation-result.schema.json · resources/knowledge-system-interface/v1/
• snapshot.schema.json · resources/knowledge-system-interface/v1/
• validate-snapshot-token.py · resources/knowledge-system-interface/v1/
• reconcile-interface.sh · scripts/

SKILL.md (first lines)

# Setup Knowledge System

## Command

Run `/setup-knowledge-system check` for a fresh read-only health check or
`/setup-knowledge-system reconcile` to apply safe deltas and finish with the same
fresh check. Omitted mode means `reconcile`. Reject every other mode.

Knowledge System is independently usable. Do not inspect, clone, install, or
reconcile Agentic OS, Mastery System, Career Ops, a Distribution Bundle, or any
cross-system automation.

## Result

Report one overall state and a state for each branch:

- `converged`: observed live state already matches the bundled definition;
- `drifted`: check found a safe delta that reconcile can apply;
- `blocked`: user input, access, or an unavailable dependency prevents only this
  branch from converging;
- `failed`: malformed data, an unsafe invariant, an unexpected error, or a claimed
  write that remains drifted after the final check.

Continue across independent branches. Never treat an earlier setup run, receipt,
version record, or prompt snapshot as evidence of current health.

## Bundled Sources

Resolve all resource paths relative to this `SKILL.md`; an installed setup skill
must not require a repository checkout or fetch a hidden latest release.

- The canonical interface package is
  `resources/knowledge-system-interface/v1/`.
- The canonical KB Reconcile definition is
  `resources/automations/kb-reconcile/definition.md`.
- The installed interface target is
  `<harness-skill-root>/knowledge-system-interface/v1/`. It is a non-skill package
  with a provider-blind validation executable and must not contain `SKILL.md` or
  become user-invocable.
- The canonical public skill names are `lookup`, `capture`, and
  `setup-knowledge-system`. They are distributed from `skills/public/` by their
  owning Knowledge System release.
- `get-knowledge` and `grill-knowledge` are internal, repo-native helpers. They are
  committed under `skills/internal/`, excluded from normal public distribution,
  and installed only through an explicit repo-native action.

`/lookup` and `/capture` resolve the shared interface package relative to their
harness skill root. A missing package, an unsupported interface major, an invalid
registry, or a role absent from the registry blocks only the capability that needs
it.

## Check

Check is strictly read-only. Read live state, compute all comparisons in memory or
a disposable temporary directory, report the result, and make zero writes.

### 1. Bindings and provider

Find the installation's existing `local/bindings.yml`. Preserve the file byte for
byte throughout setup unless the user explicitly supplies a missing value for a
safe additive update.

- Validate its shape against `local/bindings.example.yml` when a source checkout is
  available. Unknown valid keys and values are preserved.
- A nonblank provider name and connector are required. Validate the connector with
  one narrow live read.
- Validate only the endpoint roles required by Knowledge System capabilities: the
  active Endpoint Registry and KB Reconcile. A key is not proof of a binding;
  resolve it live by meaning or by its recorded hint.
- Blank is valid only when the role resolves unambiguously by meaning. A placeholder,
  inaccessible owner, or ambiguous owner is `blocked`, never fabricated state.
- Changing an existing provider is outside ordinary reconciliation and requires the
  dedicated approval-gated provider migration.

Never rebuild the whole bindings file, delete a value because the current release
does not understand it, or copy provider coordinates into committed files.

### 2. Public and internal skills

Inspect the live harness skill root, not an installed receipt.

- Verify `lookup`, `capture`, and `setup-knowledge-system` are present and are from
  the same explicit Knowledge System installation action.
- Verify the installed `lookup` and `capture` contracts resolve
  `knowledge-system-interface/v1` from the shared harness skill root.
- Report missing or stale public skills as drift that requires an explicit install
  or upgrade of the owning release. Do not silently fetch or upgrade a release.
- Do not install internal skills during ordinary public setup. When setup runs from
  the owning repository and the user explicitly requests the internal install,
  compare and copy only `skills/internal/get-knowledge` and
  `skills/internal/grill-knowledge`.

### 3. Knowledge System interface

Validate the bundled v1 package before comparing it:

- every JSON file parses;
- every schema validates its bundled example;
- every request and capture role exists and is active in the Endpoint Registry;
- the registry revision is nonblank;
- the Snapshot Token validation operation executes its self-check;
- the Knowledge Project Snapshot producer executes its self-check;
- the package contains no `SKILL.md`.

Compare the complete bundled and installed trees by relative path, file type, and
content. Extra installed files are drift because the installed package must be an
exact non-skill materialization. Do not use timestamps as evidence.

Use `scripts/reconcile-interface.sh check <harness-skill-root>` for this exact tree
comparison when filesystem access is available. Report
`snapshot-token-validation` as a distinct capability: `ready` only when the
installed executable passes a fresh self-check, otherwise `blocked` with the
observed reason. Package drift and capability readiness remain separate facts.
Report `knowledge-project-snapshot` the same way from a fresh installed
`produce-project-snapshot.py --self-check`. This read-only capability has no KB
capture or write authority.

### 4. KB Reconcile

From giacomoguidotto/skills, MIT.

More from giacomoguidotto/skills