akm docs

Bundle Author's Guide

This guide walks through building a bundle, making it discoverable, and sharing it so others can install it with akm bundle add. It assumes you already know what a bundle is; see Bundles for the concept and Reference: Asset Types for the full catalog of asset types, directory conventions, and per-type examples.

Create a Bundle

A bundle is just a directory of assets. akm classifies each asset by file extension and content, so directory names are hints, not requirements — a .sh file is a script whether it lives in scripts/, deploy/, or the bundle root, and nesting is fully supported.

mkdir my-bundle && cd my-bundle
mkdir scripts skills commands agents knowledge
# add your assets, then verify locally
akm bundle add .
akm index
akm search "deploy"

For the preferred directory layout, the full set of supported asset types (scripts, skills, commands, agents, knowledge, memories, workflows, tasks, env files, and more), and worked examples of each, see Reference: Asset Types.

Add a .meta/ directory at the bundle root to orient readers to the bundle as a whole — what it's for, where to start, conventions to follow. .meta/ is a dot-directory, so the indexer skips it: these docs never appear in akm search and never compete for ranking. They're read directly with akm show meta[:<name>] (or akm show <bundle>//meta[:<name>] once installed). See Reference: Asset Types for the .meta/ layout and an example index.md.

Write Metadata for Discovery

Metadata is not documentation for humans skimming your repo — it is the signal an agent's search ranking runs on. Write descriptions that describe what the asset does and when to reach for it, not just what it's named.

Prefer metadata that travels with the asset itself, so it can't drift out of sync with the code:

If you still have a legacy .stash.json sidecar, migrate its fields into inline metadata before publishing — see the v0.7 → v0.8 migration guide for the full field mapping and a worked example.

Keep show payloads focused. akm show returns the whole asset body by default (the whole document for a knowledge asset, the whole SKILL.md for a skill). An agent that calls show pays for every token you put in that payload. Split long reference material into headed sections so agents can request one slug at a time (akm show knowledge/guide#rate-limits) instead of the entire document, and keep skills and commands scoped to one task rather than a bundle of unrelated instructions.

Separate reusable instructions from project-specific memory. Skills, commands, and agents should describe how to do something in a way that holds up across projects. Anything that's true only for this project or this run — a decision made in a retro, a fact about the current deployment, a lesson learned from a failure — belongs in memories/, facts/, or lessons/, not baked into a skill's instructions. Mixing the two makes the reusable asset harder to reuse elsewhere and makes the project-specific context harder to find and prune later.

Give scripts and workflows explicit safety and parameter metadata. AKM retrieves every supported capability type, but it only orchestrates execution surfaces it can reason about — scripts run through @run/@setup/@cwd declarations, workflows through their declared steps. Undocumented parameters or missing execution hints don't make an asset safer to skip; they make it a worse citizen of that boundary, forcing an agent (or a human) to guess what a script does before running it. Document every parameter with @param, declare the interpreter and working directory explicitly, and describe destructive or irreversible steps in the body text.

Test Before You Publish

Before sharing, install your bundle locally and confirm the assets are both present and findable:

# Install from the local directory
akm bundle add ./my-bundle
akm bundle list

# Exact-name lookups
akm show scripts/deploy.sh

# Realistic queries -- not just the asset's own name
akm search "ship a release"
akm curate "deploy the app to staging"

Testing only exact-name search hides ranking problems your users will hit immediately: someone looking for "deploy" won't necessarily type deploy.sh. Search with the phrasing you expect users (and agents) to actually use, and with akm curate for task-shaped queries. If results are poor or your asset doesn't surface, improve the description, tags, and search hints rather than renaming the file to match the query.

Run akm lint before you publish. It catches structural problems (missing name/type on commands and agents, broken refs, malformed workflow structure, invalid task YAML) as well as the dangerous-env-key scan described in Env Security below.

akm lint

Version Bundles and Document Compatibility

Use npm versions or GitHub releases so users can pin to a known-good state instead of tracking your default branch:

akm bundle add npm:pkg@1.2.3
akm bundle add github:owner/repo#v1.2.3

Note in your README.md which akm-cli version(s) your bundle targets, especially if you rely on a feature that shipped recently (a new asset type, a frontmatter field, a lint rule). Breaking changes to your own bundle's layout deserve the same treatment you'd want from akm itself: a note in your changelog and, if the change is large, a short migration note for anyone pinned to the old layout.

Design for Local Customization

Users are expected to fork individual assets out of your bundle rather than edit your source tree directly. akm clone copies one asset (or, for a skill, its whole directory) into the user's writable bundle or a custom --dest, and the local copy wins in subsequent searches from that point forward:

akm clone scripts/deploy.sh
akm clone scripts/deploy.sh --dest ./project/.claude

Design assets so a clone-and-edit workflow actually works: keep parameters and setup steps explicit rather than hard-coded, avoid assumptions about paths outside the bundle, and prefer one asset per concern so a user can clone the one thing they need to change without dragging in unrelated behavior. See akm clone for the full command reference.

Publish Your Bundle

Detailed, provider-by-provider behavior for akm bundle add (git, npm, filesystem, website) lives in Bundles; the summaries below cover only what changes when you're the one publishing.

Sharing on GitHub

  1. Push your bundle to a GitHub repository.
  2. Add the akm-stash topic to your repo so it appears in registry search (gh repo edit --add-topic akm-stash, or from repository settings under "Topics").
  3. Others can now install it: akm bundle add github:your-username/my-bundle.
  4. To pin a version, tag a release and install with a #ref: akm bundle add github:your-username/my-bundle#v1.0.0. Installs are git-based — an unpinned add tracks the default branch, a #ref pins that tag/branch/commit — and the latest-release tarball is used only as a fallback when git access fails.

Sharing on npm

  1. Add a package.json with "akm-stash" in keywords.

  2. If your repo contains files that shouldn't ship (source, tests, CI config), use akm.include to declare which paths to publish:

    {
  "name": "@your-scope/my-bundle",
  "version": "1.0.0",
  "keywords": ["akm-stash"],
  "akm": { "include": ["scripts", "skills", "knowledge", ".meta"] }
}

    Paths are relative to package.json; only listed directories/files are copied into the install cache, and .git is always excluded. Remember to include .meta explicitly — dot-directories are otherwise easy to leave out of a published tarball (a GitHub tarball install includes .meta/ automatically, without needing an allowlist).

  3. npm publish --access public.

  4. Others can now install it: akm bundle add @your-scope/my-bundle.

Sharing on a Network Directory

For teams sharing assets without a registry, mount a bundle directly:

akm bundle add /mnt/shared/team-bundle

Assets appear in search results immediately, no further install step needed. See Bundles for adding a mounted source to ~/.config/akm/config.json directly, and for write-safety behavior when a mounted or git bundle is marked writable.

Submitting to the Registry

The official akm-registry lists your bundle three ways: an npm package with akm-stash in keywords, the akm-stash GitHub topic on your repo, or a PR against manual-entries.json for a curated entry or override. Auto-discovered entries merge into index.json on the registry's build cycle; curated entries are reviewed before inclusion. For the registry's entry schema and how auto-discovered and curated entries are reconciled, see Reference: Registry.

CLI-based submission (akm driving the PR) is planned for a future release.

Write-Safety Expectations

Publishing a bundle does not make it writable by default. akm bundle add installs git, npm, and website bundles read-only unless the source is explicitly marked writable (filesystem sources are the exception — local directories are writable by default, opt out with writable: false), and only the primary bundle or a source resolved as writable accepts changes back (via akm sync, akm clone --dest, or akm remember --bundle). If you're publishing a bundle you expect other teams to write back into — not just install and read — say so in your README.md and document the writable: true configuration your users need. See akm sync for exactly what gets committed and when a push happens.

Env Security

The vault asset type was removed in 0.9.0; env replaces it. See the 0.8 → 0.9 migration guide.

If your bundle includes env files under env/, be aware of how akm handles them during install.

Dangerous key detection. akm bundle add and akm lint scan env files for environment variable names that can be used to hijack process execution when the file is loaded via akm env run. The flagged names include LD_PRELOAD, PATH, DYLD_INSERT_LIBRARIES, NODE_OPTIONS, and 37 others (41 literal keys total), plus two pattern-based families (BASH_FUNC_*, Shellshock-class injection; GIT_CONFIG_*, git config override injection). When these keys are found, akm bundle add pauses in interactive mode and asks the user to confirm before continuing. In non-interactive (CI) mode the install fails unless the user passes --allow-dangerous-env-keys. akm env run applies the same scan at run time: a third-party-sourced bundle is refused unless that reviewed run explicitly passes --allow-dangerous-env-keys; a first-party bundle warns and proceeds.

This is not a ban — it is a speed bump. If your bundle legitimately needs one of these keys (for example, a PATH override for a hermetic toolchain), do the following before publishing:

  1. Document the reason clearly in your README.md. Explain which key is set, why it is needed, and what the value does.

  2. Run akm lint against your bundle locally to see the dangerous-env-key findings before your users do (suppress a specific key with a # akm-lint-ok: dangerous-env-key comment on the preceding line):

    akm lint

  3. Consider whether the value can be set by the user after install rather than shipped in the env file. Env files that ship without values — just key names and comments — do not trigger the audit.

Key names are metadata, not secrets. Env key names appear in akm env list and search results by design. Only values are protected. The --sensitive flag on akm env create excludes a file from both env list output and the search index; its key names then surface only when the file is shown directly by ref.

Bundle Structure Tips