@ahood/cli 0.7.3 → 0.8.1

package/dist/help.js

@@ -100,7 +100,9 @@ export const SKILL_COMMANDS_HELP = [
     {
         usage: "ahood skill update [<owner>/<skill> ...] [--dry-run] [--json]",
         summary: "Move the lockfile pin(s) forward to the latest version, for one skill or all installed skills at once.",
-        desc: "Move the lockfile pin(s) forward to the latest version. With no argument, updates every installed skill; one failure doesn't stop the rest.",
+        desc: "Move the lockfile pin(s) forward to the latest version. With no argument, updates every installed skill; one failure doesn't stop the rest. " +
+            "An mcp-kind entry is updated in place (re-resolving any secret environment variables) as long as its .mcp.json entry still matches what " +
+            "ahood last installed there -- a hand-edited or unverifiable entry is refused rather than silently overwritten.",
         flags: [
             "--dry-run   Preview current vs. latest version (and the changelog for anything behind) without installing anything.",
             "--json      With --dry-run, emit structured preview objects instead of a formatted table.",
@@ -117,9 +119,11 @@ export const SKILL_COMMANDS_HELP = [
         examples: ["ahood skill outdated", "ahood skill outdated alice/pdf-tools --json"],
     },
     {
-        usage: "ahood skill remove <owner>/<skill>",
-        summary: "Uninstall and unpin a skill (local only).",
-        desc: "Uninstall and unpin (local only).",
+        usage: "ahood skill remove <owner>/<skill> [--yes]",
+        summary: "Uninstall and unpin a skill (local only, prompts for confirmation unless --yes is passed).",
+        desc: "Uninstall and unpin (local only). Prompts for confirmation unless --yes is passed. For an mcp-kind install, " +
+            "also deletes its .mcp.json entry as long as it still matches what ahood last installed there -- a hand-edited " +
+            "or unverifiable entry is left in place and warned about instead of being silently touched.",
     },
     {
         usage: "ahood skill edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]",
@@ -246,15 +250,19 @@ export const GROUP_COMMANDS_HELP = [
         ],
     },
     {
-        usage: "ahood group remove-member <group> <username>",
-        summary: "Remove a member from a group you own.",
+        usage: "ahood group remove-member <group> <username> [--yes]",
+        summary: "Remove a member from a group you own (prompts for confirmation unless --yes is passed).",
         desc: "Remove a member from a group you own. The group's owner cannot be removed this way -- delete the " +
-            "group instead. Only the group's owner can remove someone other than themselves.",
+            "group instead. Only the group's owner can remove someone other than themselves. Prompts for a typed " +
+            "\"yes\" unless --yes is passed.",
+        flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
     },
     {
-        usage: "ahood group leave <group>",
-        summary: "Leave a group you belong to.",
-        desc: "Leave a group you belong to. The group's owner cannot leave -- delete the group instead.",
+        usage: "ahood group leave <group> [--yes]",
+        summary: "Leave a group you belong to (prompts for confirmation unless --yes is passed).",
+        desc: "Leave a group you belong to. The group's owner cannot leave -- delete the group instead. Prompts for " +
+            "a typed \"yes\" unless --yes is passed.",
+        flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
     },
     {
         usage: "ahood group delete <group> [--yes]",
@@ -264,6 +272,84 @@ export const GROUP_COMMANDS_HELP = [
         flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
     },
 ];
+// Every snap-entity verb, all reached as `ahood snap <verb>` -- mirrors
+// GROUP_COMMANDS_HELP above, just for the "Snaps" feature (ahood-cli#107):
+// a private, freeform text note capturing "what happened this session",
+// searchable later by its owner, optionally shareable via a revocable link,
+// never public otherwise.
+export const SNAP_COMMANDS_HELP = [
+    {
+        usage: "ahood snap create <content> [--tags tag1,tag2] [--json]",
+        summary: "Capture a new private snap, from an argument or piped stdin.",
+        desc: "Capture a new private snap. Pass the content as an argument, or omit it and pipe content on stdin " +
+            "(e.g. `echo \"...\" | ahood snap create`, or a piped heredoc) -- useful for capturing a whole session's " +
+            "worth of freeform text at once. Prints the new snap's id on success.",
+        flags: [
+            "--tags <comma,separated>   Attach tags to the new snap.",
+            "--json                     Emit {id, created_at} instead of just the bare id.",
+        ],
+        examples: [
+            'ahood snap create "Debugged the flaky CI step, root cause was a race in the cache key." --tags deploy,bugfix',
+            'echo "..." | ahood snap create',
+        ],
+    },
+    {
+        usage: "ahood snap list [--json] [--limit <n>]",
+        summary: "List your own snaps, most recent first.",
+        desc: "List your own snaps: id, a truncated content preview, created_at, a (shared) marker if shared, and " +
+            "any tags in brackets.",
+        flags: [
+            "--json        Emit the raw snap objects instead of formatted lines.",
+            "--limit <n>   Cap the number of results.",
+        ],
+    },
+    {
+        usage: "ahood snap search <query> [--json] [--limit <n>]",
+        summary: "Search your own snaps by content.",
+        desc: "Search your own snaps by content. Same output shape as `ahood snap list`.",
+        flags: [
+            "--json        Emit the raw snap objects instead of formatted lines.",
+            "--limit <n>   Cap the number of results.",
+        ],
+        examples: ["ahood snap search flaky-ci"],
+    },
+    {
+        usage: "ahood snap show <id> [--json]",
+        summary: "Print a single snap's full content.",
+        desc: "Print a single snap's full content. Plain mode prints the raw content verbatim to stdout -- no " +
+            "formatting, no labels -- so it's safe to pipe into a file or another tool.",
+        flags: ["--json    Emit the full snap object instead of the raw content."],
+    },
+    {
+        usage: "ahood snap remove <id> [--yes]",
+        summary: "Permanently delete a snap (prompts for confirmation unless --yes is passed).",
+        desc: "Permanently delete a snap. Irreversible. Prompts for a typed \"yes\" unless --yes is passed.",
+        flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
+    },
+    {
+        usage: "ahood snap share <id> [--json]",
+        summary: "Mint (or return the existing) shareable link for a snap.",
+        desc: "Mint or return the existing shareable link for a snap. Idempotent -- safe to run more than once.",
+        flags: ["--json    Emit {share_url} instead of just the bare URL."],
+    },
+    {
+        usage: "ahood snap unshare <id> [--yes]",
+        summary: "Revoke a snap's share link (the snap itself is untouched; prompts for confirmation unless --yes is passed).",
+        desc: "Revoke a snap's share link -- the snap itself is untouched, and re-running `ahood snap share` mints a new " +
+            "link. Prompts for a typed \"yes\" unless --yes is passed, since anyone using the old link loses access " +
+            "immediately.",
+        flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
+    },
+    {
+        usage: "ahood snap tags <id> [tag1,tag2,...] [--json]",
+        summary: "Replace a snap's tags (omit the tag list, or pass an empty one, to clear all tags).",
+        desc: "Replace the full set of tags on a snap -- this is not a merge, so any existing tags not listed are " +
+            "dropped. Omitting the tag list entirely, or passing an empty string, clears all tags. No confirmation " +
+            "prompt: unlike remove/unshare this only touches metadata, never the snap's content or shareability.",
+        flags: ["--json    Emit {id, tags} instead of a plain-text summary."],
+        examples: ["ahood snap tags snap_123 deploy,bugfix", 'ahood snap tags snap_123 ""'],
+    },
+];
 // Exported so other consumers of the command list (e.g. shell completion) can
 // surface aliases without needing their own copy of this map. Aliases apply
 // at the skill-verb level today (e.g. "show" for "view"); nothing at the
@@ -276,6 +362,7 @@ export const COMMAND_ALIASES = { show: "view" };
 const ENTITY_COMMANDS_HELP = {
     skill: SKILL_COMMANDS_HELP,
     group: GROUP_COMMANDS_HELP,
+    snap: SNAP_COMMANDS_HELP,
 };
 // Two-token lookup for an entity verb (findCommandHelp("skill", "search"),
 // findCommandHelp("group", "create")) or a single-token lookup for a
@@ -283,6 +370,16 @@ const ENTITY_COMMANDS_HELP = {
 export function findCommandHelp(command, subcommand) {
     const entityList = ENTITY_COMMANDS_HELP[command];
     if (entityList && subcommand !== undefined) {
+        // Try the literal verb first -- COMMAND_ALIASES is a single global map
+        // ("show" -> "view", for skill's alias), but a different entity can
+        // have its own real verb that happens to share the alias's name (e.g.
+        // `ahood snap show`, a real verb, not an alias for anything). Resolving
+        // through COMMAND_ALIASES unconditionally would send that lookup to a
+        // nonexistent "ahood snap view" entry instead of the literal "ahood
+        // snap show" one that's actually in this list.
+        const literal = entityList.find((c) => c.usage.startsWith(`ahood ${command} ${subcommand} `) || c.usage === `ahood ${command} ${subcommand}`);
+        if (literal)
+            return literal;
         const resolved = COMMAND_ALIASES[subcommand] ?? subcommand;
         return entityList.find((c) => c.usage.startsWith(`ahood ${command} ${resolved} `) || c.usage === `ahood ${command} ${resolved}`);
     }
@@ -403,18 +500,34 @@ export function formatGroupHelp() {
         "Run `ahood group <command> --help` for a single command's flags and examples.",
     ].join("\n");
 }
+// `ahood snap --help` -- the group-level listing for every snap verb.
+export function formatSnapHelp() {
+    const lines = formatCommandTable(SNAP_COMMANDS_HELP.map((c) => ({ usage: usageWithAliases(c), summary: c.summary })));
+    return [
+        "ahood snap -- capture and search private, session-scoped notes",
+        "",
+        "Commands:",
+        ...lines,
+        "",
+        "Run `ahood snap <command> --help` for a single command's flags and examples.",
+    ].join("\n");
+}
 // `ahood --help` -- the top-level listing: account commands rendered in
-// full, plus a single summary line each pointing at `ahood skill --help`
-// and `ahood group --help` for their (much longer) entity command lists.
+// full, plus a single summary line each pointing at `ahood skill --help`,
+// `ahood group --help`, and `ahood snap --help` for their (much longer)
+// entity command lists.
 export function formatHelp() {
     const skillGroupUsage = "ahood skill <command>";
     const skillGroupSummary = "Search, install, and publish skills -- run `ahood skill --help` for the full list.";
     const groupGroupUsage = "ahood group <command>";
     const groupGroupSummary = "Create private groups and share skills with them -- run `ahood group --help` for the full list.";
+    const snapGroupUsage = "ahood snap <command>";
+    const snapGroupSummary = "Capture and search private, session-scoped notes -- run `ahood snap --help` for the full list.";
     const lines = formatCommandTable([
         ...TOP_LEVEL_COMMANDS_HELP.map((c) => ({ usage: usageWithAliases(c), summary: c.summary })),
         { usage: skillGroupUsage, summary: skillGroupSummary },
         { usage: groupGroupUsage, summary: groupGroupSummary },
+        { usage: snapGroupUsage, summary: snapGroupSummary },
     ]);
     return [
         "ahood -- CLI for the ahood skills registry (https://ahood.vercel.app)",
@@ -430,6 +543,7 @@ export function formatHelp() {
         "Run `ahood <command> --help` (or `ahood help <command>`) for a single command's flags and examples.",
         "Run `ahood skill --help` for the full list of skill commands.",
         "Run `ahood group --help` for the full list of group commands.",
+        "Run `ahood snap --help` for the full list of snap commands.",
         "Run `ahood --version` to print the installed CLI version.",
         "",
         "Exit codes: 0 success, 1 general error, 2 usage/validation error,",

package/dist/http.js

@@ -65,8 +65,17 @@ export async function apiJson(path, init = {}) {
             : `Request failed with status ${res.status}`;
         throw new ApiError(res.status, message);
     }
+    // A 204 No Content (or any 2xx with an empty body) has nothing to parse --
+    // res.json() throws on empty input, which previously surfaced as a
+    // generic "Malformed response" error even though the request succeeded
+    // (ahood-cli#103). Callers that don't need response data (e.g. token
+    // revoke, which awaits this without using the result) get `undefined`
+    // back instead of a spurious failure.
+    const text = await res.text();
+    if (text === "")
+        return undefined;
     try {
-        return (await res.json());
+        return JSON.parse(text);
     }
     catch {
         throw new Error(`Malformed response from ${getApiUrl()}${path}: expected JSON.`);

package/dist/index.js

@@ -22,7 +22,8 @@ import { completion } from "./commands/completion.js";
 import { mcp } from "./commands/mcp.js";
 import { init } from "./commands/init.js";
 import { createGroup, listGroups, groupMembers, inviteLink, joinGroup, removeMember, leaveGroup, deleteGroup, } from "./commands/group.js";
-import { formatHelp, formatSkillHelp, formatGroupHelp, formatCommandHelp, findCommandHelp } from "./help.js";
+import { createSnap, listSnaps, searchSnaps, showSnap, removeSnap, shareSnap, unshareSnap, tagsSnap, } from "./commands/snap.js";
+import { formatHelp, formatSkillHelp, formatGroupHelp, formatSnapHelp, formatCommandHelp, findCommandHelp } from "./help.js";
 import { ApiError } from "./http.js";
 import { exitCodeFor } from "./exit-code.js";
 import { CLI_NAME, CLI_VERSION } from "./version.js";
@@ -68,10 +69,23 @@ const GROUP_VERBS = {
     leave: leaveGroup,
     delete: deleteGroup,
 };
+// Every snap-entity verb, reached only as `ahood snap <verb>` -- see
+// dispatchSnap() below. Mirrors GROUP_VERBS above exactly; a snap is a pure
+// API-client entity like a group, with no local filesystem footprint.
+const SNAP_VERBS = {
+    create: createSnap,
+    list: listSnaps,
+    search: searchSnaps,
+    show: showSnap,
+    remove: removeSnap,
+    share: shareSnap,
+    unshare: unshareSnap,
+    tags: tagsSnap,
+};
 // Top level is now just account/auth-scoped commands (not entity-specific --
-// same reasoning `gh auth login` isn't `gh account login`) plus the `skill`
-// and `group` entity groups. Future entities (e.g. "personality",
-// "protocols") get their own entry here alongside these two.
+// same reasoning `gh auth login` isn't `gh account login`) plus the `skill`,
+// `group`, and `snap` entity groups. Future entities get their own entry
+// here alongside these.
 const COMMANDS = {
     login: () => login(),
     logout: () => logout(),
@@ -81,6 +95,7 @@ const COMMANDS = {
     mcp,
     skill: dispatchSkill,
     group: dispatchGroup,
+    snap: dispatchSnap,
 };
 // Commands whose handler owns its own --help handling (at both the group
 // level, e.g. `ahood skill --help` / `ahood group --help`, and the per-verb
@@ -88,8 +103,9 @@ const COMMANDS = {
 // instead of the generic top-level interception in main(). Despite the
 // name, this Set has nothing to do with the "Groups" feature -- "group"
 // here just means "a command that owns its own sub-verb dispatch", the same
-// sense "skill" already used before "group" (the entity) existed.
-const GROUP_COMMANDS = new Set(["skill", "group"]);
+// sense "skill" already used before "group" (the entity) existed. "snap"
+// joins this set for the exact same reason (ahood-cli#107).
+const GROUP_COMMANDS = new Set(["skill", "group", "snap"]);
 function levenshtein(a, b) {
     const dp = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
     for (let i = 0; i <= a.length; i++)
@@ -124,6 +140,9 @@ function closestSkillCommand(input) {
 function closestGroupVerb(input) {
     return closestOf(input, Object.keys(GROUP_VERBS));
 }
+function closestSnapVerb(input) {
+    return closestOf(input, Object.keys(SNAP_VERBS));
+}
 // `ahood skill <verb> [...]` -- owns its own help handling at both the
 // group level (`ahood skill` / `ahood skill --help`) and the per-verb level
 // (`ahood skill <verb> --help`), since neither should fall through to
@@ -175,6 +194,32 @@ async function dispatchGroup(args) {
     }
     await handler(rest);
 }
+// `ahood snap <verb> [...]` -- owns its own help handling at both the
+// group level (`ahood snap` / `ahood snap --help`) and the per-verb level
+// (`ahood snap <verb> --help`), exactly mirroring dispatchSkill()/
+// dispatchGroup() above.
+async function dispatchSnap(args) {
+    const [sub, ...rest] = args;
+    if (!sub || sub === "--help" || sub === "-h") {
+        console.log(formatSnapHelp());
+        return;
+    }
+    const handler = SNAP_VERBS[sub];
+    if (!handler) {
+        console.error(`Unknown snap command: ${sub}`);
+        const suggestion = closestSnapVerb(sub);
+        if (suggestion)
+            console.error(`Did you mean '${suggestion}'?`);
+        console.error("Run `ahood snap --help` for a list of commands.");
+        process.exit(2);
+    }
+    if (rest.includes("--help") || rest.includes("-h")) {
+        const entry = findCommandHelp("snap", sub);
+        console.log(entry ? formatCommandHelp(entry) : formatSnapHelp());
+        return;
+    }
+    await handler(rest);
+}
 async function main() {
     const [command, ...args] = process.argv.slice(2);
     if (command === "--version" || command === "-v") {
@@ -195,6 +240,12 @@ async function main() {
             console.log(entry ? formatCommandHelp(entry) : formatGroupHelp());
             return;
         }
+        if (sub === "snap") {
+            const verb = args[1];
+            const entry = verb ? findCommandHelp("snap", verb) : undefined;
+            console.log(entry ? formatCommandHelp(entry) : formatSnapHelp());
+            return;
+        }
         const entry = sub ? findCommandHelp(sub) : undefined;
         console.log(entry ? formatCommandHelp(entry) : formatHelp());
         return;
@@ -223,8 +274,10 @@ async function main() {
         console.error("Run `ahood help` for a list of commands.");
         process.exit(2);
     }
-    // Group commands (currently just "skill") own their own --help handling
-    // at both the group and per-verb level -- don't intercept here.
+    // Entities with their own sub-dispatch ("skill", "group", "snap" --
+    // GROUP_COMMANDS despite the name, unrelated to the "group" entity itself)
+    // own their own --help handling at both the entity and per-verb level --
+    // don't intercept here.
     if (!GROUP_COMMANDS.has(command) && (args.includes("--help") || args.includes("-h"))) {
         const entry = findCommandHelp(command);
         console.log(entry ? formatCommandHelp(entry) : formatHelp());
@@ -257,4 +310,4 @@ if (isEntrypoint) {
     main();
 }
 // Exported for tests only -- the CLI itself only ever calls main() above.
-export { main, dispatchSkill, dispatchGroup, COMMANDS, SKILL_COMMANDS, GROUP_VERBS };
+export { main, dispatchSkill, dispatchGroup, dispatchSnap, COMMANDS, SKILL_COMMANDS, GROUP_VERBS, SNAP_VERBS };

package/dist/lockfile.js

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmdirSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 export function readLockfile(path) {
     if (!existsSync(path))
         return {};
@@ -31,24 +31,83 @@ export function writeJsonFileAtomic(path, data) {
 function writeLockfile(path, lockfile) {
     writeJsonFileAtomic(path, lockfile);
 }
+// A lock directory is stale if the PID recorded inside it (written by the
+// acquirer below) belongs to a process that's no longer running -- signal 0
+// doesn't actually deliver a signal, just probes whether the process could
+// be signaled. ESRCH means it's dead; EPERM means it's alive but owned by
+// someone else, which is conservatively treated as still alive since that
+// can't be disproven. A missing/unparseable pid file is also treated as
+// "not stale" -- either a lock from before this file existed, or another
+// process is still mid-way through acquiring (mkdirSync succeeded, the pid
+// write hasn't landed yet) -- safer to wait it out than to reclaim a lock
+// that's actually still being set up.
+function isLockStale(pidFile) {
+    let pidText;
+    try {
+        pidText = readFileSync(pidFile, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const pid = Number(pidText);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
 // Simple advisory lock via mkdir's atomicity (EEXIST on a second caller),
 // so two concurrent `ahood skill add`/`remove` invocations against the same
 // project don't race a read-modify-write and silently drop one another's
 // entry. Exported so other same-directory JSON files with the same
 // read-modify-write shape (e.g. add.ts's .mcp.json merge) can reuse it
 // instead of duplicating the pattern.
+//
+// The lock directory holds a `pid` file naming its holder, so a process
+// that finds the lock held can tell a live holder from one that was
+// hard-killed (SIGKILL/OOM) mid-critical-section: without this, such a lock
+// is never released, and every subsequent add/remove/update in that project
+// busy-waits out the full timeout below and then fails permanently until a
+// human manually deletes the stale directory (ahood-cli#100).
 export function withLock(path, fn) {
     mkdirSync(dirname(path), { recursive: true });
     const lockDir = `${path}.lock`;
+    const pidFile = join(lockDir, "pid");
     const deadline = Date.now() + 5000;
     for (;;) {
         try {
             mkdirSync(lockDir);
+            // Best-effort: mkdirSync above is what actually holds the lock: if
+            // this write fails for some reason, the lock is still correctly held,
+            // just without staleness detection for this particular acquisition.
+            try {
+                writeFileSync(pidFile, String(process.pid));
+            }
+            catch {
+                // non-fatal, see comment above
+            }
             break;
         }
         catch (error) {
             if (error.code !== "EEXIST")
                 throw error;
+            if (isLockStale(pidFile)) {
+                // Reclaim it. Best-effort removal: if a concurrent process wins the
+                // race and reclaims (or a live holder finishes and releases) first,
+                // this just falls through to the normal wait/retry below instead of
+                // throwing.
+                try {
+                    rmSync(lockDir, { recursive: true, force: true });
+                }
+                catch {
+                    // lost the race -- fall through to wait/retry
+                }
+                continue;
+            }
             if (Date.now() > deadline) {
                 throw new Error(`Timed out waiting for the lockfile lock at ${lockDir}. If no other ahood process is running, delete that directory manually.`);
             }
@@ -59,7 +118,7 @@ export function withLock(path, fn) {
         return fn();
     }
     finally {
-        rmdirSync(lockDir);
+        rmSync(lockDir, { recursive: true, force: true });
     }
 }
 export function writeLockfileEntry(path, ownerSlashSkill, entry) {
@@ -69,6 +128,40 @@ export function writeLockfileEntry(path, ownerSlashSkill, entry) {
         writeLockfile(path, lockfile);
     });
 }
+// Thrown by writeLockfileEntryVerifyingChecksum -- carries the conflicting
+// entry so the caller (add.ts) can build its own user-facing message and
+// decide what to roll back (an already-extracted skill dir, an already-
+// written agent file, an already-merged .mcp.json entry).
+export class LockfileChecksumConflictError extends Error {
+    existing;
+    constructor(existing) {
+        super("Lockfile checksum conflict");
+        this.existing = existing;
+    }
+}
+// add.ts's checksum-pin tamper-detection guard used to read the lockfile
+// (unlocked) well before the eventual writeLockfileEntry call, which
+// acquires its OWN, separate lock later -- two independently-locked steps,
+// not one atomic operation. Under concurrent installs of "the same"
+// version with different (tampered) checksums, both processes' unlocked
+// reads could see no conflict, so both writes would proceed and whichever
+// wins the later lock silently overwrites the other with no error ever
+// surfaced -- exactly the tampering this guard exists to catch
+// (ahood-cli#101). Performing the read, the check, and the write inside one
+// locked critical section closes that window: whichever caller's write
+// actually lands is checked against the lockfile state as it exists AT
+// THAT MOMENT, not a possibly-stale snapshot from earlier.
+export function writeLockfileEntryVerifyingChecksum(path, ownerSlashSkill, entry) {
+    withLock(path, () => {
+        const lockfile = readLockfile(path);
+        const existing = lockfile[ownerSlashSkill];
+        if (existing && existing.version === entry.version && existing.checksum_sha256 !== entry.checksum_sha256) {
+            throw new LockfileChecksumConflictError(existing);
+        }
+        lockfile[ownerSlashSkill] = entry;
+        writeLockfile(path, lockfile);
+    });
+}
 export function removeLockfileEntry(path, ownerSlashSkill) {
     return withLock(path, () => {
         const lockfile = readLockfile(path);

package/dist/spec.js

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { UsageError } from "./usage-error.js";
-// Owner and skill segments become filesystem path components (.claude/skills/<owner>/<skill>)
+// Owner and skill segments become filesystem path components (.claude/skills/<owner>@<skill>)
 // and URL path segments, so both are restricted to a safe charset that cannot contain "..",
 // "/", "\", or a leading dot -- this is what closes the path-traversal hole in add/remove
 // (a spec like "alice/.." previously resolved outside .claude/skills/ entirely).
@@ -76,23 +76,34 @@ export function validateExternalUrl(value, flag) {
 }
 export const SKILLS_ROOT = join(".claude", "skills");
 export const LOCKFILE_PATH = join(".claude", "skills.lock.json");
+// Claude Code's own project-skill loader scans .claude/skills/ exactly one
+// level deep (each immediate child directory is checked for a SKILL.md),
+// not recursively -- so the previous owner-nested layout
+// (.claude/skills/<owner>/<skill>/SKILL.md) was never discovered by Claude
+// Code at all; it only ever worked via this CLI's own commands (ahood-cli#96).
+// Joining owner and skill into one flat directory name with "@" fixes that
+// while staying collision-resistant, mirroring agentPath below: SEGMENT_RE's
+// character class [a-z0-9._-] (case-insensitive) never contains "@", so the
+// joined name always has exactly one "@", unambiguous for any pair of
+// SEGMENT_RE-valid values. "@" is a valid path-segment character on Linux,
+// macOS, and Windows.
 export function skillDir(owner, skill) {
-    return join(SKILLS_ROOT, owner, skill);
+    return join(SKILLS_ROOT, `${owner}@${skill}`);
 }
 // Claude Code's own subagent loader scans .claude/agents/*.md as flat files
-// (non-recursive), unlike .claude/skills/<owner>/<skill>/ which nests by
-// owner -- a bare .claude/agents/<skill>.md would let two different owners'
-// same-named agent collide and silently overwrite each other. Joining the
-// owner into the filename with "@" keeps the layout flat (so Claude Code
-// still finds it) while staying collision-resistant: SEGMENT_RE's character
-// class is exactly [a-z0-9._-] (case-insensitive), which does not include
-// "@" -- so "@" can never appear inside a valid owner or skill segment, and
-// the joined filename always contains exactly one "@", at the boundary
-// between the two segments. That makes the join unambiguous for any pair of
-// SEGMENT_RE-valid values, including ones containing hyphens (e.g.
-// owner="al-ice"/skill="bob" joins to "al-ice@bob.md", which cannot also be
-// produced by any other valid owner/skill pair). "@" is a valid filename
-// character on Linux, macOS, and Windows.
+// (non-recursive), same reasoning as skillDir above -- a bare
+// .claude/agents/<skill>.md would let two different owners' same-named agent
+// collide and silently overwrite each other. Joining the owner into the
+// filename with "@" keeps the layout flat (so Claude Code still finds it)
+// while staying collision-resistant: SEGMENT_RE's character class is exactly
+// [a-z0-9._-] (case-insensitive), which does not include "@" -- so "@" can
+// never appear inside a valid owner or skill segment, and the joined
+// filename always contains exactly one "@", at the boundary between the two
+// segments. That makes the join unambiguous for any pair of SEGMENT_RE-valid
+// values, including ones containing hyphens (e.g. owner="al-ice"/skill="bob"
+// joins to "al-ice@bob.md", which cannot also be produced by any other valid
+// owner/skill pair). "@" is a valid filename character on Linux, macOS, and
+// Windows.
 export const AGENTS_ROOT = join(".claude", "agents");
 export function agentPath(owner, skill) {
     return join(AGENTS_ROOT, `${owner}@${skill}.md`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",
@@ -26,7 +26,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/index.js",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "sync-readme": "node scripts/sync-readme.mjs"