CodeWiki / skillwiki

Project-aware Karpathy-style knowledge base for Claude Code skills.

/plugin marketplace add karlorz/llm-wiki
/plugin install skillwiki@llm-wiki

The plugin ships 22 skills (wiki-*, proj-*, wiki-add-task, wiki-adapter-prd, wiki-reingest, using-skillwiki, skillwiki-mcp, skillwiki-connect). They are namespaced by Claude Code as llm-wiki:<skill> (e.g. llm-wiki:wiki-init).

npx skillwiki@latest install

This copies 22 SKILL.md files into ~/.claude/skills/ and writes .claude/skills/wiki-manifest.json. Use this when you want the skills available outside a Claude Code plugin context, or to seed ~/.claude/skills/ for tools that scan it directly.

agy plugin install https://github.com/karlorz/llm-wiki

The repository root includes an agy-compatible plugin.json plus a matching .claude-plugin/plugin.json marker for GitHub URL installs. Root skills/ and agents/ are materialized mirrors of the canonical files under packages/skills/. Derive the current skill and agent counts from those mirrors before validating:

agy plugin validate .

find skills -mindepth 2 -maxdepth 2 -name SKILL.md -print | wc -l
find agents -mindepth 1 -maxdepth 1 -name '*.md' -print | wc -l

After changing canonical skill, agent, or hook assets under packages/skills/, regenerate install-facing mirrors before validating:

npm run materialize:plugins
npm run materialize:plugins:check

Cursor / Grok Bot do not list this repo on the public Cursor Marketplace. A GitHub or npm release does not move the pin; Reinstall repeats the last indexed snapshot. Check cursor-agent plugin marketplace list --format json.

If "scope": "user" for llm-wiki (operator GitHub add), Dashboard Refresh / Auto Refresh does not apply. Follow cursor-github-marketplace-repin (status.sh, then remove + add --git-ref). After rempin, restore KEEP plugins (skillwiki, vault-sync) via /plugins or install-keep-plugins.sh — Cursor CLI 2026.08.25 has no plugin install. Grok Bot shares that Cursor account list. Until the pin advances, use Option B or grok plugin update skillwiki.

To update a Team marketplace admin row (scope is not user):

1. Push the release tag.
2. Dashboard → Plugins → karlorz/llm-wiki → Refresh or Enable Auto Refresh (needs the Cursor GitHub App; re-index at most every 10 minutes).
3. Refocus or restart Cursor / Grok Bot.
4. Confirm ~/.cursor/plugins/cache/llm-wiki/skillwiki/<git-sha>/plugin.json version matches the release.

If the SHA is unchanged, re-import https://github.com/karlorz/llm-wiki in Team marketplace and Refresh again.

A sibling vault-sync plugin ships six operational skills (install, status, presync, snapshot, FUSE freshness, uninstall). It is packaged separately from the skillwiki skill set.

skillwiki exposes a deterministic CLI consumed by the skills. Prefer the built help over hard-coded counts:

npm run -w packages/cli build
node packages/cli/dist/cli.js --help

Use built --help as the authority for the current command surface rather than a hard-coded count. To calculate the listed top-level commands from that authority:

node packages/cli/dist/cli.js --help | awk '/^Commands:/{listed=1; next} listed && /^  [a-z]/{count++} END {print count}'

All subcommands emit JSON by default. Pass --human for terminal output. tag reconcile and page publish default to dry-run; add --write only after their preview succeeds. page publish is the required write path for new or updated typed knowledge pages.

