akm-cli 0.0.18 → 0.0.20

package/README.md

@@ -10,167 +10,97 @@ A package manager for AI agent capabilities -- scripts, skills, commands,
 agents, and knowledge -- that works with any AI coding assistant that can run
 shell commands.
 
-`akm` organizes reusable scripts, prompts, and agent configs into a searchable
-**stash**, shares them as installable **kits** via **registries**, and gives
-any model a way to discover and use them. No plugins required -- just CLI
-output any tool-calling model can read.
+## Install
 
-## Requirements
+```sh
+# Standalone binary (no runtime dependencies)
+curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash
 
-`akm` requires [Bun](https://bun.sh) v1.0+ as its runtime. It uses Bun-specific
-APIs (`bun:sqlite`) that are **not available in Node.js**.
+# Or via Bun
+bun install -g akm-cli
+```
 
-> **Don't want Bun?** Use the [standalone binary](#standalone-binary) instead -- it
-> bundles everything and has no runtime dependencies.
+Upgrade in place with `akm upgrade`.
 
 ## Quick Start
 
 ```sh
-# Install (requires Bun v1.0+)
-bun install -g akm-cli
-
-# Initialize your stash
-akm init
-
-# Add a kit from GitHub
-akm add github:owner/repo
-
-# Clone an asset to a specific directory
-akm clone script:deploy.sh --dest ./project/.claude
-
-# Search for assets
-akm search "deploy"
-
-# Show an asset
-akm show script:deploy.sh
+akm init                          # Initialize your stash
+akm add github:owner/repo         # Add a kit from GitHub
+akm search "deploy"               # Find assets
+akm show script:deploy.sh         # View details and run command
 ```
 
-## Works Any AI Agent
-
-`akm` is platform agnostic. Any model that can execute shell commands can search
-your stash and use what it finds. The workflow is three commands:
-
-1. `akm search "what you need"` -- find relevant assets (returns JSON by default)
-2. `akm show <ref>` -- get the details (run command, instructions, prompt, etc.)
-3. Use the asset -- execute the `run` command, follow the skill instructions, fill in the template
+## Features
 
-### Drop-in prompt snippet
+### Works with Any AI Agent
 
-Add this to your `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, system prompt, or any instruction
-file to give your agent access to your stash without any additional setup:
+Any model that can run shell commands can use `akm`. Add this to your
+`AGENTS.md`, `CLAUDE.md`, or system prompt:
 
 ~~~markdown
 ## Resources & Capabilities
 
-You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via the `akm` CLI. Use it to find and use capabilities before writing something from scratch. Always search the stash first when you need a capability.
-
-Use `akm -h` for more information about searching and using assets.
+You have access to a searchable library of scripts, skills, commands, agents,
+and knowledge documents via the `akm` CLI. Use `akm -h` for details.
 ~~~
 
-That's it. No plugin, no SDK, no integration code. The model reads the JSON
-output from `akm` and acts on it. If you would like more detailed instructions, check out the example [AGENTS.md](docs/AGENTS.md)
-
-### Platform plugins (optional)
+No plugins, SDKs, or integration code required. Platform-specific plugins
+(e.g., [OpenCode](https://github.com/itlackey/akm-plugins?tab=readme-ov-file#opencode))
+are available for tighter integration but purely optional.
 
-For tighter integration, plugins are available for some platforms. These add
-native tool bindings so the agent doesn't need to shell out, but they're
-purely optional -- the CLI works everywhere.
+### Clone Assets Anywhere
 
-**OpenCode** -- Add the [OpenCode plugin](https://github.com/itlackey/akm-plugins?tab=readme-ov-file#opencode) to your `opencode.json`:
-
-```json
-{
-  "plugin": ["akm-opencode"]
-}
-```
-
-**Claude Code** -- Add the prompt snippet above to your `CLAUDE.md` or
-project instructions. Claude Code can run `akm` commands directly.
-
-**Everything else** -- If your agent can run shell commands, it can use `akm`.
-Add the prompt snippet above or in [AGENTS.md](docs/AGENTS.md) to whatever instruction/rules mechanism your platform uses.
-
-## The Stash
-
-Your stash is the local library where assets live. It combines three sources
-in priority order:
-
-1. **Primary stash** -- Your personal assets (`AKM_STASH_DIR`), created by `akm init`
-2. **Search paths** -- Additional directories (team shares, project dirs, etc.)
-3. **Installed kits** -- Kits from npm, GitHub, or git via `akm add` (cache-managed)
-
-The first match wins, so local assets always override installed ones. Use
-`akm clone` to fork an installed asset into your stash for editing.
-
-## Registries
-
-Registries are indexes of available kits. akm ships with the official
-[akm-registry](https://github.com/itlackey/akm-registry) pre-configured.
+`akm clone` copies any asset from your stash or a remote source into a
+target directory for local editing:
 
 ```sh
