@outsidestudio/agent-kit 0.2.1 → 0.2.3

package/README.md

@@ -3,16 +3,16 @@
 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.
 
 That command:
 
@@ -20,15 +20,16 @@ That command:
 2. Asks once for any secrets the profile needs (API keys, model endpoint) and stores them in `~/.config/outside-agent-kit/env` (chmod 600), loaded from `~/.zshrc` / `~/.bashrc`.
 3. Fetches the **latest** version of every skill and plugin. Nothing is pinned.
 4. Writes each tool's config, keeping anything the developer added themselves.
-5. Installing **only registry items** (no profile) is additive: it adds/replaces those items and keeps the rest of your install. Installing a profile reconciles the full set.
+5. **Installs are additive**: `agent-kit <target>` writes the named profiles/items and never removes anything else you already have — so `agent-kit product-backend` after `agent-kit product-backend web-frontend` just refreshes backend and leaves the web skills in place. To drop something, use `agent-kit remove <target>`; to rebuild configs to exactly your saved set, use `agent-kit update`.
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `agent-kit <profile...>` | Install one or more profiles |
-| `agent-kit outside/llm` | Add/refresh a single registry item without touching the rest of the install (see `agent-kit list`) |
-| `agent-kit update` | Re-install the current targets with the latest of everything |
+| `agent-kit add <profile...>` | Add/refresh one or more profiles (additive — keeps the rest). Bare `agent-kit <profile...>` and `install` are shorthands |
+| `agent-kit add outside/llm` | Add/refresh a single registry item on top of what you have (see `agent-kit list`) |
+| `agent-kit remove <target...>` | Remove installed profiles/items; everything else is reconciled to stay |
+| `agent-kit update` | Re-fetch your saved targets and reconcile configs to exactly them (prunes leftovers) |
 | `agent-kit doctor` | Check tools, secrets, model endpoint, MCP servers, skills |
 | `agent-kit secrets` | Enter missing secrets |
 | `agent-kit list` | Show profiles and registry items |
@@ -44,6 +45,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)
 ```
@@ -54,21 +56,25 @@ src/adapters/        one adapter per tool (opencode.ts, omp.ts)
 {
   "description": "Product backend developers",
   "extends": ["shared"],
-  "include": ["context-mode", "outside/backend-skills"]
+  "include": ["context-mode", "outside/product-backend-skills"]
 }
 ```
 
-`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 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
@@ -111,13 +117,13 @@ 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).
 
 ## 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`.
@@ -126,15 +132,16 @@ Model metadata is endpoint-specific — the same model id behind a different gat
 
 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`.
+- **Private npm registry** (GitHub Packages, Verdaccio): `npm publish`, then devs run `bunx @outsidestudio/agent-kit add <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.
+**Auto-update.** bunx reuses its cached 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 — bare commands stay current, no `@latest` needed. Set `AGENT_KIT_NO_UPDATE_CHECK=1` to opt out. Copies older than 0.2.3 cannot self-update: if a new command errors (e.g. `Unknown target "add"`), run `bunx @outsidestudio/agent-kit@latest update` once; from then on the bare form updates itself.
 
 ## 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`).
+- **Document skills.** Anthropic's docx/pdf/pptx/xlsx skills shell out to `python3` (and LibreOffice/pandoc for some conversions). `agent-kit doctor` warns when `python3` is missing; install the rest only if you use those flows.
 - **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.

package/package.json

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

package/profiles/product-backend.json

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

package/profiles/shared.json

@@ -1 +1 @@
-{"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","anthropic/document-skills"]}

package/profiles/web-frontend.json