Raw evidence is immutable after capture. The CLI may create new captures and, through attended state-bound workflows, preserve-move exact bytes within raw/; it never rewrites raw content/frontmatter. raw/assets/** is a flexible stable pool: use explicit embeds such as ![[raw/assets/example/diagram.png]], and do not move referenced assets as a side effect of archive or dedup.

skillwiki mcp / skillwiki-mcp is an optional stdio MCP server over deterministic CLI functions. It is not auto-started by the plugin. Mutations stay on the CLI; compile claim/publish/review writes are interactive CLI only.

Read-only tools include query, lint summary, doctor, graph build, project index, stale, config get, sources pending, compile status, and reviews.

Example client config:

{
  "mcpServers": {
    "skillwiki": {
      "command": "skillwiki",
      "args": ["mcp"]
    }
  }
}

npm install
npm run materialize:plugins:check
npm run test:plugin-metadata
npm run -w skillwiki build
npm test
npm run typecheck

Local CLI tarball (for scp / offline install) goes to a gitignored folder — never next to packages/cli/package.json:

npm run pack:cli                 # build + pack → artifacts/npm/skillwiki-<ver>.tgz
npm run pack:cli -- --no-build   # pack only
npm run pack:cli -- --json       # machine-readable path + sha256

Requires Node ≥ 20.

packages/mcp-server is a Streamable HTTP MCP daemon: the only agent writer to the SkillWiki vault. It holds a local plain working directory, serializes Tier-1 writes (wiki_capture, wiki_log_append), and fail-closes on S3 put errors. GitHub backup stays a sibling wiki-snapshot unit — never inside this process.

Production runs as native systemd on sg01 (wiki.karldigi.dev/mcp). Sibling systemd units on that host provide the GitHub snapshotter, FUSE refresh, agent memory research, and session-brief publication, grouped under the skillwiki-backend.target systemd family target; those responsibilities stay outside the MCP daemon.

docker-compose.coolify.yml is an optional later deployment path for the MCP daemon only, parked for cloud01 pending a short deployment grill. It does not include the snapshotter, FUSE, research, or session-brief units, and it is not a plan to Dockerize sg01 or macos-dev. docker-compose.coolify-bundled.yml remains a fresh-install/CI smoke template (MCP + hardened SeaweedFS), not the production fleet shape. The operator-only fleet.yaml intent that retires the sg02 Git satellite is recorded in projects/llm-wiki/work/2026-09-17-sg02-satellite-retire/fleet-satellite-off.md in the SkillWiki vault; the YAML itself is outside the HTTP MCP write allowlist.

Clients use type: http with Authorization: Bearer ${SKILLWIKI_MCP_TOKEN}. The server stores sha256(token) → host_id in a token map (hashes only). Token mint is a host operation at first deploy, not this repo — see projects/llm-wiki/work/2026-09-12-centralized-wiki-http-mcp/plan.md §5.

The SkillWiki Grok plugin ships mcp.json / .mcp.json pointing at https://wiki.karldigi.dev/mcp. Captures use MCP wiki_capture / wiki_log_append (skill skillwiki-mcp); do not write local raw/transcripts/ for those captures.

1. Mint a bearer on sg01 (token_hash → host_id in the daemon token map). Never commit the raw token.
2. export SKILLWIKI_MCP_TOKEN="<token>" in the Grok process environment. Optional: SKILLWIKI_MCP_URL to override the production URL.
3. grok plugin update skillwiki
4. Start a new session (SessionStart cannot inject the parent MCP env).
5. grok mcp doctor skillwiki

Cursor / Grok Bot: the Cursor-native package (.cursor-plugin) requires SKILLWIKI_MCP_TOKEN and pins https://wiki.karldigi.dev/mcp (absolute URL, no ${VAR:-default}). Open Plugins → Configure for skillwiki and enter the bearer — the same field grok-search uses for GROK_SEARCH_MCP_TOKEN. Grok Bot does not read ~/.cursor/mcp.json or the Mac process environment. Start a new Agent chat after Configure. Do not rempin unless the llm-wiki gitRef is stale.

Cursor headless wrappers may copy cursor-cli-mcp.example.json; it is not a marketplace pin and is not auto-installed. Fail closed if the token is missing. Never put the bearer in plugin files or the wiki.

The archive-only canonical specification lives under the active SkillWiki vault at {WIKI_PATH}/projects/llm-wiki/history/specs/2026-05-02-llm-wiki-skill-design.md (revised 2026-05-03). Resolve {WIKI_PATH} with skillwiki path.