AGENTS.md

Instructions for AI agents working in this repo.

Repo structure

skills/
├── skills/                  # All discoverable skills (own + vendor symlinks)
│   ├── miguel-review/       # Own skill (regular directory)
│   ├── impeccable -> ../vendor/impeccable/.claude/skills/impeccable  # Vendor symlink
│   └── ...
├── vendor/                  # Third-party skill repos (git submodules)
│   └── impeccable/          # pbakaus/impeccable
├── install.sh               # Install script with vendor support + `--check` validator
├── README.md                # Public catalog: every skill, badge count, vendor version table
├── index.html               # GitHub Pages landing page: mirrors the README catalog
└── AGENTS.md                # This file

~/.cursor/skills is a symlink to skills/. ~/.claude/skills is a real directory whose entries are per-skill symlinks back into skills/ -- Claude Code does not load skills from a symlinked top-level directory, so the per-skill symlinks are how it picks them up while live edits in this repo still take effect. Any skill directory (or symlink) inside skills/ with a SKILL.md is automatically available to agents in both Cursor and Claude Code.

Re-create the per-skill symlinks if anything drifts:

./install.sh --symlink --all --force --target ~/.claude/skills

Adding a new own skill

Own skills are skills you write and maintain yourself. They live as regular directories under skills/.

1. Create the directory and SKILL.md:

skills/<skill-name>/
├── SKILL.md              # Required
├── references/           # Optional -- detailed docs the agent reads on demand
│   └── some-reference.md
└── examples.md           # Optional

2. SKILL.md must have YAML frontmatter with name and description:

---
name: my-skill-name
description: >-
  What this skill does and when to use it. Include trigger phrases
  so the agent knows when to activate it. Use when the user mentions
  X, Y, or Z.
---

3. Register the skill in install.sh by adding an entry to the SKILLS array:

SKILLS=(
  ...existing entries...
  "my-skill-name:Short description for the install picker"
)

4. MANDATORY: Add the skill to README.md. Every skill registered in install.sh must appear in the README's skill catalog under an appropriate ### section. If no existing section fits, create a new one. Do not skip this step. The README is the public catalog -- a skill missing from it is effectively undiscoverable. If the skill is adapted from a vendor (e.g. gstack), credit the source in the description with a link.
5. MANDATORY: Update the two skill counts and index.html. See Keeping the catalogs in sync.
6. Run ./install.sh --check and fix anything it reports. CI runs the same check and fails on any drift.
7. Commit the new directory, the updated install.sh, README.md, and index.html together in a single commit.

Own skill conventions

• Name: lowercase, hyphens, max 64 chars (e.g. miguel-review, gh-issue-creator)
• Description: third person, includes both WHAT it does and WHEN to use it
• SKILL.md body: under 500 lines; use reference files for detailed content
• Reference files: one level deep only (link from SKILL.md, never chain references)
• No narration comments: don't add comments that just repeat what the code does

Adding a new vendor skill set

Vendor skills come from external repos maintained by other people. They live as git submodules under vendor/ with symlinks in skills/.

1. Add the submodule:

git submodule add https://github.com/<owner>/<repo> vendor/<name>

2. Add an entry to the VENDOR_SKILLS array in install.sh:

VENDOR_SKILLS=(
  ...existing entries...
  "<name>:<owner>/<repo>:<path-to-skills-dir-inside-repo>"
)

The format is name:github-repo:skills-path. For example, Impeccable stores its skills in .claude/skills, so its entry is:

"impeccable:pbakaus/impeccable:.claude/skills"

3. Create symlinks from skills/ to each skill in the vendor repo:

for skill_dir in vendor/<name>/<skills-path>/*/; do
  ln -sf "../vendor/<name>/<skills-path>/$(basename "$skill_dir")" "skills/$(basename "$skill_dir")"
done

4. MANDATORY: Add the vendor skill set to README.md. Same rule as own skills -- every vendor skill exposed via skills/ must appear in the README catalog, with a link to the upstream repo, and add a row to the "Vendor skills" table (source, version or date, which skills are linked). Do not skip this step.
5. MANDATORY: Update the two skill counts and index.html. See Keeping the catalogs in sync.
6. Run ./install.sh --check and fix anything it reports.
7. Commit .gitmodules, the vendor/<name> submodule, the new symlinks, the updated install.sh, README.md, and index.html together.

Pinning a subset of a vendor's skills

The VENDOR_SKILLS entry takes an optional 4th field listing which skills to link. Without it, install.sh links every directory under the vendor's skills path, so when upstream adds skills they silently appear in skills/ (and then fail --check because they are not in the catalogs). Pin the subset explicitly whenever you do not want all of them, e.g. "emil:emilkowalski/skill:skills:review-animations,emil-design-eng".

When the vendor repo is one skill (its SKILL.md sits at the repo root), use . as the skills path. It is linked under the vendor name, e.g. "anatomy:wheresryan22/anatomy:." → skills/anatomy -> ../vendor/anatomy.

Vendor skill rules

• Never edit files inside vendor/. Those are managed by the upstream repo. To make changes, contribute upstream or override with an own skill of the same name (own skills take priority over vendor symlinks).
• Name conflicts: if an own skill and a vendor skill share the same name, the own skill wins. The link_vendor_skills function in install.sh skips symlink creation when a non-symlink directory already exists.
• Updating vendors: run ./install.sh --update-vendor to pull latest from all vendor submodules and re-link.

Updating vendor skills

./install.sh --update-vendor

This runs git submodule update --remote --merge and re-creates the symlinks. After updating:

1. Stage the submodule pointers immediately (git add vendor/*). Every other install.sh invocation runs git submodule update --init, which resets each submodule to the pointer in the index -- an unstaged bump is silently undone the next time you run the script.
2. Check whether upstream renamed or split a skill directory (ls -l skills/ shows dangling symlinks). Re-point the symlink and update the VENDOR_SKILLS filter, the README row, and the index.html card to the new name.
3. Refresh the "Vendor skills" table in README.md (version from the vendor's plugin.json or SKILL.md frontmatter, or main (<date>) when there is none) and any version mentioned in that vendor's catalog rows.
4. Run ./install.sh --check, then commit:

git add vendor/<name> README.md index.html
git commit -m "update <name> to v<new-version>"

Keeping the catalogs in sync

Three places must agree with the contents of skills/ (own directories and vendor symlinks). ./install.sh --check verifies all of them and CI fails on any mismatch, so run it before every commit that touches skills/:

The check reports, per skill, which file is missing it, and flags catalog entries whose directory no longer exists.

Key files