SkillGarden (TypeScript)

Part of LoopEngine — a runtime for defining and running AI agents through a transparent ReAct loop — handling SKILL.md-based skill discovery and lazy loading. Works standalone too, no dependency on LoopEngine itself.

See the root README for the pitch, the prior-art landscape, and the scope decisions. This file only covers what's specific to running the code.

Install

npm install

Quickstart

npm run quickstart

import { SkillGarden } from './src/index.js'

const garden = new SkillGarden({ dirs: ['examples/skills'] })
const { included, truncated } = garden.buildIndex()

console.log(garden.invoke('greet', 'world'))
// -> "Hello, world!"

const eligible = garden.eligibleFor(included, ['apps/web/index.tsx'])
// -> includes "deploy:web", since its `paths` glob matches

CLI

npx skillgarden add firecrawl --agent file-agent
# -> Added file-agent:firecrawl -> agents/file-agent/skills/firecrawl/SKILL.md

npx skillgarden add firecrawl
# -> Added firecrawl -> skills/firecrawl/SKILL.md

Copies a skill from the bundled registry/<category>/<skill>/ into a default location that depends on whether --agent is given:

• With --agent <name> (and no --dir): agents/<name>/skills/<skill>/ — a per-agent skills folder, discovered by pointing that agent's own skillsDirs at it.
• Without --agent: the flat skills/<skill>/.

<skill> is a bare name (searched across every category — ambiguous only if the same skill name exists under more than one, which none of the bundled ones do today) or an explicit <category>/<skill>, e.g. npx skillgarden add web/firecrawl. Either way the installed copy is always named after the bare skill alone — category is just how this registry organizes its own bundled skills, not something forced onto your own skills/ folder.

Bundled skills

A skill earns a place here only if it teaches the model something it doesn't already reliably know — a private convention, an external API's exact contract, a specific safety procedure — not general reasoning it can already do unprompted (a proofreading pass, a unit conversion, a JSON⇄CSV reshape). Bundling those anyway would spend every caller's index budget for no behavior change.

| Skill | Category | What it does | | --- | --- | --- | | firecrawl | web | Scrape, crawl, or map a website into markdown/structured data via the Firecrawl API — a specific external API's exact endpoints/auth/parameters. | | batch-rename-plan | files | Turn a batch-rename request into an explicit old-name -> new-name mapping, without renaming anything yet — a safety procedure (never execute silently, always show a reviewable plan, flag collisions), not just "how to rename files." |

Pass --dir <path> to use a different root instead of either default. An explicit --dir combined with --agent nests by agent under it — <dir>/<agent>/<skill>/, ready for discoverSkillFiles to pick up as <agent>:<skill> — for the shared-root pattern (one skills root serving several agents, namespaced by subfolder). Pass --force to overwrite an existing install.

Test / build

npm test        # vitest
npm run build   # tsc -> dist/

Status

Loader, budget-aware index, directory discovery with colon-namespacing, and path-conditional activation are real and tested. Published as skillgarden on npm.