cmd-skills-local-repo

What this skill does

# Repo-Local Skill Manager <!-- omit in toc -->

Create or refactor repo-local skills and agent instructions that work across Claude, Codex, Gemini, and Codex-home using a single canonical source in `.agents/`.

- [Architecture](#architecture)
- [Phase 1: Gather Context](#phase-1-gather-context)
- [Phase 2a: Agent Instructions](#phase-2a-agent-instructions)
- [Phase 2b: Scaffold, Promote, or Repair the Skill](#phase-2b-scaffold-promote-or-repair-the-skill)
  - [Create canonical source](#create-canonical-source)
  - [Create symlinks](#create-symlinks)
  - [Update .gitignore](#update-gitignore)
- [Phase 3: Verify](#phase-3-verify)
- [Templates](#templates)

## Architecture

```
repo-root/
├── .agents/
│   ├── AGENTS.md                                           # Canonical agent instructions
│   └── skills/<name>/SKILL.md                              # Canonical skill source
├── AGENTS.md → .agents/AGENTS.md                           # Symlink (tools reading repo root)
├── CLAUDE.md → .agents/AGENTS.md                           # Symlink (Claude reads repo root)
├── .codex/AGENTS.md → ../.agents/AGENTS.md                 # Symlink
├── .gemini/GEMINI.md → ../.agents/AGENTS.md                # Symlink
├── .claude/skills/<name> → ../../.agents/skills/<name>     # Per-skill symlink
├── .codex/skills/<name> → ../../.agents/skills/<name>      # Per-skill symlink
├── .codex-home/skills/<name> → ../../.agents/skills/<name> # Per-skill symlink
└── .gitignore                                              # Whitelist entries for all paths
```

Key rules:

- `.agents/` is the single source of truth for both agent instructions and skills
- `.agents/AGENTS.md` is the canonical agent instruction file — all tool-specific files are symlinks
- Per-skill symlinks are used instead of directory-level symlinks so externally installed skills (e.g. via `npx skills add`) coexist without conflict
- `.gitignore` uses a base `skills/` ignore rule, then whitelists specific paths
- An optional `evals/` directory inside `.agents/skills/<name>/` is always gitignored
- **No skill may live as a real directory under a tool-specific path** (`.claude/skills/<name>/`, `.codex/skills/<name>/`, `.codex-home/skills/<name>/`). Per-tool dirs contain only symlinks. Canonical source is always `.agents/skills/<name>/` — this keeps skills cross-tool and prevents silent Claude-only (or Codex-only, etc.) drift

## Phase 1: Gather Context

Before asking questions, run discovery:

```bash
ls .agents/ 2>/dev/null
ls .agents/skills/ 2>/dev/null
ls .claude/commands/ 2>/dev/null
cat CLAUDE.md 2>/dev/null | head -5
cat AGENTS.md 2>/dev/null | head -5
grep -n "^skills/" .gitignore 2>/dev/null
```

Also run the cross-tool audit (see [Audit commands](#audit-commands) for the copy-paste block). Detect:

- **Tool-specific real-dir skills** — any directory under `.claude/skills/`, `.codex/skills/`, or `.codex-home/skills/` that is a real directory (not a symlink). These violate the cross-tool rule and must be promoted.
- **Orphans in `.agents/skills/`** — any skill in `.agents/skills/` that is missing a symlink in one or more per-tool dirs. These are reachable from some tools but not others.

Present all findings (shared-context reads + audit output), then use `AskUserQuestion` with these questions (max 4 per call):

1. **Mode**: "Do you want to (a) create a NEW repo-local skill from scratch, (b) refactor an existing `.claude/commands/` file into the cross-tool skill structure, (c) just set up agent instructions (no skill), (d) promote an existing tool-specific real-dir skill into the cross-tool layout, or (e) repair an orphan `.agents/skills/` skill by creating missing per-tool symlinks?"
2. **Skill name** (if a/b/d/e): "What should the skill be called? (kebab-case, e.g. `grove-api-review`)"
3. **Description** (if a or b): "One-line description of what the skill does."
4. **If commands exist and mode = b**: "Which command file should I migrate?" (list the files found in `.claude/commands/`)

If the audit surfaced violations or orphans, lead with those — it's almost always the right next action before scaffolding anything new.

## Phase 2a: Agent Instructions

Set up `.agents/AGENTS.md` as the canonical agent instruction file with symlinks for every tool.

**Step 1 — Create or migrate the canonical file:**

```bash
mkdir -p .agents
```

- If `AGENTS.md` exists at repo root and is a regular file, move it: `mv AGENTS.md .agents/AGENTS.md`
- If `CLAUDE.md` exists at repo root and is a regular file (not a symlink), move it: `mv CLAUDE.md .agents/AGENTS.md`
- If neither exists, create `.agents/AGENTS.md` with a minimal skeleton
- If both exist, merge them into `.agents/AGENTS.md` (prefer `AGENTS.md` content, append unique `CLAUDE.md` content)

**Step 2 — Create symlinks:**

```bash
ln -sf .agents/AGENTS.md AGENTS.md
ln -sf .agents/AGENTS.md CLAUDE.md
mkdir -p .codex .gemini
ln -sf ../.agents/AGENTS.md .codex/AGENTS.md
ln -sf ../.agents/AGENTS.md .gemini/GEMINI.md
```

**Step 3 — Verify all symlinks resolve:**

```bash
readlink AGENTS.md
readlink CLAUDE.md
readlink .codex/AGENTS.md
readlink .gemini/GEMINI.md
head -3 CLAUDE.md
```

**Step 4 — Update .gitignore:**

Check if entries already exist, then add as needed:

```bash
grep -n "AGENTS.md\|CLAUDE.md\|GEMINI.md" .gitignore 2>/dev/null
```

Append the agent instructions block from the [gitignore template](#gitignore-block-template) if not present.

## Phase 2b: Scaffold, Promote, or Repair the Skill

Skip this phase if the user chose mode (c) in Phase 1. Modes (a), (b), (d), and (e) all share the same symlink + gitignore steps — they only differ in how the canonical source is produced.

### Create canonical source

Create the canonical directory:

```bash
mkdir -p .agents/skills/<name>
```

**If creating new (mode a):**

Create `.agents/skills/<name>/SKILL.md` with frontmatter and a minimal skeleton. Ask the user to provide or iterate on the skill content.

**If refactoring from `.claude/commands/` (mode b):**

1. Read the source command file (e.g., `.claude/commands/<name>.md`)
2. Create `.agents/skills/<name>/SKILL.md` with YAML frontmatter added
3. Convert the top-level header to include `<!-- omit in toc -->`
4. Do NOT delete the original command file yet — offer in Phase 3

**If promoting an existing tool-specific real-dir skill (mode d):**

The skill currently lives as a real directory under a per-tool path (e.g., `.claude/skills/<name>/` with a real `SKILL.md` inside). Move it to the canonical location:

```bash
mv .claude/skills/<name> .agents/skills/<name>
```

If the violation is under `.codex/skills/` or `.codex-home/skills/` instead, `mv` from there. Then proceed to [Create symlinks](#create-symlinks) — a symlink must be re-added to the per-tool dir the skill was promoted from (since the `mv` removed it), *and* to the other two per-tool dirs.

**If repairing an orphan (mode e):**

The skill already lives at `.agents/skills/<name>/` but is missing one or more per-tool symlinks. Skip directly to [Create symlinks](#create-symlinks) — the canonical source is untouched; only the symlinks need to be (re-)created.

### Create symlinks

Each skill needs a symlink in every tool's skills directory. This approach allows external skills (e.g. from `npx skills add`) to coexist.

```bash
mkdir -p .claude/skills .codex/skills .codex-home/skills
ln -sf ../../.agents/skills/<name> .claude/skills/<name>
ln -sf ../../.agents/skills/<name> .codex/skills/<name>
ln -sf ../../.agents/skills/<name> .codex-home/skills/<name>
```

Check that the symlinks resolve correctly:

```bash
test -f .claude/skills/<name>/SKILL.md && echo "OK" || echo "BROKEN"
```

Two legacy layouts require normalization before this loop runs cleanly:

**Legacy — directory-level symlink** (`.claude/skills → ../.agents/skills`). Replace with per-skill symlinks:

```bash
for tool in .claude .codex .codex-home; do
  [ -L "$tool/skills" ] && rm "$tool/skills"
  mkdir -p "$tool/skills"
done
```

**Legacy — tool-