Asset Types

Reference for the capability taxonomy the native akm adapter recognizes, the bundle directory layout, and the metadata every asset carries.

Contract

akm's own native format (the akm adapter) recognizes fourteen asset types: script, skill, command, agent, knowledge, instruction, env, secret, workflow, lesson, memory, task, session, and fact.
Scripts, knowledge, commands, agents, skills, and workflows are classified by file extension and content, not by directory name. A .sh file is a script whether it lives in scripts/, deploy/, or the bundle root; for these types the conventional directory names below are an opt-in convention that improves indexing confidence. The remaining types are directory-required: env, secret, memory, lesson, fact, session, task, and instruction assets are only discovered under their placement directories (a memory-shaped .md outside memories/ indexes as plain knowledge).
type is not part of an asset's ref — the placement subdirectory carries that signal. See Refs.
Ten additional bundle formats beyond akm's own (Claude Code and OpenCode tool directories, OKF, LLM wikis, and more) are recognized, indexed, and validated in place by their own adapters — see Bundle Types for the full type-by-type table (purpose, what the agent gets, and example ref) and the other-format read/write picture.

Directory layout

There's no required structure, but this skeleton is the opt-in convention:

my-bundle/
  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)
  instructions/   # Project guidance (.md)
  env/            # Environment files (.env) — groups of related config, loaded whole
  secrets/        # Secrets — one sensitive value per file (auth tokens, keys, certs)
  workflows/      # Peer workflow sources (.md and .yml)
  lessons/        # Distilled lessons (.md, see akm improve / proposals)
  memories/       # Recalled context fragments (.md, see Memory reference)
  facts/          # Durable bundle-level facts (.md)
  tasks/          # Task source v4 scheduled or on-demand automation (.yml only)
  sessions/       # Machine-placed indexed session summaries (.md)
  .meta/          # Optional bundle orientation, not indexed (see "Bundle orientation" below)

LLM Wikis are a related but separate concept: a wiki is its own installable bundle (akm bundle add github:team/research-wiki), not a type-subdirectory inside a regular bundle. See Wikis for how akm recognizes and indexes them.

Classification taxonomy

Scripts and knowledge are classified by what they are: a .sh file is a script; a plain .md file is knowledge. Commands and agents are classified by how an LLM should use them: a .md file with $ARGUMENTS placeholders is a command template; one with tools in its frontmatter is an agent definition. Workflow assets may be .md or .yml: Markdown is classified by type: workflow or placement, while the GitHub-shaped YAML adapter validates the closed workflow subset. These are peer workflow sources, not an md-only surface. Skills are a packaging convention: a directory containing a SKILL.md file.

See Classification for the full specificity-based matching system.

Metadata field reference

Metadata lives with the asset itself, not in a separate sidecar file: frontmatter for markdown assets, and structured comments for scripts. The indexer derives metadata from filenames, code comments, frontmatter, and package.json.

See Filesystem Layout for the full field reference.

Bundle orientation: the `.meta/` convention

A bundle may carry an optional .meta/ directory at its root holding human-authored orientation for the bundle as a whole — purpose, key assets, conventions, maintainer. This is distinct from per-asset metadata, which still lives with each asset: .meta/ never describes individual assets, only the bundle itself.

my-bundle/
  .meta/
    index.md          # shown by `akm show meta` — the default orientation doc
    about.md          # shown by `akm show meta:about`
    conventions.md     # shown by `akm show meta:conventions`

Because .meta/ is a dot-directory, the indexer skips it — these docs never appear in akm search and never compete for ranking. They are direct-read on demand:

akm show meta                       # working bundle's .meta/index.md
akm show meta:about                 # working bundle's .meta/about.md
akm show akm//meta                  # the primary bundle explicitly

akm show <origin>//meta:<name> resolves <name>.md first, then an extensionless <name>. The convention is open-ended: bundle owners add new docs by dropping files into .meta/ — no configuration or code changes required. akm bundle create scaffolds a starter .meta/index.md.

Known gap: an install-ref origin (akm show github:owner/repo//meta) does not currently resolve even for an installed bundle — origin resolution matches only derived installation ids, not raw install refs. Use akm//meta for the primary bundle, or the bundle key you gave it in bundles (config.json), not the original install ref.

Script execution (ExecHints)

For script assets, akm resolves execution hints in this order:

Header comment tags (@run, @setup, @cwd)
Auto-detection from extension and nearby dependency files

Defaults

Directory placement is advisory for scripts, knowledge, commands, agents, skills, and workflows; it is required for env, secret, memory, lesson, fact, session, task, and instruction discovery.
A memory asset with no source directory pointed at it is written to the working bundle by akm remember.
facts/ holds durable bundle-level facts, including the organization, backlink, and domain convention facts the bundle skeleton ships with (see Refs — namespacing).

Security / persistence implications

env and secret assets carry protected values: key names are discoverable, but values are never written to stdout, the index, or structured output. See STABILITY.md's "Protected env & secret values" entry for the exact contract and the safe injection path (akm env run / akm secret run).
All asset content is plain files inside the bundle directory — the search index (index.db) is a derived, regenerable cache rebuilt by akm index; it is never the source of truth for asset content.
akm lint only operates on writable sources, and akm improve on one of them: the bundle it writes to (--bundle, else defaultWriteTarget, else the working bundle). Read-only registry caches (git, npm, website) are excluded from improvement and lint passes even when they are indexed.

Stability

Per STABILITY.md: asset type is a free-form, open string — --type filtering is exact-match against an open set and deliberately unvalidated (an unrecognized type returns zero hits, not an error). The lesson asset type's schema (when_to_use, description) is stable, but its distillation triggers and ranking are Experimental tuning targets. See STABILITY.md for the full command- and surface-level tier index.