@ahood/cli 0.9.0 → 0.10.0

package/README.md

@@ -28,8 +28,10 @@ Installed alice/pdf-tools@1.4.0 to .claude/skills/alice@pdf-tools
 - [Why ahood](#why-ahood)
 - [Configuration](#configuration)
 - [Usage examples](#usage-examples)
+- [Kinds: skills, agents, and MCP servers](#kinds-skills-agents-and-mcp-servers)
 - [Commands](#commands)
 - [Exit codes](#exit-codes)
+- [Compatibility](#compatibility)
 - [Shell completion](#shell-completion)
 - [Using ahood from an AI agent](#using-ahood-from-an-ai-agent)
 - [Development](#development)
@@ -187,6 +189,35 @@ Shared alice/pdf-tools with design-team.
 Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private visibility, it just makes it visible to everyone in `design-team` too. On the other side, whoever received the link runs `ahood group join <the link>` to join.
 </details>
 
+## Kinds: skills, agents, and MCP servers
+
+The registry holds three kinds of artifact this CLI works with, each with its own command group. All three take the same verbs (`search`, `list`, `view`/`show`, `read`, `versions`, `diff`, `add`, `update`, `outdated`, `remove`, `edit`, `unpublish`, `star`, `unstar`, `share`, `unshare`, `init`, `publish`), run by the same code:
+
+| Kind | Root file | `add` installs to | Group |
+| --- | --- | --- | --- |
+| skill | `SKILL.md` | `.claude/skills/<owner>@<skill>/` | `ahood skill <verb>` |
+| agent | `AGENT.md` | `.claude/agents/<owner>@<agent>.md` | `ahood agent <verb>` |
+| mcp | `server.json` | an entry merged into `.mcp.json` | `ahood mcp <verb>` |
+
+```
+$ ahood agent search review
+$ ahood agent init code-reviewer        # ./code-reviewer/AGENT.md
+$ ahood agent publish alice/code-reviewer@1.0.0 --path code-reviewer --name "Code Reviewer"
+$ ahood mcp init github-server          # ./github-server/server.json, a safe placeholder starter
+$ ahood mcp add alice/github-server
+$ ahood agent add alice/pdf-tools
+alice/pdf-tools is a skill, not an agent -- refusing to install it. Use `ahood skill add alice/pdf-tools` instead.
+```
+
+- **`ahood agent` and `ahood mcp` are strict.** A target of another kind is refused -- exit code `2`, naming the kind it found -- before anything is downloaded, prompted for, written, or sent. That covers `add`, `update`, `remove`, `edit`, `unpublish`, `share`/`unshare`, `star`/`unstar`, and `publish` (an existing entry of another kind is refused before anything is packed or uploaded); the read-only verbs refuse too, rather than show the wrong kind. `search` asks the registry for that kind only, `list` keeps only that kind of your own entries, and `update`/`outdated` with no argument consider only installed pins of that kind. `agent publish`/`mcp publish` imply their kind and reject a contradictory `--kind`.
+- **Missing or unexpected kind metadata is refused, never guessed.** If the registry's answer carries no kind (or one this CLI doesn't handle), a kind-scoped command stops with exit `1` and points at the legacy form. `remove` reads the kind from the project's own files (the skill directory, the agent file, or the mcp fingerprint in the lockfile) and asks the registry only when those can't tell; if neither can, nothing is removed.
+- **`ahood skill` is legacy and cross-kind in this release.** `ahood skill search` and `ahood skill list` include every kind, and `ahood skill add`/`update`/`remove`/... act on whatever kind the target is, exactly as before -- including `--json` output and exit codes -- so existing scripts keep working. Add `--kind skill|agent|mcp` to any `ahood skill` verb (except `publish`, whose `--kind` keeps its original meaning) to scope it, or `--kind all` to spell out the cross-kind behavior.
+- **Not in scope: `doc`.** The registry also has a `doc` kind (documentation pages); this CLI has no `ahood doc` group. Kind dispatch is table-driven (`src/kind-info.ts`), so adding one is an entry there plus its help and `init` template.
+
+**Migration plan for a strict `ahood skill`.** A future major version will make `ahood skill <verb>` skills-only by default, matching `agent` and `mcp`. Until then: (1) this release adds the strict groups and `--kind`, and labels `ahood skill` as legacy in `--help`; (2) a following minor release prints a stderr deprecation note when an `ahood skill` command actually touches a non-skill entry (stdout and `--json` unchanged); (3) the major release flips the default, keeping `ahood skill <verb> --kind all` as the explicit cross-kind escape hatch. Scripts that want today's behavior forever can pass `--kind all` now.
+
+**`ahood mcp` has two meanings.** With no arguments, or as `ahood mcp serve` (the preferred spelling), it starts this CLI's local, read-only MCP server over stdio -- unchanged, so existing MCP host configurations keep working with no edits. With a registry verb it manages MCP server manifests. Anything else (`ahood mcp srve`, `ahood mcp --flag`) fails with usage and a suggestion instead of starting a server. Neither is the hosted registry MCP endpoint at `https://ahood.vercel.app/api/mcp`.
+
 ## Commands
 
 <!-- Generated from src/help.ts's COMMANDS_HELP by scripts/sync-readme.mjs --
@@ -203,9 +234,9 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | `ahood whoami [--json]` | Reports whether your stored token still authenticates. |
 | `ahood token create <name>\|list [--json]\|revoke <id> [--yes]` | Manage personal API tokens. |
 | `ahood completion <bash\|zsh\|fish>` | Print a shell completion script for the command names. |
-| `ahood mcp` | Start an MCP server exposing read-only skill commands as tools over stdio. |
+| `ahood help useme` | Print the bundled ahood SKILL.md for an AI agent -- raw, offline, no login needed. |
 
-### Skill
+### Skill (legacy, cross-kind)
 
 | Command | What it does |
 | --- | --- |
@@ -228,6 +259,54 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | `ahood skill init [name]` | Scaffold a new skill folder with a minimal, valid SKILL.md. |
 | `ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--kind skill\|agent\|mcp] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]` | Publish a new version of a skill, agent, or mcp server manifest from a folder containing SKILL.md, AGENT.md, or server.json, creating the skill first if it doesn't already exist. |
 
+### Agent
+
+| Command | What it does |
+| --- | --- |
+| `ahood agent search <query> [--json] [--limit <n>]` | Search published agents. |
+| `ahood agent view\|show <owner>/<agent> [--json] [--web]` | Show a single agent's details without installing it (alias: ahood agent show). |
+| `ahood agent read <owner>/<agent> [--json]` | Print a published agent's AGENT.md, without installing it. |
+| `ahood agent versions <owner>/<agent> [--json]` | List a agent's published-version history. |
+| `ahood agent diff <owner>/<agent> <versionA> <versionB> [--json]` | Show what changed between two published versions of an agent. |
+| `ahood agent list [--json]` | List your own agents, public and private. |
+| `ahood agent add <owner>/<agent>[@version]` | Install an agent into .claude/agents/<owner>@<agent>.md, pinned in the lockfile. |
+| `ahood agent update [<owner>/<agent> ...] [--dry-run] [--json]` | Move agent pins forward to the latest version. |
+| `ahood agent outdated [<owner>/<agent> ...] [--json]` | Read-only staleness check for installed agents. |
+| `ahood agent remove <owner>/<agent> [--yes]` | Uninstall and unpin an agent (local only, prompts unless --yes is passed). |
+| `ahood agent edit <owner>/<agent> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]` | Update an agent you own, changing only the flags you pass. |
+| `ahood agent unpublish <owner>/<agent>[@version] [--yes]` | Delete an agent from the registry for every consumer, or yank one version (prompts unless --yes is passed). |
+| `ahood agent star <owner>/<agent>` | Star an agent. |
+| `ahood agent unstar <owner>/<agent>` | Remove your star from an agent. |
+| `ahood agent share <owner>/<agent> --group <group>` | Share an agent you own with a group, without changing its visibility. |
+| `ahood agent unshare <owner>/<agent> --group <group>` | Stop sharing an agent you own with a group. |
+| `ahood agent init [name]` | Scaffold a new agent folder with a minimal, valid AGENT.md. |
+| `ahood agent publish <owner>/<agent>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]` | Publish a new version of an agent from a folder containing AGENT.md, creating it first if it doesn't exist yet. |
+
+### MCP (local server and server manifests)
+
+| Command | What it does |
+| --- | --- |
+| `ahood mcp serve` | Start the local, read-only ahood MCP server over stdio (preferred spelling). |
+| `ahood mcp` | Same as `ahood mcp serve`, kept byte-for-byte so existing MCP host configs keep working. |
+| `ahood mcp search <query> [--json] [--limit <n>]` | Search published MCP server manifests. |
+| `ahood mcp view\|show <owner>/<server> [--json] [--web]` | Show a single MCP server manifest's details without installing it (alias: ahood mcp show). |
+| `ahood mcp read <owner>/<server> [--json]` | Print a published MCP server manifest's server.json, without installing it. |
+| `ahood mcp versions <owner>/<server> [--json]` | List a MCP server manifest's published-version history. |
+| `ahood mcp diff <owner>/<server> <versionA> <versionB> [--json]` | Show what changed between two published versions of an MCP server manifest. |
+| `ahood mcp list [--json]` | List your own MCP server manifests, public and private. |
+| `ahood mcp add <owner>/<server>[@version]` | Install an MCP server manifest into an entry in .mcp.json, pinned in the lockfile. |
+| `ahood mcp update [<owner>/<server> ...] [--dry-run] [--json]` | Move MCP server manifest pins forward to the latest version. |
+| `ahood mcp outdated [<owner>/<server> ...] [--json]` | Read-only staleness check for installed MCP server manifests. |
+| `ahood mcp remove <owner>/<server> [--yes]` | Uninstall and unpin an MCP server manifest (local only, prompts unless --yes is passed). |
+| `ahood mcp edit <owner>/<server> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]` | Update an MCP server manifest you own, changing only the flags you pass. |
+| `ahood mcp unpublish <owner>/<server>[@version] [--yes]` | Delete an MCP server manifest from the registry for every consumer, or yank one version (prompts unless --yes is passed). |
+| `ahood mcp star <owner>/<server>` | Star an MCP server manifest. |
+| `ahood mcp unstar <owner>/<server>` | Remove your star from an MCP server manifest. |
+| `ahood mcp share <owner>/<server> --group <group>` | Share an MCP server manifest you own with a group, without changing its visibility. |
+| `ahood mcp unshare <owner>/<server> --group <group>` | Stop sharing an MCP server manifest you own with a group. |
+| `ahood mcp init [name]` | Scaffold a new MCP server manifest folder with a minimal, valid server.json. |
+| `ahood mcp publish <owner>/<server>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]` | Publish a new version of an MCP server manifest from a folder containing server.json, creating it first if it doesn't exist yet. |
+
 ### Group
 
 | Command | What it does |
@@ -255,7 +334,7 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | `ahood snap tags <id> [tag ...] [--clear] [--json]` | Print a snap's tags, or replace them with the tags given. |
 <!-- COMMANDS_TABLE_END -->
 
-Run `ahood --help`, `ahood skill --help`, `ahood group --help`, `ahood snap --help`, or `ahood <command> --help` (also `ahood help <command>` / `ahood help skill <verb>` / `ahood help group <verb>` / `ahood help snap <verb>`) for the same reference — including per-command flags and examples — directly in your terminal. `ahood --version` prints the installed CLI version.
+Run `ahood --help`, `ahood skill --help`, `ahood agent --help`, `ahood mcp --help`, `ahood group --help`, `ahood snap --help`, or `ahood <command> --help` (also `ahood help <command>` / `ahood help <skill|agent|mcp|group|snap> <verb>`) for the same reference — including per-command flags and examples — directly in your terminal. `ahood --version` prints the installed CLI version.
 
 ## Exit codes
 
@@ -270,6 +349,12 @@ Stable across releases, safe to branch on in a script:
 | `5` | Not found |
 | `6` | Network/transport error, or an upstream server (5xx) error |
 
+## Compatibility
+
+Surfaces that are stable across releases on purpose, because something outside this codebase depends on their exact shape:
+
+- **`User-Agent` header.** Every request sends `User-Agent: @ahood/cli/<version>` (e.g. `@ahood/cli/0.9.0`), built in `src/http.ts` from this package's own `name` and `version` in `package.json`. This is deliberately a plain, stable, parseable string rather than an opaque one, because it is exactly what a WAF/firewall allowlist rule needs to scope a rate limit or block rule to browser page traffic without also catching the CLI. **Changing this header's shape (its format, delimiter, or what it's derived from) is a breaking change** for anyone who has written a rule against it, even though nothing in this CLI's own test suite would fail — treat it with the same care as the [exit codes](#exit-codes) below. If it ever needs to carry more than name/version (for example OS or Node version, to make a spoofed string easier to tell apart from a real one), that's a deliberate compatibility change too and belongs in this same section, documented to match exactly what the code sends.
+
 ## Shell completion
 
 ```
@@ -290,8 +375,9 @@ ahood completion fish > ~/.config/fish/completions/ahood.fish
 - **No interactive login required.** Set `AHOOD_TOKEN` once (a personal API token from `ahood token create <name>`) and every command works non-interactively.
 - **Structured output everywhere.** `--json` is available on every read command and on `publish`/`update`, so an agent never has to scrape human-formatted text.
 - **Predictable failure.** A stable, documented [exit code](#exit-codes) per failure class, and error messages that never leak raw upstream infrastructure details — safe to surface directly to an agent's reasoning loop.
-- **A real "start here."** `ahood skill init <name>` scaffolds a valid `SKILL.md` an agent can extend, rather than requiring it to know the frontmatter format up front.
-- **A native MCP server, for agents that prefer tool calls to subprocess parsing.** `ahood mcp` starts a Model Context Protocol server over stdio, exposing `skill_search`, `skill_view`, `skill_read`, `skill_versions`, `skill_list`, and `whoami` as typed tools -- the same data the `--json` flags above already return, reachable as structured tool calls instead. Configure your MCP-aware agent host to run `ahood mcp` (or `npx @ahood/cli@latest mcp`) as a stdio server.
+- **A built-in guide for the agent itself.** `ahood help useme` prints a complete `SKILL.md` teaching an agent when and how to use ahood -- kinds, search -> read -> add -> update, publishing, `--json`, exit codes, `AHOOD_TOKEN`, the MCP options, and which commands are destructive. It is bundled with the installed CLI version, so it needs no login, no network, and writes nothing: stdout is the raw file and nothing else (diagnostics go to stderr), ready to paste into an agent's context or for an agent with a shell to read directly (`ahood help useme > ahood-SKILL.md` saves it). That is separate from `ahood skill add alexkay/ahood`, which optionally installs the registry-published ahood skill into a project as its own pinned skill.
+- **A real "start here."** `ahood skill init <name>`, `ahood agent init <name>`, and `ahood mcp init <name>` scaffold a `SKILL.md`, `AGENT.md`, or `server.json` that passes the registry's publish validation, rather than requiring an agent to know each format up front.
+- **A native MCP server, for agents that prefer tool calls to subprocess parsing.** `ahood mcp serve` (or bare `ahood mcp`, unchanged for existing configs) starts a Model Context Protocol server over stdio, exposing `skill_search`, `skill_view`, `skill_read`, `skill_versions`, `skill_list`, `skill_outdated`, and `whoami` as typed, read-only tools -- the same data the `--json` flags above already return, reachable as structured tool calls instead. Configure your MCP-aware agent host to run `ahood mcp serve` (or `npx @ahood/cli@latest mcp serve`) as a stdio server, e.g. `claude mcp add ahood -- ahood mcp serve`.
 
 ## Development
 

package/dist/commands/add.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { mkdirSync, renameSync, rmSync, rmdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { mkdirSync, renameSync, rmSync, rmdirSync, statSync, writeFileSync, readFileSync, existsSync } from "node:fs";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import * as tarStream from "tar-stream";
 import { gunzipSync } from "node:zlib";
@@ -9,6 +9,7 @@ import { readLockfile, withLock, writeJsonFileAtomic, writeLockfileEntryVerifyin
 import { promptSecret } from "../secret-prompt.js";
 import { sanitizeForTerminal } from "../terminal-safe.js";
 import { UsageError } from "../usage-error.js";
+import { assertKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill add <owner>/<skill>[@version]";
 const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024; // 50 MB compressed
 const MAX_EXTRACTED_BYTES = 200 * 1024 * 1024; // 200 MB decompressed
@@ -515,19 +516,51 @@ export async function resolveMcpServerConfig(buffer, options = {}) {
     const serverConfig = buildMcpServerConfig(manifest, env);
     return { manifest, serverConfig, secretNames };
 }
+// Whether the config that was (or is about to be) written to disk actually
+// carries a credential: `env` also holds non-secret configuration now
+// (ahood-cli#120), so only names the manifest declared as secrets count.
+// Load-bearing in two places since ahood-cli#158: the install/update paths
+// consult it to request 0600 for a .mcp.json they are about to CREATE, and
+// warnIfSecretsWereWritten consults it to decide whether anything secret-
+// sensitive was written at all.
+function secretsLanded(serverConfig, secretNames) {
+    const env = serverConfig.env;
+    if (!env)
+        return false;
+    return secretNames.some((name) => Object.prototype.hasOwnProperty.call(env, name));
+}
 // The plaintext-secret warning printed after a successful mcp install/update.
 // Still derived from the config that actually landed on disk -- the property
 // the old bare `serverConfig.env` check was chosen for -- but intersected with
 // the manifest's declared secrets, because `env` now also holds non-secret
 // configuration (ahood-cli#120) and would otherwise warn about credentials
 // for a server that declares none.
+//
+// ahood-cli#158 composes a second piece onto it. A brand-new .mcp.json is
+// created 0600 when a secret landed (see installMcpEntry/updateMcpEntry), but
+// an EXISTING file keeps its pre-existing mode (#119) -- deliberately, since
+// tightening it could break another tool or user that reads the shared config.
+// So when the credential landed in a file that is still group/world-readable,
+// the warning says so and suggests chmod 600, leaving the decision with the
+// user who knows their environment, instead of the CLI chmod-ing behind their
+// back.
 function warnIfSecretsWereWritten(serverConfig, secretNames) {
-    const env = serverConfig.env;
-    if (!env)
-        return;
-    if (!secretNames.some((name) => Object.prototype.hasOwnProperty.call(env, name)))
+    if (!secretsLanded(serverConfig, secretNames))
         return;
-    console.warn(`WARNING: ${MCP_CONFIG_PATH} now contains one or more secret values in plaintext -- do not commit it to version control.`);
+    let warning = `WARNING: ${MCP_CONFIG_PATH} now contains one or more secret values in plaintext -- do not commit it to version control.`;
+    // statSync rather than lstat on purpose: a symlinked .mcp.json is written
+    // THROUGH (#144), so the mode that matters is the real file's. Best-effort:
+    // the write has already succeeded, so a stat that somehow fails must not
+    // surface as a second error -- the plaintext warning above still stands.
+    try {
+        if (statSync(MCP_CONFIG_PATH).mode & 0o077) {
+            warning += ` It is also readable by other users on this machine -- consider \`chmod 600 ${MCP_CONFIG_PATH}\`.`;
+        }
+    }
+    catch {
+        // advisory only, see comment above
+    }
+    console.warn(warning);
 }
 // Fingerprint of exactly what ahood wrote into .mcp.json's mcpServers.<skill>
 // entry, stored in the lockfile alongside the version/checksum pin. Lets
@@ -622,6 +655,11 @@ async function installMcpEntry(owner, skill, meta, buffer) {
     // collision check specifically rather than the manifest-shape check.
     assertNoCollision(readMcpConfig(), owner, skill);
     const { serverConfig, secretNames } = await resolveMcpServerConfig(buffer);
+    // Whether a credential landed decides two things now (ahood-cli#158): the
+    // mode a brand-new .mcp.json is created with below, and the warning after.
+    // 0600 applies to creation only -- an existing file keeps its pre-existing
+    // mode (#119) and gets the readability advisory in the warning instead.
+    const wroteSecrets = secretsLanded(serverConfig, secretNames);
     // Read-modify-write under an advisory lock, mirroring lockfile.ts's own
     // writeLockfileEntry: .mcp.json sits right next to the lockfile and can
     // hold other servers' secrets, so it gets the same protection against a
@@ -635,7 +673,7 @@ async function installMcpEntry(owner, skill, meta, buffer) {
         const fileContents = readMcpConfig();
         assertNoCollision(fileContents, owner, skill);
         fileContents.mcpServers[skill] = serverConfig;
-        writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents);
+        writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents, wroteSecrets ? 0o600 : undefined);
     });
     const mcpKey = `${owner}/${skill}`;
     try {
@@ -676,7 +714,7 @@ async function installMcpEntry(owner, skill, meta, buffer) {
             withLock(MCP_CONFIG_PATH, () => {
                 const fileContents = readMcpConfig();
                 delete fileContents.mcpServers[skill];
-                writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents);
+                writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents, wroteSecrets ? 0o600 : undefined);
             });
         }, `WARNING: could not roll back ${MCP_CONFIG_PATH} after ${mcpKey}'s install failed -- its mcpServers."${skill}" entry (which may contain a secret you entered) may still be present while ${LOCKFILE_PATH} has no pin for it. Delete that entry by hand before re-running \`ahood skill add ${mcpKey}\`.`);
         if (error instanceof LockfileChecksumConflictError) {
@@ -734,6 +772,11 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
     // prompt is correct.
     const existingEnv = readMcpEntryEnv(existingOnDisk);
     const { serverConfig, secretNames } = await resolveMcpServerConfig(buffer, { existingEnv, allowNonTtyPrompt: false });
+    // Same dual use as installMcpEntry's (ahood-cli#158): the self-heal case can
+    // CREATE a .mcp.json that just resolved a secret (the carried-forward env is
+    // gone with a hand-deleted entry, so a genuine resolution just happened),
+    // and the warning needs the same fact afterward.
+    const wroteSecrets = secretsLanded(serverConfig, secretNames);
     // Read-modify-write under an advisory lock, mirroring installMcpEntry's
     // own pattern. Re-checks the fingerprint here too (not just above) since
     // arbitrary time may have passed since the pre-check -- the download, and
@@ -749,7 +792,7 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
         }
         previousOnDisk = freshExisting;
         freshServers[skill] = serverConfig;
-        writeJsonFileAtomic(MCP_CONFIG_PATH, fresh);
+        writeJsonFileAtomic(MCP_CONFIG_PATH, fresh, wroteSecrets ? 0o600 : undefined);
     });
     try {
         writeLockfileEntryVerifyingChecksum(LOCKFILE_PATH, key, {
@@ -787,7 +830,7 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
                 else {
                     mcpServers[skill] = previousOnDisk;
                 }
-                writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents);
+                writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents, wroteSecrets ? 0o600 : undefined);
             });
         }, `WARNING: could not roll back ${MCP_CONFIG_PATH} after ${key}'s update failed -- its mcpServers."${skill}" entry may be on the new version while ${LOCKFILE_PATH} still pins the old one. Delete that entry by hand and run \`ahood skill add ${key}\` to reinstall.`);
         if (error instanceof LockfileChecksumConflictError) {
@@ -822,13 +865,28 @@ export async function downloadVerifiedArchive(owner, skill, meta) {
     }
     return buffer;
 }
