skills AGENTS.md

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
├── README.md
└── 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

1. 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.
---

1. 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"
)