elizaos--eliza/packages/skills/CLAUDE.md

@elizaos/skills

Bundled skills library and skill loading utilities for elizaOS agents.

Purpose

This package ships 34 bundled skills (markdown instruction files) and the TypeScript API for discovering, loading, and formatting them. The agent runtime (packages/agent, runtime/eliza.ts) calls getSkillsDir() at startup to locate the bundled skills directory; @elizaos/plugin-agent-skills (api/skill-discovery-helpers.ts) also calls getSkillsDir() to scan bundled skills. getSkillsDir is the only symbol consumers import from this package today.

This package is not a plugin — it exports pure utility functions and the bundled skill files. It does not register actions, providers, or services.

Layout

packages/skills/
  src/
    index.ts          — re-exports all public API
    types.ts          — all shared TypeScript types (Skill, SkillEntry, SkillFrontmatter, etc.)
    loader.ts         — loadSkills(), loadSkillsFromDir(), loadSkillEntries()
    resolver.ts       — getSkillsDir(), getCuratedActiveDir(), getProposedSkillsDir(), promoteSkill()
    frontmatter.ts    — parseFrontmatter(), resolveSkillMetadata(), resolveSkillProvenance(), serializeSkillFile()
    formatter.ts      — formatSkillsForPrompt(), formatSkillEntriesForPrompt(), buildSkillCommandSpecs()
  skills/             — 34 bundled skill directories, each with a SKILL.md
  test/               — formatter.test.ts, frontmatter.test.ts, provenance.test.ts, resolver.test.ts

Key Exports

import {
  // Discovery
  getSkillsDir,           // absolute path to the bundled skills/ directory
  getCuratedActiveDir,    // <stateDir>/skills/curated/active (loaded at runtime)
  getProposedSkillsDir,   // <stateDir>/skills/curated/proposed (staged for review, NOT loaded)
  promoteSkill,           // move a proposed skill to active atomically
  clearSkillsDirCache,    // reset the bundled-dir resolution cache

  // Loading
  loadSkills,             // load from all default locations; returns { skills, diagnostics }
  loadSkillsFromDir,      // load from a single directory
  loadSkillEntries,       // loadSkills + full frontmatter/metadata parsed into SkillEntry[]

  // Formatting
  formatSkillsForPrompt,        // format Skill[] into system-prompt text block
  formatSkillEntriesForPrompt,  // same but from SkillEntry[] (respects invocation policy)
  buildSkillCommandSpecs,       // build SkillCommandSpec[] for chat UI command dispatch
  formatSkillSummary,           // single "name: description" string
  formatSkillsList,             // newline-joined list

  // Frontmatter
  parseFrontmatter,             // parse YAML frontmatter from markdown string
  stripFrontmatter,             // return body without frontmatter
  serializeSkillFile,           // re-serialize frontmatter + body (used by learning loop)
  resolveSkillMetadata,
  resolveSkillInvocationPolicy,
  resolveSkillProvenance,
} from "@elizaos/skills";

Skill Discovery Precedence

loadSkills() merges from these sources in order (later overrides earlier on name collision):