@@ -1 +1 @@
-{"description":"Web / frontend developers","extends":["shared"],"include":["context-mode","outside/web-skills"]}
+{"description":"Web / frontend developers","extends":["shared"],"include":["context-mode","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/src/cli.ts

@@ -1,15 +1,18 @@
 #!/usr/bin/env bun
+import { join } from "node:path";
 import { doctor } from "./commands/doctor";
-import { install, secrets, update } from "./commands/install";
+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
 
 ${color.bold("Usage")}
-  agent-kit <target...>            Install profiles and/or single registry items (same as: agent-kit install <target...>)
-  agent-kit update                 Re-install the current targets with the latest of everything
+  agent-kit add <target...>        Add/refresh profiles and/or single registry items; leaves everything else installed untouched (shorthand: agent-kit <target...>, also: agent-kit install)
+  agent-kit remove <target...>     Remove installed profiles/items; the rest is kept and reconciled
+  agent-kit update                 Re-fetch the saved targets and reconcile configs to exactly them
   agent-kit doctor                 Check tools, secrets, model endpoint and MCP servers
   agent-kit secrets                Enter any missing secrets
   agent-kit list                   Show profiles and registry items
@@ -23,9 +26,10 @@ ${color.bold("Options")}
   --no-shell            Don't add the secrets loader to ~/.zshrc / ~/.bashrc
 
 ${color.bold("Examples")}
-  bunx @outsidestudio/agent-kit product-backend
-  bunx @outsidestudio/agent-kit product-backend web-frontend
-  bunx @outsidestudio/agent-kit outside/llm      # just the model provider (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
 `;
 
@@ -45,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,
@@ -57,9 +95,13 @@ async function main() {
   if (!cmd || flags.help) return console.log(HELP);
 
   switch (cmd) {
+    case "add":
     case "install":
       if (!rest.length) throw new Error("What to install? Run: agent-kit list");
       return install(rest, opts);
+    case "remove":
+      if (!rest.length) throw new Error("What to remove? Run: agent-kit list");
+      return remove(rest, opts);
     case "update":
       return update(opts);
     case "doctor":

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/install.ts

@@ -11,6 +11,8 @@ export interface InstallOptions {
   tools?: string[];
   yes?: boolean;
   shell?: boolean;
+  /** Rebuild configs from exactly these targets, purging managed leftovers. */
+  reconcile?: boolean;
 }
 
 function pickTools(requested?: string[]): string[] {
@@ -46,10 +48,14 @@ function mergeToolState(prev: ToolState | undefined, next: ToolState): ToolState
 export async function install(targets: string[], opts: InstallOptions = {}) {
   const tools = pickTools(opts.tools);
   const { profiles, items: direct } = await resolveTargets(targets);
-  // Targeting only registry items adds/replaces those items; it never purges
-  // the rest of the install. A profile target still reconciles the full set.
-  const additive = profiles.length === 0 && direct.length > 0;
-  log.head(`Setting up ${targets.map((t) => `"${t}"`).join(" + ")} for ${tools.join(" + ")}`);
+  // Installs are additive: they add/refresh the named targets and never touch
+  // what else is installed. Only --reconcile runs (update, remove) purge.
+  const additive = opts.reconcile !== true;
+  log.head(
+    targets.length
+      ? `Setting up ${targets.map((t) => `"${t}"`).join(" + ")} for ${tools.join(" + ")}`
+      : `Removing everything the kit manages for ${tools.join(" + ")}`,
+  );
 
   const ids = [...new Set([...(await resolveProfiles(profiles)), ...direct])];
   const items = await Promise.all(ids.map(loadItem));
@@ -101,7 +107,10 @@ export async function install(targets: string[], opts: InstallOptions = {}) {
     managed: { ...(prev?.managed ?? {}) },
     installed: additive ? { ...(prev?.installed ?? {}), ...plan.fetched } : plan.fetched,
   };
-  if (additive && prev) log.step(`Additive: keeping ${prev.profiles.join(", ") || "existing items"}; replacing ${direct.join(", ")}`);
+  if (additive && prev)
+    log.step(
+      `Additive: keeping ${[...prev.profiles, ...prev.items].join(", ") || "nothing"}; refreshing ${targets.join(", ")}`,
+    );
   for (const t of tools) {
     const next = await adapters[t].apply(plan, prev?.managed[t]);
     state.managed[t] = additive ? mergeToolState(prev?.managed[t], next) : next;
@@ -124,7 +133,31 @@ export async function install(targets: string[], opts: InstallOptions = {}) {
 export async function update(opts: InstallOptions = {}) {
   const prev = await readState();
   if (!prev) throw new Error("Nothing installed yet. Run: agent-kit <profile>");
-  await install([...prev.profiles, ...prev.items], { ...opts, tools: opts.tools ?? prev.tools });
+  // Reconcile: the saved targets are the whole truth, so leftovers from
+  // changed profile definitions get purged.
+  await install([...prev.profiles, ...prev.items], {
+    ...opts,
+    tools: opts.tools ?? prev.tools,
+    reconcile: true,
+  });
+}
+
+/** Drop targets from the saved install; everything else is reconciled to stay. */
+export async function remove(targets: string[], opts: InstallOptions = {}) {
+  const prev = await readState();
+  if (!prev) throw new Error("Nothing installed yet. Run: agent-kit <profile>");
+  await resolveTargets(targets); // reject unknown names
+  const saved = [...prev.profiles, ...prev.items];
+  const gone = targets.filter((t) => saved.includes(t));
+  if (!gone.length)
+    throw new Error(
+      `None of ${targets.join(", ")} is installed. Installed: ${saved.join(", ") || "nothing"}. ` +
+        `Items pulled in by a profile can only be removed by removing that profile.`,
+    );
+  const rest = saved.filter((t) => !gone.includes(t));
+  log.head(`Removing ${gone.join(", ")}`);
+  if (rest.length) log.info(`Keeping: ${rest.join(", ")}`);
+  await install(rest, { ...opts, tools: opts.tools ?? prev.tools, reconcile: true });
 }
 
 /** Re-prompt for every secret the current install needs. */

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 {
@@ -95,8 +97,10 @@ export interface Plan {
   /** What was fetched, for the install log. */
   fetched: Record<string, string>;
   /**
-   * Single registry-item install: replace only the items in this plan and
-   * keep everything else the kit managed before (no purge of skills/MCP/etc).
+   * Additive run (the default for installs): write exactly what this plan
+   * names and keep every other entry the kit managed before — no purge of
+   * skills/MCP/plugins/providers. Reconcile runs (update, remove) leave this
+   * false and rebuild the config from only this plan.
    */
   additive?: boolean;
 }

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" }
-}