@outsidestudio/agent-kit 0.2.2 → 0.3.0

package/README.md

@@ -3,16 +3,18 @@
 One command to set up a developer's AI coding tools: skills, MCP servers and our self-hosted model provider, for **OpenCode** and **OMP (oh-my-pi)**.
 
 ```bash
-bunx @outsidestudio/agent-kit product-backend
+bunx @outsidestudio/agent-kit add product-backend
 ```
 
 Need more than one profile (e.g. full-stack)? Pass them together; their items are merged:
 
 ```bash
-bunx @outsidestudio/agent-kit product-backend web-frontend
+bunx @outsidestudio/agent-kit add product-backend web-frontend
 ```
 
-Run them in one command. Running them separately does not stack: each install replaces what the previous one set up.
+Installs **stack**: every run is additive, so installing one profile never removes another profile's entries — run them in any order, as often as you like. `agent-kit remove <target>` takes something out again.
+
+**Auto-update.** bunx caches its copy of the kit. From **0.2.3** a cached copy checks npm's `latest` on startup and transparently reruns the new version with your arguments, so bare commands stay current (`AGENT_KIT_NO_UPDATE_CHECK=1` to opt out). Copies older than 0.2.3 cannot self-update: run `bunx @outsidestudio/agent-kit@latest update` once; the bare form updates itself from then on.
 
 That command:
 
@@ -45,6 +47,7 @@ Options: `--tool opencode,omp`, `-y/--yes` (no prompts), `--no-shell` (don't edi
 profiles/            one file per department; "extends" + "include" registry ids
 registry/            one file per item; id = path under registry/ without .json
   outside/           our own items (registry/outside/llm.json → id "outside/llm")
+  anthropic/         Anthropic's skills (registry/anthropic/document-skills.json)
 skills/<group>/      our custom skills (SKILL.md folders)
 src/adapters/        one adapter per tool (opencode.ts, omp.ts)
 ```
@@ -55,21 +58,25 @@ src/adapters/        one adapter per tool (opencode.ts, omp.ts)
 {
   "description": "Product backend developers",
   "extends": ["shared"],
-  "include": ["context-mode", "outside/backend-skills"]
+  "include": ["outside/product-backend-skills", "security-audit"]
 }
 ```
 
-`shared` is the base every department extends: the LLM provider, company skills, Superpowers and Context7.
+`shared` is the base every department extends: the LLM provider, company skills, Superpowers, Context7, context-mode and Anthropic's document skills (docx, pdf, pptx, xlsx).
 
 ### Registry item kinds
 
-**`skills`**: a folder of skills, from this repo or any git repo (default branch, latest commit).
+**`skills`**: a folder of skills, from this repo or any git repo (default branch, latest commit). `only` picks specific skill folders from the source; `requires` lists executables the skills expect on PATH (doctor warns when one is missing).
 
 ```json
-{ "kind": "skills", "source": { "type": "local", "path": "skills/backend" } }
+{ "kind": "skills", "source": { "type": "local", "path": "skills/product-backend" } }
 { "kind": "skills", "source": { "type": "git", "repo": "https://github.com/org/repo.git", "path": "skills" }, "only": ["skill-a"] }
+{ "kind": "skills", "source": { "type": "git", "repo": "https://github.com/anthropics/skills.git", "path": "skills" },
+  "only": ["docx", "pdf", "pptx", "xlsx"], "requires": ["python3"] }
 ```
 
+`anthropic/document-skills` uses the last shape: each run clones Anthropic's public skills repo and copies only the four document skills into the tools' skills dirs. Nothing from that repo is bundled in the npm package — worth knowing because those four carry Anthropic's source-available license (the repo's other skills are Apache 2.0).
+
 **`mcp`**: a local (stdio) or remote (HTTP) MCP server. Write secrets as `${VAR}`; each adapter converts them to the tool's syntax (`{env:VAR}` for OpenCode, `${VAR}` for OMP).
 
 ```json
@@ -87,16 +94,16 @@ src/adapters/        one adapter per tool (opencode.ts, omp.ts)
   "fallback": { "type": "git", "repo": "https://github.com/obra/superpowers.git", "path": "skills" } }
 ```
 
