Skip to content

Skills as reusable playbooks

Skills sit next to repository memory (AGENTS.md) as the procedural layer: while AGENTS.md spells out norms and expectations, Skills give repeatable playbooks for work you actually do often. Compression is why that matters.

Instead of re-explaining a complex workflow each session, you invoke a skill; the playbook already holds the instructions, examples, and scripts.

What is a skill?

A skill is a self-contained folder that follows the Agent Skills specification. At its heart is a SKILL.md file that acts as the primary prompt for the agent.

A well-structured skill typically includes:

  • SKILL.md: The instructions, trigger conditions, and expected output format.
  • references/: Domain knowledge or documentation the agent needs.
  • scripts/: Executable code (Python, Bash) for deterministic tasks.
  • assets/: Templates, icons, or "good" examples for the agent to emulate.

I default to npx skills add from vercel-labs/skills. You invoke the CLI via npx, so you do not need Node tooling installed globally on your machine ahead of time.

npx skills add owner/repo-or-url

Examples:

npx skills add vercel-labs/agent-skills
npx skills add https://github.com/ericmjl/skills/tree/main/skills/skill-installer

For ordinary work this stack is still my first choice because it discovers which agents exist on your machine, targets agents with --agent (-a), and lands files where those agents actually look (rather than insisting on one canonical directory).

skills-lock.json (committed with the repo)

When npx skills add omits --global, the CLI writes skills-lock.json at the project root next to ./.agents/skills/.

Check in skills-lock.json with ./.agents/skills/ so clones reinstall the same playbook trees.

The lock schema is documented in src/local-lock.ts in vercel-labs/skills.

Field names can shift with CLI releases.

Each pinned skill records source, sourceType, optional ref, optional skillPath, and computedHash.

The ref field holds the git branch or tag the installer used when it recorded one.

computedHash is SHA-256 over the materialized skill folder: files sorted by relative path. Each step hashes relativePath + file bytes, so renames and moves show up as hash drift, not only edits inside SKILL.md.

Treat unexpected hash movement like pixi.lock churn: read the diff, then link it to git history (commits, tags, pull requests) before you merge.

npx skills experimental_install is labelled experimental on purpose. Upstream help treats it as restoring from skills-lock.json, so expect behavior and naming to move. This repo keeps skills-lock.json at the root beside ./.agents/skills/ so everyone inherits the same pinned bytes.

Global versus project scoped skills

Scope is controlled by --global (-g). Mis-set scope is usually why a skill shows up in one checkout and disappears in another.

  • Project skills (default): npx skills add … with no --global runs inside whatever repo you checked out, typically under .agents/skills/ for many harnesses. Commit those paths when teammates should inherit the same playbooks.

  • Global skills: npx skills add … -g lands in ~/.agents/skills/. Other harnesses may keep sibling trees under their configs. In all cases those playbooks ride with you, not with a clone.

That is why skills vanish cross-checkout: without -g, installs stayed inside project A until you replicated or committed .agents/skills/ in project B.

Anything you add with -g sticks with your user profile until npx skills remove drops it.

Starter pack

Once npx skills feels familiar, I install a small trio deliberately:

  • author new skills,
  • pair on live marimo notebooks,
  • refresh repository agent memory.
npx skills add \
  https://github.com/ericmjl/skills/tree/main/skills/skill-creator -g
npx skills add \
  https://github.com/marimo-team/marimo-pair/tree/main/skills/marimo-pair -g
npx skills add \
  https://github.com/ericmjl/skills/tree/main/skills/agents-md-improver -g
  • skill-creator: Harness-agnostic take on Anthropic's authoring templates; I maintain the prompts in my skills monorepo. They aim at multiple agent runtimes rather than a single vendor stack.
  • marimo-pair: Marimo pairing skill: drive a live kernel, edit cells, execute in session, not by editing the .py while marimo already owns notebook state.
  • agents-md-improver: Updates AGENTS.md as the codebase shifts so repository memory does not rot.

Once npx skills is mundane, the bigger payoff is tacit expertise you can drop into SKILL.md.

Tacit knowledge and the "ESL benefit"

One of the most powerful uses for skills is capturing tacit domain expertise.

A teammate of mine recently used skill-creator to encode her implicit knowledge from over three years of debugging chromatography traces. For her, this was a massive productivity multiplier. English is not her native language, and the structured, Markdown-first nature of skills allowed her to "download her brain" into an executable procedure without being bottlenecked by the nuances of conversational prompting.

This pattern is a huge win for international teams. It levels the playing field by turning individual intuition into a shared, high-signal technical artifact.

The iteration loop

A skill is not a static document; it is a living artifact. I've found this loop works best:

  1. Review: Scrutinize the agent's output from a skill.
  2. Revise: Make surgical edits to the output until it meets your standards.
  3. Feed back: Give the revised version back to the agent.
  4. Update: Tell the agent, "Update this skill with this new example of what looks good."

Over time, the skill evolves to match your taste and technical rigor.

See this in action

The CI/CD chapter shows how automated systems need reliable monitoring. Debugging a failed GitHub Actions run is a perfect candidate for a skill. Instead of manual log diving, you can invoke a skill that pulls the failed job logs, identifies the error, and proposes a fix.

For more on how this fits into your overall practice, see the next chapter on the Compounding agent improvement.