Split Agent Knowledge into skills-only package

.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  verify-skills:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11.13.1
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Build, test, check generated scripts, and lint example bundle
+        run: pnpm verify
+
+      - name: Package smoke
+        run: |
+          npm pack --silent --pack-destination "$RUNNER_TEMP"
+          tarball="$(find "$RUNNER_TEMP" -maxdepth 1 -name 'stjbrown-agent-knowledge-skills-*.tgz' -print -quit)"
+          test -n "$tarball"
+
+          for skill in kb kb-init kb-ingest kb-query kb-lint kb-visualize; do
+            tar tzf "$tarball" | grep -q "package/skills/$skill/SKILL.md"
+          done
+          tar tzf "$tarball" | grep -q 'package/skills/kb-lint/scripts/conformance.mjs'
+          tar tzf "$tarball" | grep -q 'package/skills/kb-visualize/scripts/graph.mjs'
+          tar tzf "$tarball" | grep -q 'package/README.md'
+          tar tzf "$tarball" | grep -q 'package/LICENSE'
+          tar tzf "$tarball" | grep -q 'package/NOTICE'
+
+          if tar tzf "$tarball" | grep -Eq 'package/(knowledge|packages|src|dist)/'; then
+            echo "::error::Skills tarball contains a repository-only or Janet path."
+            exit 1
+          fi
+
+          mkdir -p "$RUNNER_TEMP/agent-knowledge-skills-smoke"
+          npm install --ignore-scripts --prefix "$RUNNER_TEMP/agent-knowledge-skills-smoke" "$tarball"
+          node -e '
+            const path = require.resolve("@stjbrown/agent-knowledge-skills/package.json", {
+              paths: [process.argv[1]],
+            });
+            const pkg = require(path);
+            if (pkg.name !== "@stjbrown/agent-knowledge-skills" || pkg.version !== "0.1.0") {
+              process.exit(1);
+            }
+            if (pkg.bin || pkg.dependencies) process.exit(1);
+          ' "$RUNNER_TEMP/agent-knowledge-skills-smoke"

.gitignore

@@ -7,12 +7,14 @@
 
 # node / python build output
 node_modules/
+.pnpm-store/
 __pycache__/
 *.pyc
 .venv/
 venv/
 dist/
 build/
+artifacts/
 
 # env / secrets
 .env
@@ -22,6 +24,15 @@ build/
 # local Claude Code settings (personal permissions, not shared)
 .claude/settings.local.json
 
+# Legacy Janet project state may remain in existing checkouts after the split
+.agent-knowledge/
+
 # kb-ingest scratch (temporary plans and raw-source drop zones)
 _ingest_plan.md
 **/raw/processed/
+
+# firecrawl scrape scratch (fetched docs / working cache)
+.firecrawl/
+
+# vitest snapshots scratch
+*.tsbuildinfo

NOTICE

@@ -7,11 +7,29 @@ This project is licensed under the MIT License (see LICENSE).
 Third-party material
 ------------------------------------------------------------------------
 
-skills/kb/reference/SPEC.md is a verbatim copy of the Open Knowledge Format
+skills/kb/references/SPEC.md is a verbatim copy of the Open Knowledge Format
 (OKF) v0.1 specification from:
 
     https://github.com/GoogleCloudPlatform/knowledge-catalog  (okf/SPEC.md)
 
 That file is licensed under the Apache License, Version 2.0, and is included