-# Search the official registry
-akm registry search "code review"
-
-# Add a third-party registry
-akm registry add https://example.com/registry/index.json --name team
-
-# List configured registries
-akm registry list
+akm clone script:deploy.sh                              # Clone to your stash
+akm clone script:deploy.sh --dest ./project/.claude     # Clone to a specific directory
+akm clone script:deploy.sh --name my-deploy.sh          # Clone with a new name
+akm clone "npm:@scope/pkg//script:deploy.sh" --force    # Clone from a remote package
 ```
 
-See the [Registry docs](docs/registry.md) for hosting your own registry,
-the v2 index format with asset-level metadata, and more.
+Key behaviors:
+- Type subdirectories are appended automatically (e.g., `--dest ./project/.claude` becomes `./project/.claude/scripts/deploy.sh`)
+- Skills clone as entire directories; scripts/commands clone as single files
+- Remote packages are fetched on-demand without registering as installed kits
+- `--force` overwrites existing assets
 
-## Searching and Showing Assets
+### skills.sh Integration
 
-Search returns brief JSON by default. Use `--detail normal` or `--detail full`
-when you want origin, tags, or explainability metadata:
+`akm` includes [skills.sh](https://skills.sh) as a built-in registry. Community
+skills from skills.sh are searchable out of the box alongside the official
+registry -- no setup required:
 
 ```sh
-akm search "docker" --type script
+akm search "code review"             # Searches skills.sh and official registry
+akm registry search "code review"    # Search registries directly
 ```
 
-```json
-{
-  "hits": [
-    {
-      "name": "docker-build",
-      "type": "script",
-      "description": "Build and push Docker images",
-      "action": "akm show script:docker-build.sh -> execute the run command"
-    }
-  ]
-}
-```
+Results include install counts and link back to skills.sh for details. The
+provider caches queries for 15 minutes with a 24-hour stale fallback.
 
-Show returns everything the agent needs to act:
+### Registries and Private Registry Support
 
-```sh
-akm show script:docker-build.sh
-```
-
-```json
-{
-  "type": "script",
-  "name": "docker-build.sh",
-  "origin": null,
-  "action": "Execute the run command below",
-  "run": "bash /path/to/scripts/docker-build.sh",
-  "setup": "bun install",
-  "cwd": "/path/to/scripts"
-}
-```
-
-For knowledge assets, navigate without loading the entire document:
+Registries are indexes of available kits. The official
+[akm-registry](https://github.com/itlackey/akm-registry) is pre-configured.
 
 ```sh
-akm show knowledge:api-guide toc
-akm show knowledge:api-guide section "Authentication"
+akm registry search "code review"                                        # Search registries
+akm registry add https://example.com/registry/index.json --name team     # Add a registry
+akm registry list                                                        # List configured registries
 ```
 
-## Installing and Sharing Kits
+Private access is supported through:
+- **GitHub tokens** -- Set `GITHUB_TOKEN` to access private GitHub repos when installing kits
+- **Provider options** -- Each registry entry supports an `options` field for provider-specific configuration (tokens, custom headers)
+- **Pluggable providers** -- Custom registry providers can implement their own authentication
+
+See the [Registry docs](docs/registry.md) for hosting your own registry and
+the v2 index format.
 
-Install kits from npm, GitHub, any git host, or local directories:
+### Install Kits from Anywhere
 
 ```sh
 akm add @scope/my-kit                       # npm