-export async function add(args) {
+export async function add(args, scope) {
     const spec = args[0];
     if (!spec)
         throw new UsageError(USAGE);
     const { owner, skill, version: requestedVersion } = parseOwnerSkillVersion(spec, USAGE);
     const key = `${owner}/${skill}`;
     const meta = await fetchVersionMeta(owner, skill, requestedVersion);
+    // Kind-scoped install (`ahood agent add`, `ahood mcp add`, ahood-cli#172):
+    // refused here, before the download, the lockfile and every write below.
+    // Both metadata routes report the entry's kind, so this costs no request.
+    assertKind(scope, key, meta.kind, "add", "install");
+    // A doc has no local install target (ahood-cli#175): only skill, agent and
+    // mcp entries map to a place on disk. Legacy cross-kind `ahood skill add`
+    // used to fall through to the skill path and extract a doc into
+    // .claude/skills/<owner>@<slug>/ with no SKILL.md -- not a working skill,
+    // with nothing telling the user. Refused here, on every path, before the
+    // download, the lockfile and any write. Entries with NO kind keep the
+    // legacy skill behaviour.
+    if (meta.kind === "doc") {
+        throw new UsageError(`${key} is a doc (a documentation page), which has no local install target. ` +
+            `Read it with \`ahood skill read ${key}\`, or open it with \`ahood skill view ${key} --web\`.`);
+    }
     // A lockfile entry records the checksum this exact version was installed
     // with; if a later fetch of the "same" version disagrees, either the
     // published artifact changed after being pinned or the registry response

package/dist/commands/completion.js

@@ -1,57 +1,81 @@
-import { TOP_LEVEL_COMMANDS_HELP, SKILL_COMMANDS_HELP, COMMAND_ALIASES } from "../help.js";
+import { TOP_LEVEL_COMMANDS_HELP, SKILL_COMMANDS_HELP, AGENT_COMMANDS_HELP, MCP_COMMANDS_HELP, GROUP_COMMANDS_HELP, SNAP_COMMANDS_HELP, COMMAND_ALIASES, } from "../help.js";
 import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood completion <bash|zsh|fish>";
+// Every entity noun with its own verb list, in the order completion offers
+// them. Registry nouns (skill, agent, mcp -- ahood-cli#172) come first; group
+// and snap were already real nouns but had no completion at all before.
+const NOUNS = [
+    ["skill", SKILL_COMMANDS_HELP],
+    ["agent", AGENT_COMMANDS_HELP],
+    ["mcp", MCP_COMMANDS_HELP],
+    ["group", GROUP_COMMANDS_HELP],
+    ["snap", SNAP_COMMANDS_HELP],
+];
+function unique(names) {
+    return [...new Set(names.filter(Boolean))];
+}
 // Position 1 (the word right after "ahood"): every top-level command plus
-// the "skill" entity group itself.
+// every entity noun.
 function topLevelNames() {
-    return [...TOP_LEVEL_COMMANDS_HELP.map((c) => c.usage.split(" ")[1]), "skill"];
+    return unique([...TOP_LEVEL_COMMANDS_HELP.map((c) => c.usage.split(" ")[1]), ...NOUNS.map(([noun]) => noun)]);
+}
+// Position 2+, once a noun has been typed: that noun's verbs, plus alias
+// names (e.g. "show" for "view") wherever the aliased verb exists, so
+// completion offers every name a user might type. A bare `ahood mcp` entry
+// has no verb word and contributes nothing.
+function verbNames(entries) {
+    const primary = entries.map((c) => c.usage.split(" ")[2] ?? "");
+    const aliases = Object.keys(COMMAND_ALIASES).filter((alias) => primary.includes(COMMAND_ALIASES[alias]));
+    return unique([...primary, ...aliases]);
 }
-// Position 2+, once "skill" has been typed: every skill verb, plus alias
-// names (e.g. "show" for "view") so completion offers every name a user
-// might type, not just the ones with their own SKILL_COMMANDS_HELP entry.
-function skillNames() {
-    const primary = SKILL_COMMANDS_HELP.map((c) => c.usage.split(" ")[2]);
-    return [...primary, ...Object.keys(COMMAND_ALIASES)];
+// After `ahood help`: the self-skill guide plus every noun.
+function helpNames() {
+    return ["useme", ...NOUNS.map(([noun]) => noun)];
 }
 function bashCompletion() {
-    const top = topLevelNames().join(" ");
-    const skill = skillNames().join(" ");
-    return [
+    const lines = [
         "_ahood_completions() {",
         '  local cur="${COMP_WORDS[COMP_CWORD]}"',
-        `  local top_words="${top}"`,
-        `  local skill_words="${skill}"`,
-        '  if [[ "${COMP_WORDS[1]}" == "skill" && $COMP_CWORD -ge 2 ]]; then',
-        '    COMPREPLY=($(compgen -W "$skill_words" -- "$cur"))',
-        "  else",
-        '    COMPREPLY=($(compgen -W "$top_words" -- "$cur"))',
-        "  fi",
-        "}",
-        "complete -F _ahood_completions ahood",
-    ].join("\n");
+        `  local top_words="${topLevelNames().join(" ")}"`,
+        ...NOUNS.map(([noun, entries]) => `  local ${noun}_words="${verbNames(entries).join(" ")}"`),
+        `  local help_words="${helpNames().join(" ")}"`,
+    ];
+    NOUNS.forEach(([noun], i) => {
+        lines.push(`  ${i === 0 ? "if" : "elif"} [[ "\${COMP_WORDS[1]}" == "${noun}" && $COMP_CWORD -ge 2 ]]; then`);
+        lines.push(`    COMPREPLY=($(compgen -W "$${noun}_words" -- "$cur"))`);
+    });
+    lines.push('  elif [[ "${COMP_WORDS[1]}" == "help" && $COMP_CWORD -eq 2 ]]; then');
+    lines.push('    COMPREPLY=($(compgen -W "$help_words" -- "$cur"))');
+    lines.push("  else");
+    lines.push('    COMPREPLY=($(compgen -W "$top_words" -- "$cur"))');
+    lines.push("  fi");
+    lines.push("}");
+    lines.push("complete -F _ahood_completions ahood");
+    return lines.join("\n");
 }
 function zshCompletion() {
-    const top = topLevelNames().join(" ");
-    const skill = skillNames().join(" ");
-    return [
+    const lines = [
         "#compdef ahood",
-        "local -a top_cmds skill_cmds",
-        `top_cmds=(${top})`,
-        `skill_cmds=(${skill})`,
+        `local -a top_cmds ${NOUNS.map(([noun]) => `${noun}_cmds`).join(" ")} help_cmds`,
+        `top_cmds=(${topLevelNames().join(" ")})`,
+        ...NOUNS.map(([noun, entries]) => `${noun}_cmds=(${verbNames(entries).join(" ")})`),
+        `help_cmds=(${helpNames().join(" ")})`,
         "case $words[2] in",
-        "  skill)",
-        '    _describe "skill command" skill_cmds',
-        "    ;;",
-        "  *)",
-        '    _describe "command" top_cmds',
-        "    ;;",
-        "esac",
-    ].join("\n");
+    ];
+    for (const [noun] of NOUNS) {
+        lines.push(`  ${noun})`);
+        lines.push(`    _describe "${noun} command" ${noun}_cmds`);
+        lines.push("    ;;");
+    }
+    lines.push("  help)", '    _describe "help topic" help_cmds', "    ;;");
+    lines.push("  *)", '    _describe "command" top_cmds', "    ;;", "esac");
+    return lines.join("\n");
 }
 function fishCompletion() {
     return [
         ...topLevelNames().map((name) => `complete -c ahood -n "__fish_use_subcommand" -a "${name}"`),
-        ...skillNames().map((name) => `complete -c ahood -n "__fish_seen_subcommand_from skill" -a "${name}"`),
+        ...NOUNS.flatMap(([noun, entries]) => verbNames(entries).map((name) => `complete -c ahood -n "__fish_seen_subcommand_from ${noun}" -a "${name}"`)),
+        ...helpNames().map((name) => `complete -c ahood -n "__fish_seen_subcommand_from help" -a "${name}"`),
     ].join("\n");
 }
 // Position-aware command-name completion (not per-command flags) -- still

package/dist/commands/diff.js

@@ -2,6 +2,7 @@ import { createPatch } from "diff";
 import { fetchVersionMeta, downloadVerifiedArchive, extractSingleFileContent } from "./add.js";
 import { parseOwnerSkill, SEMVER_RE } from "../spec.js";
 import { UsageError } from "../usage-error.js";
+import { assertKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill diff <owner>/<skill> <versionA> <versionB> [--json]";
 // Both versions must be explicit semver here, unlike `add`'s
 // parseOwnerSkillVersion which lets "latest" default the version -- a diff
@@ -45,7 +46,7 @@ function diffManifests(manifestA, manifestB, skillMdChanged) {
     }
     return { added, removed, changed };
 }
-export async function diff(args) {
+export async function diff(args, scope) {
     const jsonOutput = args.includes("--json");
     const positional = args.filter((a) => !a.startsWith("--"));
     const [spec, versionA, versionB] = positional;
@@ -58,6 +59,8 @@ export async function diff(args) {
         fetchVersionMeta(owner, skill, versionA),
         fetchVersionMeta(owner, skill, versionB),
     ]);
+    // Both version responses carry the entry's kind; checked before either archive is downloaded.
+    assertKind(scope, `${owner}/${skill}`, metaA.kind, "diff", "diff");
     const [contentA, contentB] = await Promise.all([
         fetchSkillMdContent(owner, skill, metaA),
         fetchSkillMdContent(owner, skill, metaB),

package/dist/commands/edit.js

@@ -2,13 +2,14 @@ import { apiJson } from "../http.js";
 import { flagValue } from "../flags.js";
 import { parseOwnerSkill, validateExternalUrl } from "../spec.js";
 import { UsageError } from "../usage-error.js";
+import { ensureRemoteKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill edit <owner>/<skill> [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--visibility public|private] [--homepage <url>] [--repository <url>]";
 // Mirrors PATCH /api/v1/skills/{owner}/{skill}'s allow-list exactly
 // (lib/skills/mutations.ts's UpdateSkillInput) -- only a field the caller
 // explicitly passed a flag for is included in the body, so an omitted flag
 // never clobbers an existing value (the route only validates/writes keys
 // that are present on the body at all).
-export async function edit(args) {
+export async function edit(args, scope) {
     const spec = args[0];
     if (!spec || spec.startsWith("--"))
         throw new UsageError(USAGE);
@@ -43,6 +44,7 @@ export async function edit(args) {
     if (Object.keys(body).length === 0) {
         throw new UsageError("Nothing to update -- pass at least one of --tagline, --tags, --license, --visibility, --homepage, --repository.");
     }
+    await ensureRemoteKind(scope, owner, skill, "edit", "edit");
     const updated = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`, {
         method: "PATCH",
         headers: { "Content-Type": "application/json" },

package/dist/commands/init.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { basename, join, resolve, sep } from "node:path";
 import { UsageError } from "../usage-error.js";
+import { CLI_KINDS, KINDS, strictKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill init [name]";
 // Mirrors the server's slug convention referenced by ahood-cli#60 (and the
 // same shape as spec.ts's SEGMENT_RE, minus "." and "_" -- skill slugs are
@@ -56,15 +57,76 @@ description: TODO -- describe what this skill does and when Claude should use it
 TODO: describe, step by step, what Claude should do when this skill is invoked.
 `;
 }
+// AGENT.md, for `ahood agent init` (ahood-cli#172). The backend's publish
+// validator (lib/publish/parse-agent-frontmatter.ts in the ahood repo) is a
+// hand-rolled flat `key: value` reader, not YAML: it requires the file to
+// START with a `---` line, a closing `---` line followed by a newline, and
+// non-empty `name` and `description`; an optional `skills: [owner/slug, ...]`
+// flow list must hold owner/slug entries. Claude Code's own subagent loader
+// reads the same frontmatter (name, description, and optionally tools and
+// model). So: no leading comment above the opening `---` (that alone fails
+// publish), and the optional keys are left as commented-out examples, with
+// no colon in any prose comment, so neither reader can mistake a comment for
+// a key.
+function buildAgentMd(name) {
+    return `---
+name: ${name}
+description: TODO -- describe what this agent does and when Claude should delegate to it.
+# Optional. Uncomment to restrict the tools this agent may use (omit to inherit all).
+# tools: Read, Grep, Glob
+# Optional. Uncomment to pin a model for this agent.
+# model: sonnet
+---
+
+TODO -- write the system prompt for this agent. Say what it is responsible for,
+the steps it should take, and what it should hand back when it is done.
+`;
+}
+// server.json, for `ahood mcp init` (ahood-cli#172). Mirrors exactly what the
+// backend's publish validator (lib/publish/parse-server-manifest.ts in the
+// ahood repo) accepts: a JSON object with non-empty `name` and `description`
+// and exactly one of `packages` (one npm/npx entry) or `remotes` (one http(s)
+// url). The starter uses `remotes`, pointed at a reserved example.com host
+// (RFC 2606), deliberately: a `packages` placeholder would name an npm
+// package that `ahood mcp add` turns into `npx -y <identifier>@<version>` --
+// an install of whatever someone later publishes under that name if the
+// starter were ever published unedited. A reserved host can never resolve to
+// anyone's server. JSON has no comments, so the editing guidance is printed
+// by init instead.
+function buildServerJson(name) {
+    const manifest = {
+        name,
+        description: "TODO -- describe what this MCP server does and when an agent should use it.",
+        remotes: [{ url: "https://mcp.example.com/mcp" }],
+    };
+    return `${JSON.stringify(manifest, null, 2)}
+`;
+}
+const TEMPLATES = {
+    skill: buildSkillMd,
+    agent: buildAgentMd,
+    mcp: buildServerJson,
+};
+const NEXT_STEPS = {
+    skill: ["Fill in the description, then flesh out the ## Instructions section."],
+    agent: ["Fill in the description, then write the agent's system prompt below the frontmatter."],
+    mcp: [
+        "Fill in the description and point remotes[0].url at your server's https endpoint, or replace",
+        '"remotes" with one npm package: "packages": [{"registry_type": "npm", "runtime_hint": "npx",',
+        '"identifier": "<npm-package>", "version": "<x.y.z>"}] (plus optional "environment_variables").',
+    ],
+};
 // Falls back to "my-skill" when the directory name itself isn't usable as a
 // bare YAML scalar (empty, or starting with a character like "-" or "@" that
 // would need quoting) -- e.g. running `ahood skill init` with no name directly in
 // "/" (basename "") or in a directory whose name starts with punctuation.
-function skillNameFor(dirPath) {
+function skillNameFor(dirPath, fallback = "my-skill") {
     const base = basename(dirPath);
-    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(base) ? base : "my-skill";
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(base) ? base : fallback;
 }
-export async function init(args) {
+export async function init(args, scope) {
+    const strict = strictKind(scope);
+    const kind = strict ?? "skill";
     let name = args[0];
     if (name !== undefined && name.startsWith("-"))
         throw new UsageError(USAGE);
@@ -93,13 +155,31 @@ export async function init(args) {
         }
     }
     const targetDir = name ? resolve(name) : process.cwd();
-    const skillMdPath = join(targetDir, "SKILL.md");
-    if (existsSync(skillMdPath)) {
-        throw new Error(`SKILL.md already exists at ${skillMdPath} -- refusing to overwrite it.`);
+    const rootDoc = KINDS[kind].rootDoc;
+    const docPath = join(targetDir, rootDoc);
+    if (existsSync(docPath)) {
+        throw new Error(`${rootDoc} already exists at ${docPath} -- refusing to overwrite it.`);
+    }
+    // A kind-scoped init also refuses a folder that already holds ANOTHER
+    // kind's root document: one folder is one artifact, and a second root doc
+    // makes a plain `ahood skill publish` of that folder ambiguous. The legacy
+    // `ahood skill init` keeps its exact pre-#172 behavior.
+    if (strict !== undefined) {
+        for (const other of CLI_KINDS) {
+            if (other === kind)
+                continue;
+            const otherPath = join(targetDir, KINDS[other].rootDoc);
+            if (existsSync(otherPath)) {
+                throw new Error(`${otherPath} already exists -- that folder is already ${KINDS[other].article} ${KINDS[other].label}. ` +
+                    `Refusing to add ${rootDoc} next to it; pick another name.`);
+            }
+        }
     }
     mkdirSync(targetDir, { recursive: true });
-    writeFileSync(skillMdPath, buildSkillMd(name ?? skillNameFor(targetDir)));
-    console.log(`Created ${skillMdPath}`);
-    console.log("Fill in the description, then flesh out the ## Instructions section.");
-    console.log(`Run \`ahood skill publish <owner>/<skill>@<version>${name ? ` --path ${name}` : ""}\` when ready.`);
+    writeFileSync(docPath, TEMPLATES[kind](name ?? skillNameFor(targetDir, `my-${kind}`)));
+    console.log(`Created ${docPath}`);
+    for (const line of NEXT_STEPS[kind])
+        console.log(line);
+    const placeholder = kind === "skill" ? "<skill>" : kind === "agent" ? "<agent>" : "<server>";
+    console.log(`Run \`ahood ${strict ?? "skill"} publish <owner>/${placeholder}@<version>${name ? ` --path ${name}` : ""}\` when ready.`);
 }