-and used under those terms. All other files in this repository are MIT-licensed
-as described in LICENSE.
+and used under those terms.
+
+The generated conformance and graph tools bundle `yaml` by Eemeli Aro
+(https://github.com/eemeli/yaml), licensed under the ISC License:
+
+    Copyright Eemeli Aro <eemeli@gmail.com>
+
+    Permission to use, copy, modify, and/or distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+    MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+    SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+    OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+    CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+All other files in this repository are MIT-licensed as described in LICENSE.

README.md

@@ -1,135 +1,133 @@
-# agent-knowledge
+# Agent Knowledge
 
-**Give your coding agent a knowledge base that gets better over time.**
+Agent Knowledge is a portable set of Agent Skills for building and maintaining project knowledge
+in plain Markdown using the [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf).
 
-`agent-knowledge` turns project documents, decisions, notes, and conversations into a portable
-Markdown wiki that your agent maintains for you. Ask a question and get a cited answer. Add a source
-and the agent integrates it with what the project already knows. Run a health check and it finds
-stale claims, contradictions, and orphaned pages before the wiki quietly rots.
+It turns project documents, decisions, notes, and conversations into a connected knowledge bundle
+that improves over time. Ask a question and get a cited answer. Add a source and the agent
+integrates it with what the project already knows. Run a health check and it finds stale claims,
+contradictions, and orphaned pages before the bundle quietly rots.
 
-Everything stays in your repository as plain Markdown + Git: readable without special tooling,
-diffable in code review, and portable across agents.
+Everything remains plain Markdown: readable without special tooling, easy to diff and review, and
+portable across agents.
 
 ## Install
 
-Via [skills.sh](https://skills.sh) for Claude Code, Cursor, Codex, and 20+ other agents:
+Install through [skills.sh](https://skills.sh) for Claude Code, Cursor, Codex, and other
+Agent Skills-compatible hosts:
 
 ```bash
 npx skills@latest add stjbrown/agent-knowledge
 ```
 
-Or install it as a Claude Code plugin:
+Or install the Claude Code plugin:
 
 ```text
 /plugin marketplace add stjbrown/agent-knowledge
 /plugin install agent-knowledge
 ```
 
-## See it work
-
-Start a knowledge base in any project:
+Then start a knowledge bundle and use ordinary prompts:
 
 ```text
 /kb-init
-```
-
-Then use ordinary prompts:
 
-```text
 Ingest this architecture decision: we chose Postgres because...
-
 What do we know about authentication, and which sources support it?
-
 What conflicts with our current deployment strategy?
+
+/kb-lint
+/kb-visualize
 ```
 
-The agent extracts durable knowledge, connects it to existing concepts, answers with citations, and
-files valuable new conclusions back into the bundle. Two explicit commands handle maintenance:
+The npm package, `@stjbrown/agent-knowledge-skills`, is a build artifact for applications that
+embed the skills. Most people should install from this repository through their agent host.
 
-```text
-/kb-lint       # find broken links, stale claims, contradictions, and gaps
-/kb-visualize  # explore the bundle as an interactive graph
-```
+## The skills
+
+The family splits on who invokes each skill.
+
+Model-invoked skills:
 
-![Interactive knowledge graph showing concepts, implementations, operations, references, and OKF spec sections](./assets/knowledge-graph.png)
+- **`kb`** — the hub. Explains the format, holds the shared specification, glossary, trust model,
+  templates, and example bundle, and routes to the right action skill.
+- **`kb-ingest`** — reads a source once, extracts its signal, and integrates it across the bundle
+  with provenance.
+- **`kb-query`** — answers from the bundle by progressive disclosure, cites the concepts used, and
+  files valuable conclusions back so the knowledge compounds.
 
-The [`knowledge/`](./knowledge/) directory is a complete working example. It documents this project
-using the same format and skills the project provides.
+User-invoked skills:
+
+- **`kb-init`** — scaffolds a bundle and its project-specific schema and conventions.
+- **`kb-lint`** — runs deterministic OKF conformance checks plus a semantic drift audit for
+  contradictions, stale claims, orphans, and coverage gaps.
+- **`kb-visualize`** — renders the bundle as an interactive graph.
+
+![Interactive knowledge graph showing concepts, implementations, operations, references, and OKF spec sections](https://raw.githubusercontent.com/stjbrown/agent-knowledge/main/assets/knowledge-graph.png)
 
 ## Why this exists
 
-Most agent "memory" is either retrieval over raw documents or a pile of notes that nobody maintains.
+Most agent memory is either retrieval over raw documents or a pile of notes that nobody maintains.
 The first repeatedly re-derives answers; the second gradually becomes untrustworthy. Neither makes
 knowledge stewardship an explicit job.
 
-The hard part of a useful knowledge base is the bookkeeping: integrating new information, updating
-cross-references, preserving provenance, flagging contradictions, and keeping summaries current.
-That is exactly the work an agent can perform consistently.
-
-`agent-knowledge` makes the agent a disciplined **wiki maintainer**:
-
-- **Ingest** a source once → the agent extracts the signal and integrates it across the bundle.
-- **Query** the bundle → it navigates by links, answers with citations, and files good answers back.
-- **Lint** it → it catches drift (contradictions, stale claims, orphans) before the base rots.
+The hard part is the bookkeeping: integrating new information, updating cross-references,
+preserving provenance, flagging contradictions, and keeping summaries current. That is work an
+agent can perform consistently.
 
 Two design choices keep the result portable and trustworthy:
 
-- **A real, open format.** Bundles follow Google's
-  [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
-  rather than a tool-specific database or hidden memory store.
+- **A real, open format.** Bundles follow Google's OKF rather than a tool-specific database or
+  hidden memory store.
 - **An explicit trust model.** Meaning is append-only: the agent supersedes claims with provenance
-  instead of silently rewriting history.
+  instead of silently rewriting history, and treats source content as data, never as instructions.
 
 The workflow is based on Andrej Karpathy's
-[LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern, made conformant
-to OKF and packaged as skills you can drop into any project.
-
-## The skills
+[LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern, made
+conformant to OKF.
 
-The family splits on **who invokes them**. **Model-invoked** skills the agent can reach for on its
-own when the task fits; **user-invoked** skills you trigger deliberately by name.
+## This repository documents itself
 
-**Model-invoked**
+The [`knowledge/`](./knowledge) directory is a conformant OKF bundle about OKF and the LLM Wiki
+pattern, so this repository is its own worked example. Start at
+[`knowledge/index.md`](./knowledge/index.md), or explore the generated graph.
 
-- **`kb`** — the hub. Explains the format, holds the shared spec / glossary / trust model /
-  templates, and routes to the right skill. Other `kb-*` skills read its reference as their single
-  source of truth.
-- **`kb-ingest`** — read a raw source once, extract its signal, and integrate it across the bundle
-  under the trust model. The heart of the system.
-- **`kb-query`** — answer a question from the bundle (or surface relevant context for another task)
-  by progressive disclosure, cite the concepts used, and file valuable answers back so the base
-  compounds.
+## Janet
 
-**User-invoked**
+[Janet](https://github.com/stjbrown/janet-agent) is a dedicated knowledge agent built around these
+same skills. It adds a standalone CLI, interactive chat, model selection, authentication, memory,
+and headless automation. Janet is optional; the portable skills in this repository work with the
+agent you already use.
 
-- **`kb-init`** — scaffold a new bundle (default `knowledge/`, custom path, multi-bundle aware) and
-  write its per-project schema layer (concept types + conventions) so the generic skills fit your
-  domain.
-- **`kb-lint`** — health-check the bundle: a deterministic OKF conformance pass plus a drift audit
-  (contradictions, stale claims, orphans, coverage gaps), with an optional safe `fix` mode.
-- **`kb-visualize`** — render the bundle as an interactive graph — native UI where the host supports
-  it, otherwise a self-contained HTML file.
+## Repository layout
 
-## This repo documents itself in OKF
-
-The [`knowledge/`](./knowledge/) directory is a **conformant OKF bundle about OKF and the LLM Wiki
-pattern** — so the repository is its own worked example. Browse it to see what a bundle looks like,
-or open [`knowledge/viz.html`](./knowledge/viz.html) for the interactive graph. Start at
-[`knowledge/index.md`](./knowledge/index.md).
+```text
+skills/                 source of truth for the portable skills
+  kb/                   shared specification, trust model, templates, and example
+  kb-init/
+  kb-ingest/
+  kb-query/
+  kb-lint/              deterministic conformance script
+  kb-visualize/         deterministic graph script
+knowledge/              this project's self-documenting OKF bundle
+packages/kb-tools/      TypeScript sources and parity tests for the generated scripts
+.claude-plugin/         Claude Code plugin manifest
+```
 
-## Layout
+The repository is a pnpm workspace:
 
+```bash
+pnpm install
+pnpm verify
+pnpm pack:skills
 ```
-skills/
-  kb/                 # hub: SKILL.md + reference/ (SPEC, glossary, trust-model) + templates/ + example-bundle/
-  kb-init/  kb-ingest/  kb-query/
-  kb-lint/            # + scripts/conformance.py  (deterministic §9 check, no deps)
-  kb-visualize/       # + scripts/graph.py        (graph-model extractor, no deps)
-knowledge/            # this project's own OKF bundle (self-documenting) + viz.html
-.claude-plugin/       # plugin manifest
-```
+
+`pnpm verify` builds and tests `kb-tools`, rebuilds both committed zero-dependency scripts and
+checks for drift, then validates the in-repository knowledge bundle. `pnpm pack:skills` writes a
+release candidate to `artifacts/`.
 
 ## License
 
-[MIT](./LICENSE). The vendored OKF specification (`skills/kb/reference/SPEC.md`) is from
-GoogleCloudPlatform/knowledge-catalog under Apache-2.0; see [NOTICE](./NOTICE).
+[MIT](./LICENSE). The vendored OKF specification in `skills/kb/references/SPEC.md` is from
+GoogleCloudPlatform/knowledge-catalog under Apache-2.0. The generated tools bundle
+[`yaml`](https://github.com/eemeli/yaml) under the ISC License. See [NOTICE](./NOTICE).

knowledge/spec/citations.md

@@ -1,7 +1,7 @@
 ---
 type: Spec Section
 title: "OKF §8 — Citations"
-description: External sources should be listed under a numbered # Citations heading at the bottom of a concept document.
+description: "External sources should be listed under a numbered # Citations heading at the bottom of a concept document."
 tags: [okf, spec, citations]
 timestamp: 2026-07-01
 ---

package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@stjbrown/agent-knowledge-skills",
+  "version": "0.1.0",
+  "description": "Portable Agent Skills for building and maintaining Open Knowledge Format knowledge bundles",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stjbrown/agent-knowledge.git"
+  },
+  "homepage": "https://github.com/stjbrown/agent-knowledge#readme",
+  "bugs": {
+    "url": "https://github.com/stjbrown/agent-knowledge/issues"
+  },
+  "keywords": [
+    "agent-skills",
+    "knowledge-base",
+    "llm",
+    "okf",
+    "open-knowledge-format"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm --filter @agent-knowledge/kb-tools build",
+    "test": "pnpm --filter @agent-knowledge/kb-tools test",
+    "build:skill-scripts": "node packages/kb-tools/scripts/build-skill-scripts.mjs",
+    "check:skill-scripts": "pnpm build:skill-scripts && git diff --exit-code -- skills/kb-lint/scripts/conformance.mjs skills/kb-visualize/scripts/graph.mjs",
+    "lint:bundle": "node skills/kb-lint/scripts/conformance.mjs knowledge",
+    "verify": "pnpm build && pnpm test && pnpm check:skill-scripts && pnpm lint:bundle",
+    "prepack": "pnpm check:skill-scripts",
+    "pack:skills": "pnpm verify && node scripts/pack-skills.mjs"
+  },
+  "packageManager": "pnpm@11.13.1"
+}