-**`provider`**: an OpenAI-compatible model endpoint (our vast.ai models). The provider id in each tool is the registry id with `/` replaced by `-`, so the model id `nvidia/Qwen2.8-Flash-Next-NVFP4` in `outside/llm` appears as `outside-llm/nvidia/Qwen2.8-Flash-Next-NVFP4`.
+**`provider`**: an OpenAI-compatible model endpoint (our vast.ai models). The provider id in each tool is the registry id with `/` replaced by `-`, so the model id `nvidia/Qwen3.8-Flash-Next-NVFP4` in `outside/llm` appears as `outside-llm/nvidia/Qwen3.8-Flash-Next-NVFP4`.
 
 ```json
 { "kind": "provider", "name": "Outside LLM",
   "baseURL": "${OUTSIDE_LLM_BASE_URL}", "apiKey": "${OUTSIDE_LLM_API_KEY}",
-  "models": { "nvidia/Qwen2.8-Flash-Next-NVFP4": {
-    "name": "Qwen2.8 Flash Next (NVFP4)", "contextWindow": 131072, "maxTokens": 32768,
+  "models": { "nvidia/Qwen3.8-Flash-Next-NVFP4": {
+    "name": "Qwen3.8 Flash Next (NVFP4)", "contextWindow": 131072, "maxTokens": 32768,
     "reasoning": true, "input": ["text", "image"],
     "thinking": { "mode": "effort", "efforts": ["low", "medium", "high"], "defaultLevel": "medium" } } },
-  "defaultModel": "nvidia/Qwen2.8-Flash-Next-NVFP4" }
+  "defaultModel": "nvidia/Qwen3.8-Flash-Next-NVFP4" }
 ```
 
 Model metadata is endpoint-specific — the same model id behind a different gateway has different limits — so each provider item carries the numbers for the server it points at. The kit maps `contextWindow`/`maxTokens` to OMP's `contextWindow`/`maxTokens` and OpenCode's `limit.context`/`limit.output`, `input` to OpenCode `modalities.input`, and passes `thinking` through to OMP.
@@ -112,30 +119,16 @@ Model metadata is endpoint-specific — the same model id behind a different gat
 
 `OPENCODE_CONFIG_DIR` and `OMP_PROFILE` are respected. The first time a file is changed, a backup is saved next to it as `*.agent-kit.bak`.
 
-**What the kit owns.** It records what it installed in `~/.config/outside-agent-kit/state.json`. On `update` or a profile switch it replaces only those entries. Your own MCP servers, plugins and skills are never touched; if one has the same name as a kit item, yours wins and the kit warns.
+**What the kit owns.** It records what it installed in `~/.config/outside-agent-kit/state.json`. A plain install only ever adds; `remove` and `update` rebuild configs from the saved set, deleting only those recorded entries. Your own MCP servers, plugins and skills are never touched; if one has the same name as a kit item, yours wins and the kit warns.
 
 **JSONC.** If `opencode.json` has comments, they are removed when the kit rewrites it (the backup keeps them).
 
+**Caveats.** OMP also reads other tools' configs (`opencode.json`, `.claude`, …): same-named MCP servers dedupe (OMP's own `mcp.json` wins), but a skill installed in several places may appear twice. OpenCode caches git plugins — if an update doesn't show up, clear OpenCode's plugin cache and restart it.
+
 ## Adding things
 
-- **Custom skill**: `agent-kit new skill backend/rate-limiting`, write the SKILL.md, open a PR. Everyone gets it on their next `update`.
+- **Custom skill**: `agent-kit new skill product-backend/rate-limiting`, write the SKILL.md, open a PR. Everyone gets it on their next `update`.
 - **New department**: add `profiles/<dept>.json` and `skills/<dept>/` (`new skill <dept>/<name>` creates the registry entry for you).
 - **Third-party item**: add a `registry/<id>.json` (put your own under `registry/outside/`), then add the id to profiles.
 - **New tool** (Codex, Cursor…): write `src/adapters/<tool>.ts` implementing `Adapter` and list it in `src/adapters/index.ts`.
