agentikit 0.0.13 → 0.0.15

package/README.md

@@ -1,91 +1,162 @@
 # Agent-i-Kit
 
-Agent-i-Kit gives AI coding agents a shared library of capabilities they can
-search and use. You organize tools, skills, commands, agents, knowledge, and
-scripts into a **stash**, and agents discover what they need through
-`akm` (Agent Kit Manager).
+[![npm version](https://img.shields.io/npm/v/agentikit)](https://www.npmjs.com/package/agentikit)
+[![CI](https://github.com/itlackey/agentikit/actions/workflows/ci.yml/badge.svg)](https://github.com/itlackey/agentikit/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/agentikit)](LICENSE)
 
-## What Is a Kit?
+A package manager for AI agent capabilities — tools, skills, commands, agents,
+knowledge, and scripts — that works with any AI coding assistant that can run
+shell commands.
 
-A kit is a shareable package of assets. Any directory with asset
-subdirectories is a valid kit:
+You build up useful scripts, prompts, and agent configs. Agent-i-Kit lets you
+organize them into a searchable **stash**, share them as installable **kits**,
+and give any model a way to discover and use them through `akm` (Agent Kit
+Manager). No plugins required — just CLI output any tool-calling model can read.
 
-```text
-my-kit/
-  tools/          # Executable scripts (.sh, .ts, .js)
-  skills/         # Skill definitions (directories with SKILL.md)
-  commands/       # Slash commands (.md)
-  agents/         # Agent definitions (.md)
-  knowledge/      # Reference documents (.md)
-  scripts/        # General scripts (.py, .rb, .go, etc.)
+## Requirements
+
+Agent-i-Kit requires [Bun](https://bun.sh) v1.0+ as its runtime. It uses
+Bun-specific APIs (`bun:sqlite`) that are **not available in Node.js**.
+
+## Quick Start
+
+```sh
+# Install (requires Bun v1.0+)
+bun install -g agentikit
+
+# Initialize your stash
+akm init
+
+# Add a kit from GitHub
+akm add github:owner/repo
+
+# Search for assets
+akm search "deploy"
+
+# Show an asset
+akm show script:deploy.sh
 ```
 
-Kits can be published to npm or hosted on GitHub. Tag them with `akm` or
-`agentikit` so others can discover them through registry search.
+> **Don't want Bun?** Use the [standalone binary](#standalone-binary) instead — it
+> bundles everything and has no runtime dependencies.
 
-## What Is a Stash?
+## Using With Any AI Agent
 
-The stash is your local library of assets. It combines three sources:
+Agent-i-Kit 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. **Working stash** -- Your personal assets (`AKM_STASH_DIR`). Read-write.
-2. **Mounted dirs** -- Shared team directories. Read-only.
-3. **Installed kits** -- Kits from npm or GitHub via `akm add`. Read-only.
+1. `akm search "what you need"` — find relevant assets (returns JSON)
+2. `akm show <openRef>` — get the details (run command, instructions, prompt, etc.)
+3. Use the asset — execute the `runCmd`, follow the skill instructions, fill in the template
 
-When you search or open an asset, the working stash takes priority. This
-means you can install a kit and override individual assets by cloning them
-into your working stash.
+### Drop-in prompt snippet
 
-## Prerequisites
+Add this to your `AGENTS.md`, `CLAUDE.md`, system prompt, or any instruction
+file to give your agent access to your stash without any additional setup:
 
-Agent-i-Kit requires [Bun](https://bun.sh) (v1.0+) as its runtime. It uses
-Bun-specific APIs (`bun:sqlite`) that are not available in Node.js.
+~~~markdown
 
+You have access to a searchable library of tools, skills, commands, agents,
+and knowledge documents via `akm`. Use it to find and
+use capabilities before writing something from scratch.
+
+**Finding assets:**
 ```sh
-# Install Bun if you don't have it
-curl -fsSL https://bun.sh/install | bash
+akm search "<query>"              # Search by keyword
+akm search "<query>" --type tool  # Filter by type (tool, skill, command, agent, knowledge, script)
 ```
 
-> **Don't want to install Bun?** Use the [standalone binary](#standalone-binary)
-> instead -- it has no runtime dependencies.
-
-## Quick Start
+Search returns JSON with scored results. Each hit includes an `openRef` you
+use to retrieve the full asset.
 
+**Using assets:**
 ```sh
-# Install
-bun install -g agentikit
+akm show <openRef>                # Get full asset details
+```
 
-# Initialize your stash
-akm init
+What you get back depends on the asset type:
+- **script/tool** — A `runCmd` you can execute directly
+- **skill** — Instructions to follow (read the full content)
+- **command** — A prompt template with placeholders to fill in
+- **agent** — A system prompt with model and tool hints
+- **knowledge** — A reference doc (use `--view toc` or `--view section --heading "..."` to navigate)
 
-# Search for assets
-akm search "deploy"
+Always search the stash first when you need a capability. Prefer existing
+assets over writing new code.
+~~~
 
-# Show an asset
-akm show tool:deploy.sh
+That's it. No plugin, no SDK, no integration code. The model reads the JSON
+output from `akm` and acts on it.
+
+### Platform plugins (optional)
 
-# Install a kit from npm
-akm add @scope/my-kit
+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.
 
-# Search installed and registry kits
-akm search "lint" --source both
+**OpenCode** — Add the [OpenCode plugin](https://github.com/itlackey/agentikit-plugins?tab=readme-ov-file#agentikit-opencode) to your `opencode.json`:
+
+```json
+{
+  "plugin": ["agentikit-opencode"]
+}
 ```
 
-### Standalone Binary
+**Claude Code** — Add the prompt snippet above to your `CLAUDE.md` or
+project instructions. Claude Code can run `akm` commands directly.
 
-The standalone binary bundles everything it needs and does **not** require Bun
-or Node.js.
+**Everything else** — If your agent can run shell commands, it can use `akm`.
+Add the prompt snippet to whatever instruction mechanism your platform uses.
 
-```sh
-# macOS / Linux
-curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash
+## What's In a Kit?
 
-# Windows (PowerShell)
-irm https://raw.githubusercontent.com/itlackey/agentikit/main/install.ps1 -OutFile install.ps1; ./install.ps1
+A kit is a directory of assets you can share and install. There's no required
+structure — agentikit classifies assets by **file extension and content**, not
+by directory name. A `.sh` file is a script whether it lives in `scripts/`,
+`deploy/`, or at the root. A `.md` file with `tools` in its frontmatter is an
+agent definition wherever you put it.
+
+That said, using these directory names as an opt-in convention improves
+indexing confidence:
+
+```text
+my-kit/
+  scripts/        # Executable scripts (.sh, .ts, .js, .py, .rb, .go, etc.)
+  skills/         # Skill definitions (directories with SKILL.md)
+  commands/       # Slash commands (.md with $ARGUMENTS or agent frontmatter)
+  agents/         # Agent definitions (.md with model/tools frontmatter)
+  knowledge/      # Reference documents (.md)
 ```
 
+### Asset types
+
+| Type | What it is | What the agent gets |
+| --- | --- | --- |
+| **script** | An executable script | A `runCmd` the agent can execute, or source for unsupported runtimes |
+| **skill** | A set of instructions | Step-by-step guidance the agent follows |
+| **command** | A prompt template | A template with placeholders to fill in |
+| **agent** | An agent definition | A system prompt, model hint, and tool policy |
+| **knowledge** | A reference document | Navigable content with TOC and section views |
+
+Assets are referenced by type and name (e.g. `script:deploy.sh`,
+`knowledge:api-guide.md`). See [Concepts](docs/concepts.md) for details on
+how classification works.
+
+## 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.
+
 ## Searching and Showing Assets
 
-Search returns scored results with metadata explaining why each hit matched:
+Search returns scored results with explainability:
 
 ```sh
 akm search "docker" --type tool
@@ -106,7 +177,7 @@ akm search "docker" --type tool
 }
 ```
 
-Use `openRef` from search results to show the full asset:
+Show returns everything the agent needs to act:
 
 ```sh
 akm show tool:docker-build.sh
@@ -121,97 +192,103 @@ akm show tool:docker-build.sh
 }
 ```
 
-For knowledge assets, views let you navigate large documents:
+For knowledge assets, navigate without loading the entire document:
 
 ```sh
 akm show knowledge:api-guide.md --view toc
 akm show knowledge:api-guide.md --view section --heading "Authentication"
 ```
 
-## Using With AI Agents
-
-Agent-i-Kit is designed to be called by AI coding agents. The agent searches
-for capabilities, reads the results, and acts on them.
-
-### OpenCode
+## Installing and Sharing Kits
 
-In an OpenCode project, add akm as a tool in your configuration. The agent
-can then search the stash and run tools directly:
+Install kits from npm, GitHub, any git host, or local directories:
 
-```text
-Search the stash for deployment tools, then run the best match.
+```sh
+akm add @scope/my-kit                       # npm
+akm add github:owner/repo#v1.2.3            # GitHub with tag
+akm add git+https://gitlab.com/org/kit      # Any git repo
+akm add ./path/to/local/kit                 # Local directory
 ```
 
-The agent calls `akm search "deploy" --type tool`, picks the top result,
-reads its `runCmd` from `akm show`, and executes it.
+Search the registry for community kits:
 
-### Claude Code
-
-Add akm commands as tools or reference them from your CLAUDE.md:
+```sh
+akm search "code review" --source registry
+```
 
-```markdown
-## Available Tools
+Manage installed kits:
 
-Use `akm search <query>` to find tools, skills, and commands in the stash.
-Use `akm show <ref>` to read asset details before using them.
+```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 tool:deploy.sh        # Fork an asset into your stash for editing
 ```
 
-### Any Agent
+### Publishing your own kit
 
-The JSON output from `akm search` and `akm show` is designed for machine
-consumption. Any agent that can run shell commands can use akm:
+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
+3. Optionally add `agentikit.include` to control what gets installed
+4. Publish to npm or push to GitHub
+5. Submit to the registry with `akm submit` to appear in `akm search --source registry`
 
-1. `akm search "what you need"` -- Find relevant assets
-2. `akm show <openRef>` -- Get the details
-3. Use the asset (run the `runCmd`, follow the skill instructions, etc.)
+See the [Kit Maker's Guide](docs/kit-makers.md) for a full walkthrough.
 
-## Installing Kits
+## Installation
 
-Install kits from npm, GitHub, or local directories:
+Agent-i-Kit 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
-akm add @scope/my-kit              # npm package
-akm add github:owner/repo          # GitHub repo
-akm add ./path/to/local/kit        # Local git directory
+# Install Bun if you don't have it
+curl -fsSL https://bun.sh/install | bash
+
+# Install agentikit
+bun install -g agentikit
 ```
 
-Search the registry to discover kits:
+### Standalone binary
+
+The standalone binary bundles everything and has **no runtime dependencies** —
+no Bun, no Node.js.
 
 ```sh
-akm search "code review" --source registry
-```
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash
 
-Only packages tagged with `akm` or `agentikit` appear in registry results.
-See [docs/registry.md](docs/registry.md) for details.
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/itlackey/agentikit/main/install.ps1 -OutFile install.ps1; ./install.ps1
+```
 
-## Publishing a Kit
+The shell installer verifies the binary against release checksums.
 
-1. Organize your assets into the standard directory structure
-2. Add `"akm"` to `keywords` in `package.json` (for npm) or add the `akm`
-   topic to your GitHub repo
-3. Optionally add an `agentikit.include` array in `package.json` to control
-   which paths are included when installed
+Upgrade the binary in place:
 
-```json
-{
-  "name": "@scope/my-kit",
-  "keywords": ["akm"],
-  "agentikit": {
-    "include": ["tools", "skills", "commands"]
-  }
-}
+```sh
+akm upgrade           # Download and replace the running binary
+akm upgrade --check   # Check for updates without installing
 ```
 
 ## Documentation
 
 | Doc | Description |
 | --- | --- |
-| [Concepts](docs/concepts.md) | Asset types, stash sources, metadata, tool execution |
-| [CLI Reference](docs/cli.md) | All akm commands and flags |
-| [Kit Maker's Guide](docs/kit-makers.md) | How to build and share a kit |
+| [Concepts](docs/concepts.md) | Asset types, classification, stash sources, metadata |
+| [CLI Reference](docs/cli.md) | All `akm` commands and flags |
+| [Kit Maker's Guide](docs/kit-makers.md) | Build and share a kit on GitHub, npm, or a network share |
 | [Registry](docs/registry.md) | Finding, installing, and publishing kits |
 | [Search](docs/search.md) | Hybrid search architecture and scoring |
 | [Indexing](docs/indexing.md) | How the search index is built |
 | [Filesystem](docs/filesystem.md) | Directory layout and `.stash.json` schema |
 | [Configuration](docs/configuration.md) | Providers, settings, and Ollama setup |
-| [Library API](docs/api.md) | Using agentikit as a TypeScript/JS library |
+
+## Status
+
+Agent-i-Kit is approaching v1.0. The core CLI, stash model, and registry are
+stable and in daily use. Feedback, issues, and PRs welcome — especially around
+real-world usage patterns and integrations with different AI coding assistants.
+
+## License
+
+[MPL-2.0](LICENSE)

package/dist/{src/asset-spec.js → asset-spec.js}

@@ -1,6 +1,6 @@
 import path from "node:path";
-import { toPosix } from "./common";
 import { tryGetHandler } from "./asset-type-handler";
+import { toPosix } from "./common";
 export const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"]);
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
@@ -10,7 +10,16 @@ const markdownSpec = {
 /** Extended set of script extensions for the script asset type */
 export const SCRIPT_EXTENSIONS_BROAD = new Set([
     ...SCRIPT_EXTENSIONS,
-    ".py", ".rb", ".go", ".pl", ".php", ".lua", ".r", ".swift", ".kt", ".kts",
+    ".py",
+    ".rb",
+    ".go",
+    ".pl",
+    ".php",
+    ".lua",
+    ".r",
+    ".swift",
+    ".kt",
+    ".kts",
 ]);
 export const ASSET_SPECS = {
     tool: {

package/dist/{src/asset-type-handler.js → asset-type-handler.js}

@@ -1,3 +1,5 @@
+import { UsageError } from "./errors";
+import { registerBuiltinHandlers } from "./handlers/index";
 // ── Registry ─────────────────────────────────────────────────────────────────
 const handlers = new Map();
 let handlersInitialized = false;
@@ -5,8 +7,7 @@ function ensureHandlersRegistered() {
     if (handlersInitialized)
         return;
     handlersInitialized = true;
-    // Import handler registrations
-    require("./handlers/index");
+    registerBuiltinHandlers();
 }
 export function registerAssetType(handler) {
     handlers.set(handler.typeName, handler);
@@ -15,7 +16,7 @@ export function getHandler(type) {
     ensureHandlersRegistered();
     const handler = handlers.get(type);
     if (!handler) {
-        throw new Error(`Unknown asset type: "${type}"`);
+        throw new UsageError(`Unknown asset type: "${type}"`);
     }
     return handler;
 }