1. bundled — getSkillsDir() (this package's skills/)
2. managed — <stateDir>/skills/
3. curated/active — <stateDir>/skills/curated/active/ (human-promoted or agent-promoted)
4. project — <cwd>/.elizaos/skills/
5. explicit paths — skillPaths option

curated/proposed/ is staged and never loaded automatically.

Skill File Format

Every skill lives in its own directory with a SKILL.md:

---
name: my-skill          # must match directory name; lowercase a-z 0-9 hyphens only
description: "..."      # required; max 1024 chars
disable-model-invocation: false   # if true, excluded from system prompt
user-invocable: true              # if false, cannot be triggered via /commands
primary-env: node                 # optional runtime hint
required-bins: [node, npm]        # optional; surfaced in SkillMetadata
required-env: [MY_VAR]            # optional
command-dispatch: tool            # optional; enables tool-dispatch in buildSkillCommandSpecs
command-tool: USE_SKILL           # tool name when command-dispatch: tool
---

Body markdown — detailed instructions for the agent.

The root skills/ directory can also hold flat .md files (loaded as root-level skills); subdirectories must use SKILL.md.

Commands

bun run --cwd packages/skills build       # tsc compile to dist/
bun run --cwd packages/skills dev         # tsc watch
bun run --cwd packages/skills test        # run test/
bun run --cwd packages/skills lint        # biome check --write src/
bun run --cwd packages/skills lint:check  # biome check src/ (no write)
bun run --cwd packages/skills clean       # rm -rf dist

Config / Env Vars

Variable	Effect
ELIZAOS_BUNDLED_SKILLS_DIR	Override the bundled skills directory resolution

resolveStateDir() from @elizaos/core controls the managed/curated skill locations; it honors ELIZA_STATE_DIR.

Adding a Bundled Skill

1. Create skills/<your-skill-name>/SKILL.md with valid frontmatter (name matching the dir, description required).
2. Add any reference docs as sibling files (e.g. skills/<name>/references/).
3. The skill is picked up by loadSkills() automatically — no code changes needed.
4. If the skill should be excluded from system-prompt injection but still loadable, set disable-model-invocation: true.
5. If users should not be able to invoke it via slash-commands, set user-invocable: false.

Conventions and Gotchas

• Name must equal directory name. The loader validates this and warns on mismatch. Names are lowercase [a-z0-9-]+, max 64 chars, no leading/trailing/consecutive hyphens.
• Description is required. A skill with a missing or blank description is silently dropped by the loader.
• Curated learning loop. Agent-generated skills land in curated/proposed/ and require human promotion via promoteSkill(name) (or the Settings UI) before they load. This prevents untrusted agent output from injecting itself into the prompt.
• Symlinks are resolved. The loader follows symlinks using statSync; duplicate real paths are deduplicated.
• serializeSkillFile is for the learning loop. Call it to rewrite a SKILL.md after refining provenance/content. It serializes frontmatter as YAML and preserves the body.
• buildSkillCommandSpecs sanitizes names. Command names are lowercased, non-alphanumeric chars replaced with underscores, and truncated to 32 chars. Collisions get a numeric suffix.
• No circular deps. This package depends only on @elizaos/core (for resolveStateDir) and yaml. Do not add dependencies on agent or plugin packages.

⛔ NON-NEGOTIABLE — evidence, trajectories & real end-to-end tests

The binding, repo-wide standard is AGENTS.md. Read it. Nothing in this package is done until it is proven done — a reviewer must confirm it works without reading the code, from the artifacts you attach. This applies to every feature, fix, refactor, and chore here. "Tests pass" is not proof; "CI is green" is not proof.

• Record AND read model trajectories. Capture the actual inputs and outputs of the model from a live LLM — not the deterministic proxy, not a mock: the prompt, the providers/context, the raw model output, every tool/action call, and the result. Then open the trajectory and review it by hand. A captured-but-unread trajectory is not evidence (packages/scenario-runner/bin/eliza-scenarios run <scenario> --report <out>).
• Real, full-featured E2E — no larp. Every feature ships detailed end-to-end tests that drive the real path end to end. Not the happy "front door" only: cover error paths, edge/empty/invalid input, concurrency, roles/permissions, and adversarial input. A test that asserts against a mock/stub/fixture standing in for the thing under test does not count. If the real model/device/chain/connector/account is hard to reach, make it reachable — that is the work, not an excuse to mock. If the existing tests here are shallow or mocked, fixing them is part of your change.
• Screenshots + logs at every phase, plus a complete walkthrough video/run-through of the entire feature or view, start to finish (bun run test:e2e:record).
• Manually review every artifact the change touches — never just the green check: client logs (console + network), server logs ([ClassName] …), the model trajectories in and out, before/after full-page screenshots, and the domain artifacts listed below for this package.
• No residuals. No shortcuts. The goal is not "done" — it is everything done. Clear every blocker by the hard path: build the real architecture, stand up the real model/device/service, actually test it. Never leave a TODO, a stub, a stepping-stone, or a "follow-up." When unsure, research thoroughly, weigh the options, and ship the best, highest-effort, production-ready version. Keep going until every possibility is exhausted.

Artifacts → attached inline in the PR (MP4 video, JPG screenshots, logs in <details>); attach each evidence type or explicitly mark it N/A with a reason — never leave it blank. If develop moved and changed behavior, re-capture evidence; stale proof is worse than none.

Capture & manually review for this package — runtime / framework:

• A live-LLM scenario trajectory for the runtime path you touched — provider → model → action → evaluator — with the raw <response> XML and every tool/action call visible and read.
• Backend [ClassName] logs proving the message loop, task scheduler, or service actually fired end to end.
• The memory/state artifacts produced — rows written, embeddings, room/world/entity records, scheduled-task rows — inspected, not assumed.
• For shared modules: build:node vs full build so the browser/edge bundles still compile.