AGENTS.md

Guidance for AI coding agents (Claude Code, Cursor, Codex, etc.) working in this repo.

What this repo is

A personal monorepo for agent skills authored by Zac Rosenbauer. Skills are agent-agnostic — they target the SKILL.md format and work with any agent that loads it (Claude Code, Cursor, Codex, custom agents, etc.). Skills live in skills/<skill-name>/. Shared utilities (if any) live as pnpm workspace packages in packages/.

Layout

.
├── skills/              # AUTHORING SOURCE — skills authored here, published via `npx skills add`
│   └── <name>/
│       ├── SKILL.md     # the skill
│       ├── LICENSE
│       └── README.md
├── .agents/skills/      # INSTALL DESTINATION — where `npx skills add` puts installed skills
├── skills-lock.json     # tracks installed skills (source, sourceType, skillPath, hash)
├── skill-scripts/       # canonical source for shared scripts (e.g. prompt-shield)
│   └── <name>/          # vendored into `<skill>/scripts/<name>/` via `skill-toolkit sync`
├── packages/
│   └── skill-toolkit/     # CLI for linting skills
├── contributing/        # supplementary contributor docs (e.g. prompt-injection.md)
├── lefthook.yml         # pre-commit hooks (sync, format, lint, drift check)
├── package.json         # root, private, workspaces via pnpm-workspace.yaml
├── pnpm-workspace.yaml  # workspace globs
├── turbo.json           # turbo task pipeline
└── AGENTS.md            # ← you are here (CLAUDE.md is a symlink to this file)

Two locations, two roles:

• skills/<name>/ is the authoring source. Skills authored here are published via npx skills add zrosenbauer/skills. Claude Code in this project also loads from here directly — no symlink needed.
• .agents/skills/<name>/ is the install destination managed by the skills CLI. When you run npx skills add, installed skills land here and skills-lock.json records the source/hash. The same skill can appear in both paths (you can dogfood your own skills by installing them locally) — these are NOT duplicates and .agents/skills/ should not be hand-edited or rm'd. Use the skills CLI to install/uninstall.

All skills under skills/ are public by design — every skill ships through npx skills add and gets audited by skills.sh. There are no local-only / internal skills in this repo.

Sharing scripts between skills

Helpers needed by more than one skill (e.g. prompt-shield for indirect-prompt-injection mitigation) live in skill-scripts/<name>/ as the canonical source. Each consuming skill declares the copy explicitly in <skill>/skill.json:

{
  "$schema": "https://raw.githubusercontent.com/zrosenbauer/skills/main/schemas/skill.json",
  "vendor": [{ "src": "skill-scripts/prompt-shield", "dest": "scripts/prompt-shield" }]
}

pnpm skill-toolkit sync reads every vendor directive, copies src (repo-root-relative) to dest (skill-dir-relative) byte-identical, and re-stages the result. The first segment of dest (scripts, references, templates, ...) is surfaced as a tag in CLI output — adding a new kind is just a new entry, no toolkit code change. Vendored copies are committed so skills stay self-contained when shipped.

The $schema field points at the JSON Schema generated from the zod source via pnpm skill-toolkit schema --write and committed to schemas/skill.json. A raw-githubusercontent URL is used (not a relative path) so the same manifest resolves correctly both from skills/<name>/ and from .agents/skills/<name>/ (different relative depths). Editors that understand $schema (VS Code, JetBrains, Zed) autocomplete + validate inline. A pre-commit hook (schema-check) fails the commit if the committed schema drifts from zod.

Never edit a vendored copy. Edit skill-scripts/<name>/ and let the sync run (Lefthook does this automatically on pre-commit). The drift check (pnpm skill-toolkit sync --check, also pre-commit) fails if any vendored copy diverges from source. See contributing/prompt-injection.md for the threat model and the prompt-shield consumption examples.

Skill format

Each skill is a directory under skills/ with at minimum:

---
name: <skill-name>
description: >-
  One paragraph describing when this skill should be used. Include common
  triggers (verbatim phrases the user might say) so the dispatcher can match.

# --- Claude Code extensions (ignored by other agents) ---
argument-hint: '[<optional-arg>]'
user-invocable: true
---

# <skill-name>

Body of the skill — instructions for the agent when invoked.

name and description are universally required. Other fields are Claude Code extensions; cross-agent skills include them defensively (other agents ignore unknown fields).

Optional companions: LICENSE, README.md, references/<topic>.md, templates/<thing>.template.

Tooling

• pnpm for installs (packageManager is pinned in root package.json)
• turbo for running tasks across workspace packages
• Node ≥ 24
• Bun for Maltty's compiled CLI binaries; uv for the optional security scan

Common commands:

pnpm install                           # install all workspace deps + lefthook hooks (via prepare)
pnpm build                             # turbo run build (compiles skill-toolkit via Maltty)
pnpm bundle                            # turbo run bundle (build shipping assets)
pnpm lint                              # oxlint across the repository
pnpm typecheck                         # turbo run typecheck
pnpm test                              # turbo run test
pnpm test:scripts                      # node --test across skills/*/scripts and skill-scripts/*
pnpm skill-toolkit lint                  # lint every skill against the three-tier rule set
pnpm skill-toolkit lint <name>           # lint one skill
pnpm skill-toolkit sync          # vendor canonical scripts into each consuming skill
pnpm skill-toolkit sync --stage  # sync and stage changed destinations (pre-commit)
pnpm skill-toolkit sync --check  # fail if any vendored copy drifts from source
pnpm audit:skills                      # snyk-agent-scan on public skills (needs SNYK_TOKEN)

Authoring skills:

• /skill-creator <name> — author a new skill (interactive workflow: discover → name → frontmatter → body → lint → package).

Conventions for agents

• Never edit CLAUDE.md directly — it's a symlink to AGENTS.md. Edit AGENTS.md.
• New skills go through /skill-creator. It enforces naming and description quality. Hand-authoring skills is allowed but they must still pass pnpm skill-toolkit lint --severity error.
• All skills live in skills/<kebab-case>/. Every skill is publicly distributed.
• Never hand-edit or rm anything under .agents/skills/ — that's the install destination managed by the skills CLI (tracked by skills-lock.json).
• Shared utilities go in packages/<name>/ with their own package.json and follow the workspace name convention @zrosenbauer/<name>.
• Don't add a package.json to a skill directory unless it actually needs JS deps — most skills are pure markdown.
• Prefer editing existing skills over forking. If forking from a third-party skill, keep the upstream LICENSE alongside it.