-
-## Publishing
-
-Pick one:
-
-- **Private npm registry** (GitHub Packages, Verdaccio): `npm publish`, then devs run `bunx @outsidestudio/agent-kit <profile>`. Point the `@outsidestudio` scope at your registry in `~/.npmrc` or `bunfig.toml`.
-- **Straight from GitHub**, no registry: `bunx github:madebyoutside/agent-kit <profile>`.
-
-With "always latest", `bunx` may reuse a cached copy of the kit itself. Use `bunx @outsidestudio/agent-kit@latest update` to be sure you have the newest registry.
-
-## Things to verify for your setup
-
-- **Base URL.** Put a stable gateway (LiteLLM, Cloudflare Tunnel) in front of vast.ai so `OUTSIDE_LLM_BASE_URL` doesn't change when instances are recreated.
-- **Model list.** Replace `qwen3-coder` in `registry/outside/llm.json` with the model ids your server actually serves (`curl $OUTSIDE_LLM_BASE_URL/models`).
-- **OMP plugins.** Superpowers has no `omp` entry yet, so OMP gets its skills via the fallback. Add `"omp": { "plugin": "..." }` if `omp plugin install` supports it.
-- **OpenCode plugin cache.** OpenCode caches git plugins. If an update doesn't show up, clear OpenCode's plugin cache and restart it.
-- **Duplicates in OMP.** OMP also reads other tools' configs (`opencode.json`, `.claude`, …). Same-named MCP servers dedupe (OMP's own `mcp.json` wins), but a skill installed in several places may appear twice.
+- **Release**: bump `version` in `package.json`, commit, `npm publish --access public`, push. `latest` propagates in ~1-2 min; machines on 0.2.3+ pick it up on their next bare `bunx` run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outsidestudio/agent-kit",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "One-command setup of skills, MCP servers and model providers for OpenCode and OMP",
   "type": "module",
   "bin": {

package/profiles/pm.json

@@ -1 +1,9 @@
-{"description":"Product managers","extends":["shared"],"include":["outside/pm-skills"]}
+{
+  "description": "Product managers",
+  "extends": [
+    "shared"
+  ],
+  "include": [
+    "outside/pm-skills"
+  ]
+}

package/profiles/product-backend.json

@@ -1 +1,10 @@
-{"description":"Product backend developers","extends":["shared"],"include":["context-mode","outside/backend-skills"]}
+{
+  "description": "Product backend developers",
+  "extends": [
+    "shared"
+  ],
+  "include": [
+    "outside/product-backend-skills",
+    "security-audit"
+  ]
+}

package/profiles/shared.json

@@ -1 +1,11 @@
-{"description":"Base setup every profile extends","include":["outside/llm","outside/shared-skills","superpowers","context7"]}
+{
+  "description": "Base setup every profile extends",
+  "include": [
+    "outside/llm",
+    "outside/shared-skills",
+    "superpowers",
+    "context7",
+    "context-mode",
+    "anthropic/document-skills"
+  ]
+}

package/profiles/web-frontend.json

@@ -1 +1,9 @@
-{"description":"Web / frontend developers","extends":["shared"],"include":["context-mode","outside/web-skills"]}
+{
+  "description": "Web / frontend developers",
+  "extends": [
+    "shared"
+  ],
+  "include": [
+    "outside/web-frontend-skills"
+  ]
+}

package/registry/anthropic/document-skills.json

@@ -0,0 +1,7 @@
+{
+  "kind": "skills",
+  "description": "Anthropic's document skills: docx, pdf, pptx, xlsx (cloned from Anthropic's repo at install time; source-available license, never bundled in the package)",
+  "source": { "type": "git", "repo": "https://github.com/anthropics/skills.git", "path": "skills" },
+  "only": ["docx", "pdf", "pptx", "xlsx"],
+  "requires": ["python3"]
+}

package/registry/outside/product-backend-skills.json

@@ -0,0 +1,5 @@
+{
+  "kind": "skills",
+  "description": "Product backend team custom skills (lives in this repo)",
+  "source": { "type": "local", "path": "skills/product-backend" }
+}

package/registry/outside/{web-skills.json → web-frontend-skills.json}

@@ -1,5 +1,5 @@
 {
   "kind": "skills",
-  "description": "Web team custom skills (lives in this repo)",
+  "description": "Web / frontend team custom skills (lives in this repo)",
   "source": { "type": "local", "path": "skills/web-frontend" }
 }

package/registry/security-audit.json

@@ -0,0 +1,7 @@
+{
+  "kind": "skills",
+  "description": "Cloudflare's security-audit skill: security guidance, focused reviews and full multi-agent codebase audits",
+  "source": { "type": "git", "repo": "https://github.com/cloudflare/security-audit-skill.git", "path": "skills" },
+  "only": ["security-audit"],
+  "requires": ["node"]
+}

package/src/cli.ts

@@ -1,9 +1,11 @@
 #!/usr/bin/env bun
+import { join } from "node:path";
 import { doctor } from "./commands/doctor";
 import { install, remove, secrets, update } from "./commands/install";
 import { list } from "./commands/list";
 import { newMcp, newSkill } from "./commands/new";
 import { color, log } from "./log";
+import { KIT_ROOT } from "./paths";
 
 const HELP = `${color.bold("agent-kit")}: set up skills, MCP servers and models for OpenCode and OMP
 
@@ -24,9 +26,9 @@ ${color.bold("Options")}
   --no-shell            Don't add the secrets loader to ~/.zshrc / ~/.bashrc
 
 ${color.bold("Examples")}
-  bunx @outsidestudio/agent-kit add product-backend   # bare form works too: bunx @outsidestudio/agent-kit product-backend
-  bunx @outsidestudio/agent-kit product-backend web-frontend
-  bunx @outsidestudio/agent-kit outside/llm      # just the model provider, on top of what's installed (see: agent-kit list)
+  bunx @outsidestudio/agent-kit add product-backend   # also: install, or just the bare profile name
+  bunx @outsidestudio/agent-kit add product-backend web-frontend
+  bunx @outsidestudio/agent-kit add outside/llm      # just the model provider, on top of what's installed (see: agent-kit list)
   bunx @outsidestudio/agent-kit remove web-frontend   # drop web skills, keep backend + shared
   bunx @outsidestudio/agent-kit update
 `;
@@ -47,8 +49,42 @@ function parse(argv: string[]) {
   return { args, flags };
 }
 
+
+/**
+ * bunx can silently reuse its cached copy, so an installed copy may lag the
+ * published one. A cached copy (only: its path lives in bun's install cache)
+ * compares itself against the registry's `latest` and re-execs the new
+ * version with the same argv. Dev/repo/global copies never self-update.
+ */
+async function selfUpdate(argv: string[]) {
+  if (process.env.AGENT_KIT_NO_UPDATE_CHECK) return;
+  if (!import.meta.dir.includes(".bun/install/cache")) return;
+  try {
+    const res = await fetch("https://registry.npmjs.org/@outsidestudio%2Fagent-kit", {
+      headers: { Accept: "application/vnd.npm.install-v1+json" },
+      signal: AbortSignal.timeout(2500),
+    });
+    if (!res.ok) return;
+    const latest = ((await res.json()) as { "dist-tags"?: { latest?: string } })["dist-tags"]?.latest;
+    const here = ((await Bun.file(join(KIT_ROOT, "package.json")).json()) as { version: string }).version;
+    if (!latest || latest === here) return;
+    log.info(`agent-kit ${here} is stale, rerunning with ${latest}…`);
+    const proc = Bun.spawn(["bunx", `@outsidestudio/agent-kit@${latest}`, ...argv], {
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+      env: { ...process.env, AGENT_KIT_NO_UPDATE_CHECK: "1" },
+    });
+    process.exit(await proc.exited);
+  } catch {
+    // offline, slow registry, or no bunx on PATH: run the copy we have
+  }
+}
+
 async function main() {
-  const { args, flags } = parse(Bun.argv.slice(2));
+  const argv = Bun.argv.slice(2);
+  const { args, flags } = parse(argv);
+  await selfUpdate(argv);
   const [cmd, ...rest] = args;
   const opts = {
     tools: typeof flags.tool === "string" ? flags.tool.split(",").map((s) => s.trim()).filter(Boolean) : undefined,

package/src/commands/doctor.ts

@@ -6,7 +6,7 @@ import { paths } from "../paths";
 import { loadItem, resolveProfiles, secretsOf } from "../registry";
 import { readEnvFile } from "../secrets";
 import { readState } from "../state";
-import type { McpItem, ProviderItem } from "../types";
+import type { McpItem, ProviderItem, SkillsItem } from "../types";
 
 const expand = (v: string) => v.replace(/\$\{([A-Z0-9_]+)\}/g, (_, k) => process.env[k] ?? "");
 
@@ -55,6 +55,16 @@ export async function doctor(): Promise<number> {
   const ids = [...new Set([...(await resolveProfiles(state.profiles)), ...(state.items ?? [])])];
   const items = await Promise.all(ids.map(loadItem));
 
+  const skillDeps = items.filter((i): i is SkillsItem & { id: string } => i.kind === "skills" && !!i.requires?.length);
+  if (skillDeps.length) {
+    log.head("Skill dependencies");
+    for (const item of skillDeps) {
+      const missing = item.requires!.filter((b) => !Bun.which(b));
+      if (missing.length) log.warn(`${item.id}: ${missing.join(", ")} not on PATH; these skills may not work fully`);
+      else log.ok(`${item.id}: needs ${item.requires!.join(", ")} — found`);
+    }
+  }
+
   log.head("Secrets");
   const names = [...new Set(items.flatMap(secretsOf))];
   if (!names.length) log.ok("none needed");

package/src/commands/new.ts

@@ -17,7 +17,7 @@ export async function newSkill(spec: string) {
   const root = kitRepo();
   const [group, name] = spec.includes("/") ? spec.split("/") : ["shared", spec];
   if (!validName(group) || !validName(name)) {
-    throw new Error("Use lowercase letters, digits and dashes: agent-kit new skill backend/my-skill");
+    throw new Error("Use lowercase letters, digits and dashes: agent-kit new skill product-backend/my-skill");
   }
   const dir = join(root, "skills", group, name);
   if (existsSync(dir)) throw new Error(`${dir} already exists`);

package/src/types.ts

@@ -8,6 +8,8 @@ export interface SkillsItem {
   source: SkillSource;
   /** Optional allowlist of skill folder names from the source. */
   only?: string[];
+  /** Executables that should be on PATH for these skills to work fully (warned about by doctor). */
+  requires?: string[];
 }
 
 export interface McpItem {

package/registry/outside/backend-skills.json

@@ -1,5 +0,0 @@
-{
-  "kind": "skills",
-  "description": "Backend team custom skills (lives in this repo)",
-  "source": { "type": "local", "path": "skills/backend" }
-}