@@ -179,75 +109,27 @@ akm add git+https://gitlab.com/org/kit      # Any git repo
 akm add ./path/to/local/kit                 # Local directory
 ```
 
-Manage installed kits:
-
-```sh
-akm list                        # Show installed kits with status
-akm update --all                # Update all (reports version changes)
-akm remove owner/repo           # Remove and reindex
-akm clone script:deploy.sh      # Fork an asset into your stash for editing
-```
+Manage kits with `akm list`, `akm update --all`, and `akm remove`.
 
-### Publishing your own kit
+### Publish Your Own Kit
 
-1. Organize your assets (directory conventions are optional)
-2. Add `"akm"` to `keywords` in `package.json` or add the `akm` topic to your GitHub repo
+1. Organize your assets into a directory
+2. Add `"akm"` to `keywords` in `package.json` or the `akm` topic to your GitHub repo
 3. Optionally add `akm.include` in `package.json` to control what gets installed
 4. Publish to npm or push to GitHub
 
 See the [Kit Maker's Guide](docs/kit-makers.md) for a full walkthrough.
 
-## Installation
-
-`akm` requires [Bun](https://bun.sh) v1.0+ as its runtime. It uses Bun-specific
-APIs (`bun:sqlite`) that are not available in Node.js.
-
-```sh
-# Install Bun if you don't have it
-curl -fsSL https://bun.sh/install | bash
-
-# Install akm
-bun install -g akm-cli
-```
-
-### Standalone binary
-
-The standalone binary bundles everything and has **no runtime dependencies** --
-no Bun, no Node.js.
-
-```sh
-# macOS / Linux
-curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash
-
-# Windows (PowerShell)
-irm https://raw.githubusercontent.com/itlackey/agentikit/main/install.ps1 -OutFile install.ps1; ./install.ps1
-```
-
-The shell installer verifies the binary against release checksums.
-
-Upgrade the binary in place:
-
-```sh
-akm upgrade           # Download and replace the running binary
-akm upgrade --check   # Check for updates without installing
-```
-
 ## Documentation
 
 | Doc | Description |
 | --- | --- |
 | [Getting Started](docs/getting-started.md) | Quick setup guide |
-| [CLI Reference](docs/cli.md) | All `akm` commands and flags |
-| [Configuration](docs/configuration.md) | Providers, settings, and Ollama setup |
-| [Concepts](docs/concepts.md) | Asset types, classification, stash sources, metadata |
-| [Kit Maker's Guide](docs/kit-makers.md) | Build and share a kit on GitHub, npm, or a network share |
-| [Registry](docs/registry.md) | Registries, search, and managing kits |
-
-## Status
-
-`akm` is approaching v1.0. The core CLI, stash model, and registry are generally stable
-and in daily use. Feedback, issues, and PRs welcome -- especially around
-real-world usage patterns and integrations with different AI coding assistants.
+| [CLI Reference](docs/cli.md) | All commands and flags |
+| [Configuration](docs/configuration.md) | Settings, providers, and Ollama setup |
+| [Concepts](docs/concepts.md) | Asset types, classification, stash model |
+| [Kit Maker's Guide](docs/kit-makers.md) | Build and share kits |
+| [Registry](docs/registry.md) | Registries, search, and the v2 index format |
 
 ## License
 

package/dist/common.js

@@ -147,6 +147,12 @@ export async function fetchWithTimeout(url, opts, timeoutMs = 30_000) {
     try {
         return await fetch(url, { ...opts, signal: controller.signal });
     }
+    catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") {
+            throw new Error(`Request timed out after ${timeoutMs}ms: ${url}`);
+        }
+        throw err;
+    }
     finally {
         clearTimeout(timer);
     }

package/dist/config.js

@@ -5,7 +5,10 @@ import { getConfigDir as _getConfigDir, getConfigPath as _getConfigPath } from "
 export const DEFAULT_CONFIG = {
     semanticSearch: true,
     searchPaths: [],
-    registries: [{ url: "https://raw.githubusercontent.com/itlackey/akm-registry/main/index.json", name: "official" }],
+    registries: [
+        { url: "https://raw.githubusercontent.com/itlackey/akm-registry/main/index.json", name: "official" },
+        { url: "https://skills.sh", name: "skills.sh", provider: "skills-sh" },
+    ],
     output: {
         format: "json",
         detail: "brief",

package/dist/db.js

@@ -180,6 +180,15 @@ export function upsertEntry(db, entryKey, dirPath, filePath, stashDir, entry, se
 }
 export function deleteEntriesByDir(db, dirPath) {
     const ids = db.prepare("SELECT id FROM entries WHERE dir_path = ?").all(dirPath);
+    deleteRelatedRows(db, ids);
+    db.prepare("DELETE FROM entries WHERE dir_path = ?").run(dirPath);
+}
+export function deleteEntriesByStashDir(db, stashDir) {
+    const ids = db.prepare("SELECT id FROM entries WHERE stash_dir = ?").all(stashDir);
+    deleteRelatedRows(db, ids);
+    db.prepare("DELETE FROM entries WHERE stash_dir = ?").run(stashDir);
+}
+function deleteRelatedRows(db, ids) {
     for (const { id } of ids) {
         try {
             db.prepare("DELETE FROM embeddings WHERE id = ?").run(id);
@@ -196,7 +205,6 @@ export function deleteEntriesByDir(db, dirPath) {
             }
         }
     }
-    db.prepare("DELETE FROM entries WHERE dir_path = ?").run(dirPath);
 }
 export function rebuildFts(db) {
     db.exec("DELETE FROM entries_fts");

package/dist/indexer.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { resolveStashDir } from "./common";
-import { closeDatabase, DB_VERSION, deleteEntriesByDir, getEntriesByDir, getEntryCount, getMeta, isVecAvailable, openDatabase, rebuildFts, setMeta, upsertEmbedding, upsertEntry, warnIfVecMissing, } from "./db";
+import { closeDatabase, DB_VERSION, deleteEntriesByDir, deleteEntriesByStashDir, getEntriesByDir, getEntryCount, getMeta, isVecAvailable, openDatabase, rebuildFts, setMeta, upsertEmbedding, upsertEntry, warnIfVecMissing, } from "./db";
 import { generateMetadataFlat, loadStashFile } from "./metadata";
 import { getDbPath } from "./paths";
 import { walkStashFlat } from "./walker";
@@ -45,6 +45,20 @@ export async function agentikitIndex(options) {
             db.exec("DELETE FROM entries_fts");
             db.exec("DELETE FROM entries");
         }
+        else {
+            // Incremental: purge entries from stash dirs that have been removed
+            // (e.g. after `akm remove`) so orphaned entries don't linger.
+            const prevStashDirsJson = getMeta(db, "stashDirs");
+            if (prevStashDirsJson) {
+                const prevStashDirs = JSON.parse(prevStashDirsJson);
+                const currentSet = new Set(allStashDirs);
+                for (const dir of prevStashDirs) {
+                    if (!currentSet.has(dir)) {
+                        deleteEntriesByStashDir(db, dir);
+                    }
+                }
+            }
+        }
         const tWalkStart = Date.now();
         // Walk stash dirs and index entries
         const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm } = indexEntries(db, allStashDirs, stashDir, isIncremental, builtAtMs);

package/dist/providers/skills-sh.js

@@ -75,6 +75,7 @@ class SkillsShProvider {
                 id: `skills-sh:${entry.id}`,
                 title: entry.name,
                 ref: entry.source,
+                installRef: `github:${entry.source}`,
                 homepage: `${baseUrl}/${entry.id}`,
                 score,
                 metadata: {

package/dist/providers/static-index.js

@@ -219,6 +219,7 @@ function toSearchHit(kit, score, registryName) {
         title: kit.name,
         description: kit.description,
         ref: kit.ref,
+        installRef: buildInstallRef(kit.source, kit.ref),
         homepage: kit.homepage,
         score: Math.round(score * 1000) / 1000,
         metadata,
@@ -260,13 +261,7 @@ function scoreAssets(kits, query, limit) {
     for (const { kit, registryName } of kits) {
         if (!kit.assets || kit.assets.length === 0)
             continue;
-        const installRef = kit.source === "npm"
-            ? `npm:${kit.ref}`
-            : kit.source === "git"
-                ? `git+${kit.ref}`
-                : kit.source === "local"
-                    ? kit.ref
-                    : `github:${kit.ref}`;
+        const installRef = buildInstallRef(kit.source, kit.ref);
         for (const asset of kit.assets) {
             const score = scoreAsset(asset, tokens);
             if (score > 0) {
@@ -335,6 +330,18 @@ function asStringArray(value) {
     const filtered = value.filter((v) => typeof v === "string");
     return filtered.length > 0 ? filtered : undefined;
 }
+function buildInstallRef(source, ref) {
+    switch (source) {
+        case "npm":
+            return `npm:${ref}`;
+        case "git":
+            return `git+${ref}`;
+        case "local":
+            return ref;
+        default:
+            return `github:${ref}`;
+    }
+}
 function toErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/registry-resolve.js

@@ -9,6 +9,12 @@ export function parseRegistryRef(rawRef) {
     const ref = rawRef.trim();
     if (!ref)
         throw new Error("Registry ref is required.");
+    // Detect registry search result IDs (e.g. "skills-sh:org/skills/name")
+    // that are not installable refs. Known installable prefixes are handled below.
+    const registryIdHint = detectRegistrySearchId(ref);
+    if (registryIdHint) {
+        throw new Error(registryIdHint);
+    }
     if (ref.startsWith("npm:")) {
         return parseNpmRef(ref.slice(4), ref);
     }
@@ -33,6 +39,37 @@ export function parseRegistryRef(rawRef) {
     }
     return parseGithubShorthand(ref, ref);
 }
+/**
+ * Known prefixes that `parseRegistryRef` handles as installable sources.
+ * Anything with a colon that doesn't start with one of these is likely a
+ * registry search result ID (e.g. `skills-sh:org/skills/name`).
+ */
+const KNOWN_PREFIXES = ["npm:", "github:", "git+", "file:", "http://", "https://"];
+function detectRegistrySearchId(ref) {
+    const colonIdx = ref.indexOf(":");
+    if (colonIdx < 1)
+        return undefined;
+    // Skip known installable prefixes
+    for (const prefix of KNOWN_PREFIXES) {
+        if (ref.startsWith(prefix))
+            return undefined;
+    }
+    const prefix = ref.slice(0, colonIdx);
+    // Registry IDs use lowercase-with-hyphens prefixes (e.g. skills-sh, static-index)
+    if (!/^[a-z][a-z0-9-]*$/.test(prefix))
+        return undefined;
+    const rest = ref.slice(colonIdx + 1);
+    return [
+        `"${ref}" looks like a registry search result ID, not an installable ref.`,
+        `The "${prefix}:" prefix is a registry identifier and cannot be passed to \`akm add\`.`,
+        "",
+        "Use the installRef or ref field from the search result instead. For example:",
+        `  akm registry search "${rest}" --format json`,
+        "Then install using the installRef value from the result:",
+        "  akm add github:owner/repo",
+        "  akm add npm:package-name",
+    ].join("\n");
+}
 export async function resolveRegistryArtifact(parsed) {
     if (parsed.source === "npm") {
         return resolveNpmArtifact(parsed);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "type": "module",
   "description": "CLI tool to search, open, and run extension assets from an akm stash directory.",
   "keywords": [