@kurokeita/add-skill 1.21.0 → 2.1.0

package/dist/skills/universalize-agents/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: universalize-agents
+description: Use when the user wants to consolidate or "universalize" their AI agent setup across platforms (Claude Code, Codex, Windsurf, GitHub Copilot, Gemini CLI, Antigravity). Discovers each platform's installed skills/agents/commands and master instructions, copies them into a single `.agents/` directory, migrates master instructions into a canonical `AGENTS.md`, and installs a per-platform session-start hook that symlinks `.agents/` back into each platform's directories.
+version: 0.1.0
+---
+
+# Universalize Agents
+
+Consolidate a multi-platform AI agent setup into one source of truth
+(`.agents/` + `AGENTS.md`) and wire every platform to re-materialize it via
+symlinks on each session start.
+
+This skill is the first step of a larger "universalize agent setup" feature.
+It performs discovery, consolidation, and hook installation. It does **not**
+modify this repository's `src/` or CLI.
+
+## Canonical references
+
+Read these before acting — they are the source of truth and must not drift
+from the codebase:
+
+- `reference/mapping.md` — reverse map of every platform's
+  skills/agents/commands directories (derived from `src/utils/paths.ts`),
+  the per-platform hook-config file locations, and the master-instruction
+  file names.
+- `scripts/agent-setup.sh` (macOS/Linux) and `scripts/agent-setup.ps1`
+  (Windows) — the idempotent symlink templates that get installed.
+- `reference/hook-templates/` — per-platform session-start hook snippets.
+
+## When to Use
+
+Invoke when the user asks to "universalize", "consolidate", "unify", or
+"centralize" their agent setup, skills, commands, or instructions across more
+than one AI coding platform.
+
+## Workflow
+
+Follow these phases in order. Stop and ask whenever a decision is the user's
+to make.
+
+### Phase 1 — Choose scope
+
+Ask the user: **universalize the setup for the current project, or globally?**
+
+- `project` → `.agents/` lives at the project root; platform targets are the
+  project-relative directories in `reference/mapping.md`.
+- `global` → `.agents/` lives at `$HOME/.agents`; platform targets are the
+  `~/...` directories in `reference/mapping.md`.
+
+Record the chosen scope and the resolved base directory (`BASE`). Everything
+downstream uses `BASE`.
+
+### Phase 2 — Discover existing setups
+
+For each of the six platforms, check whether its directories exist under
+`BASE` (per `reference/mapping.md`). Treat a platform as "in use" if any of
+its skills/agents/commands dirs or its master-instruction file exists.
+
+For each in-use platform, enumerate items in its `skills`, `agents`,
+`workflows`, and `rules` source dirs. Some platforms collapse multiple types into one
+directory (Codex puts skills + agents + workflows in `.codex/skills`; Claude
+Code puts workflows in `.claude/skills`). Disambiguate an item's real type by
+reading its frontmatter / the `x-ai-agents-type` metadata this toolchain
+writes when wrapping items — never by directory alone.
+
+Report a discovery summary (platforms in use, item counts per type) before
+continuing.
+
+### Phase 3 — Build `.agents/`
+
+Create the unified layout under `BASE`:
+
+```text
+.agents/
+  skills/    agents/    commands/    rules/    hooks/
+```
+
+Copy discovered items into `.agents/{skills,agents,commands,rules}`. When the
+same-named item is found on more than one platform, copy it once: prefer the
+first platform discovered and warn about the collision rather than silently
+overwriting. Never wipe an existing `.agents/` — merge into it.
+
+#### Format normalization
+
+The unified store is markdown-only. Normalize as you copy:
+
+- **Rules.** Collect standard markdown rule files from the platforms that
+  support them — Claude, Gemini, and Antigravity use `<agent-dir>/rules`;
+  GitHub Copilot uses `.github/instructions` (see `reference/mapping.md`) —
+  into `.agents/rules/`. Codex and Windsurf have none. These are per-platform
+  rule files, distinct from the master instruction files consolidated in
+  Phase 4. Rules are **not** symlinked back (not in `__LINK_MAP__`); Phase 4
+  wires the whole dir into `AGENTS.md`.
+- **Workflows → commands.** Treat every platform's "workflow" items as the
+  universal `commands` type and place them in `.agents/commands/`. If a prior
+  run left a `.agents/workflows/` directory, move its contents into
+  `.agents/commands/` and remove the now-empty `workflows/` dir.
+- **Gemini commands → skills.** Gemini stores commands as TOML
+  (`.gemini/commands/*.toml`), which cannot be symlinked back as markdown.
+  Convert each Gemini `*.toml` into a skill: parse its `description` and
+  `prompt = """..."""` fields, then write `.agents/skills/<name>/SKILL.md`
+  with the prompt as the body and this frontmatter:
+
+  ```markdown
+  ---
+  name: <toml file name without extension>
+  description: <value of the TOML `description` field>
+  ---
+
+  <contents of the TOML `prompt` field>
+  ```
+
+  This is the reverse of `convertToGeminiCommandTOML` in
+  `src/utils/toml.ts`. Gemini workflows therefore land in `.agents/skills/`,
+  not `.agents/commands/`.
+
+### Phase 4 — Migrate master instructions
+
+Detect every master-instruction file present in scope:
+
+| Platform | File |
+|---|---|
+| Claude Code | `CLAUDE.md` |
+| Codex / Antigravity / Windsurf | `AGENTS.md` |
+| Gemini CLI | `GEMINI.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+
+The canonical target is root `AGENTS.md` (already the native master file for
+Codex, Antigravity, and Windsurf).
+
+- **None found** → create a minimal `AGENTS.md`.
+- **Exactly one found** → use it as `AGENTS.md` directly, no prompt.
+- **Two or more distinct files found** → STOP and ask the user how to
+  consolidate:
+  1. **Keep one** — show each detected file with a short preview / line
+     count; the user picks which becomes `AGENTS.md`.
+  2. **Merge all + trim** — concatenate every source, then de-duplicate
+     overlapping instructions into one coherent `AGENTS.md` (semantic
+     de-duplication, preserving every unique directive). Surface any
+     conflicting directives to the user instead of dropping them silently.
+
+After producing `AGENTS.md` (at `BASE`), **replace the entire contents** of
+each non-`AGENTS.md` master file with a single import line — its original
+content now lives in `AGENTS.md`:
+
+```text
+@AGENTS.md
+```
+
+Always create `AGENTS.md` (with the migrated content) before overwriting any
+master file, so nothing is lost. Platforms that natively read `AGENTS.md`
+(Codex, Antigravity, Windsurf) need no such file.
+
+**Wiring rules into masters.** Rules are not symlinked into any platform dir.
+Instead, import the whole `.agents/rules/` directory into `AGENTS.md` with a
+single directory import, so every platform that reads `AGENTS.md` (directly, or
+via its `@AGENTS.md` master import) picks them up:
+
+```text
+@.agents/rules/
+```
+
+Add this import only when `.agents/rules/` is non-empty.
+
+### Phase 5 — Install and run the setup script
+
+Pick the script for the host OS — `scripts/agent-setup.sh` on macOS/Linux,
+`scripts/agent-setup.ps1` on Windows — copy it into `BASE/.agents/hooks/`
+(keeping its extension), make it executable, and fill its two placeholders:
+
+- `__AGENTS_DIR__` → path to `BASE/.agents`: **relative** (`.agents`) for
+  project scope, **absolute** for global scope.
+- `__LINK_MAP__` → one `SRC_SUBDIR|DEST_DIR` line per (in-use platform × type),
+  using the scope-correct destination dirs from `reference/mapping.md`.
+  `SRC_SUBDIR` is `skills`, `agents`, or `commands`. Use **relative** dest
+  dirs (e.g. `.claude/skills`) for project scope and **absolute** dirs for
+  global scope. The script detects the mode from `__AGENTS_DIR__` and emits
+  relative symlinks for project scope, absolute for global.
+
+The script symlinks each item individually (not whole directories) so that
+collapsed targets like `.codex/skills` can receive skills + agents + commands
+merged together without conflict. It is idempotent and refuses to clobber a
+real (non-symlink) path.
+
+In **project scope** the script keeps the generated symlinks out of git by
+writing a single `.gitignore` per platform at its base dir (the parent of the
+target dirs, e.g. `.claude/.gitignore`) that lists each symlink subdir
+(`skills/`, `commands/`, …). Only the canonical `.agents/` content (which you
+commit) is version-controlled. Global scope skips this (it is not inside a
+repo).
+
+Once `.agents/` holds every item and the script is installed, **delete the
+original item files/directories at each platform source dir**. The canonical
+copy now lives in `.agents/`, so the originals are redundant — and because the
+symlink step refuses to overwrite a real path, it cannot link until the
+original is gone. Then run the setup script once to create the symlinks; every
+later session-start run re-applies them idempotently.
+
+### Phase 6 — Install session-start hooks
+
+For each in-use platform, register a session-start hook that runs the
+installed setup script in `BASE/.agents/hooks/` (`agent-setup.sh` on
+macOS/Linux, `agent-setup.ps1` on Windows), writing to the config file in
+`reference/mapping.md`:
+
+| Platform | Project file | Global file | Format |
+|---|---|---|---|
+| Claude Code | `.claude/settings.json` | `~/.claude/settings.json` | JSON |
+| Gemini / Antigravity | `.gemini/settings.json` | `~/.gemini/settings.json` | JSON |
+| Codex | `.codex/config.toml` | `~/.codex/config.toml` | TOML |
+| Windsurf | — | — | no session-start hook (skip) |
+| GitHub Copilot | `.github/hooks/agent-setup.json` | `~/.copilot/hooks/agent-setup.json` | JSON |
+
+Rules for every write:
+
+- **Append, never overwrite.** Parse the existing file, inject the hook entry
+  only if an equivalent one is absent, then write back. Preserve all other
+  keys and formatting as much as the format allows.
+- **Path style follows scope.** The hook command points at the setup script:
+  use a **relative** path (`.agents/hooks/agent-setup.sh`) for project scope
+  and an **absolute** path for global scope — matching how `__AGENTS_DIR__`
+  was filled.
+- Back up the file (`<file>.bak`) before the first modification.
+- Use the verified template for each platform in `reference/hook-templates/`
+  (`claude-code.json`, `gemini.json`, `codex.toml`, `copilot.json`).
+  **Windsurf has no session-start hook**, so it gets no recurring hook. Keep
+  its dirs in the Phase 5 `__LINK_MAP__` so the one-time setup run symlinks
+  them, but tell the user the shared `.agents/` will not auto-refresh on
+  Windsurf — they re-run the setup script manually to pick up later changes.
+  Codex prompts for a trust review of project hooks on first use.
+
+### Phase 7 — Report
+
+Summarize: scope, platforms processed, items consolidated per type, how
+master instructions were resolved, which hooks were installed (and which were
+skipped/unverified), and any collisions or backups created.
+
+## Constraints
+
+- Append-only for existing config (settings/hook) files; back up first.
+  Master instruction files are the exception: replace their contents with the
+  `@AGENTS.md` import once the content is migrated into `AGENTS.md`.
+- Per-item symlinks, never whole-directory, never clobber real paths.
+- Do not fabricate hook schemas; verify unverified platforms at runtime.
+- Do not modify this repo's `src/`, CLI, or `paths.ts`.

package/dist/skills/universalize-agents/reference/hook-templates/README.md

@@ -0,0 +1,30 @@
+# Hook templates
+
+Session-start hook snippets that the `universalize-agents` skill merges into
+each platform's config file (see `../mapping.md` for file locations).
+
+## Verification status
+
+| Platform | Template | Status |
+|---|---|---|
+| Claude Code | `claude-code.json` | Verified |
+| Gemini / Antigravity | `gemini.json` | Verified |
+| Codex | `codex.toml` | Verified |
+| GitHub Copilot | `copilot.json` | Verified |
+| Windsurf | — | No session-start hook — one-time symlink only |
+
+Windsurf (Cascade) hooks are action-scoped only (`pre_write_code`,
+`post_setup_worktree`, etc.) with no session-start event, so no recurring hook
+is installed. Windsurf still gets a one-time symlink during the setup run (its
+dirs stay in the link map); re-run the setup script manually to pick up later
+changes to the shared `.agents/`.
+
+## Merge rules (all platforms)
+
+- Append, never overwrite. Parse the file, inject the hook only if an
+  equivalent entry is absent, then write back.
+- Back up the file to `<file>.bak` before the first modification.
+- The hook command is the absolute path to the OS-appropriate setup script
+  (`agent-setup.sh` on macOS/Linux, `agent-setup.ps1` on Windows). Copilot
+  uses the `bash`/`powershell` fields; Gemini and Codex use a `command`
+  string grouped under a `matcher`.

package/dist/skills/universalize-agents/reference/hook-templates/claude-code.json

@@ -0,0 +1,15 @@
+{
+	"_comment": "VERIFIED. Claude Code SessionStart hook. Merge the SessionStart entry into the existing settings.json hooks object; do not overwrite sibling keys. Replace the command path with the absolute path to <base>/.agents/hooks/agent-setup.sh.",
+	"hooks": {
+		"SessionStart": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "<base>/.agents/hooks/agent-setup.sh"
+					}
+				]
+			}
+		]
+	}
+}

package/dist/skills/universalize-agents/reference/hook-templates/codex.toml

@@ -0,0 +1,10 @@
+# VERIFIED (developers.openai.com/codex/hooks). Append these tables into the
+# existing .codex/config.toml; keep other tables. Replace <COMMAND> with the
+# absolute path to <base>/.agents/hooks/agent-setup.sh. Codex prompts for a
+# trust review of project hooks on first use.
+[[hooks.SessionStart]]
+matcher = "startup"
+
+[[hooks.SessionStart.hooks]]
+type = "command"
+command = "<COMMAND>"

package/dist/skills/universalize-agents/reference/hook-templates/copilot.json

@@ -0,0 +1,9 @@
+{
+	"_comment": "VERIFIED (docs.github.com hooks-configuration). Write to .github/hooks/agent-setup.json (project) or ~/.copilot/hooks/agent-setup.json (global). Replace <COMMAND> with the absolute path to <base>/.agents/hooks/agent-setup.sh; use the powershell field instead of bash on Windows.",
+	"version": 1,
+	"hooks": {
+		"sessionStart": [
+			{ "type": "command", "bash": "<COMMAND>", "timeoutSec": 30 }
+		]
+	}
+}

package/dist/skills/universalize-agents/reference/hook-templates/gemini.json

@@ -0,0 +1,11 @@
+{
+	"_comment": "VERIFIED (gemini-cli docs/hooks/reference.md). Merge the SessionStart entry into the existing .gemini/settings.json hooks object; keep sibling keys. Replace <COMMAND> with the absolute path to <base>/.agents/hooks/agent-setup.sh (agent-setup.ps1 on Windows). Same schema for Antigravity.",
+	"hooks": {
+		"SessionStart": [
+			{
+				"matcher": "startup",
+				"hooks": [{ "type": "command", "command": "<COMMAND>" }]
+			}
+		]
+	}
+}

package/dist/skills/universalize-agents/reference/mapping.md

@@ -0,0 +1,100 @@
+# Platform mapping reference
+
+Reverse map used by the `universalize-agents` skill. Source of truth is
+`src/utils/paths.ts` in this repository — keep this file in sync with it.
+
+## Source directories (discover from / symlink to)
+
+`Global` paths are under `$HOME`. `Project` paths are relative to the project
+root. A few platforms use a different sub-path between scopes (noted in bold).
+
+### Skills (`.agents/skills`)
+
+| Platform | Global | Project |
+|---|---|---|
+| Claude Code | `~/.claude/skills` | `.claude/skills` |
+| Codex | `~/.codex/skills` | `.codex/skills` |
+| GitHub Copilot | `~/.copilot/skills` | `.copilot/skills` |
+| Gemini CLI | `~/.gemini/skills` | `.gemini/skills` |
+| Windsurf | `~/.codeium/windsurf/skills` | `.codeium/windsurf/skills` |
+| Antigravity | `~/.gemini/antigravity/`**`global_skills`** | `.gemini/antigravity/`**`skills`** |
+
+### Agents (`.agents/agents`)
+
+| Platform | Global | Project |
+|---|---|---|
+| Claude Code | `~/.claude/agents` | `.claude/agents` |
+| Codex | `~/.codex/skills` | `.codex/skills` |
+| GitHub Copilot | `~/.copilot/agents` | `.copilot/agents` |
+| Gemini CLI | `~/.gemini/agents` | `.gemini/agents` |
+| Windsurf | — | — |
+| Antigravity | — | — |
+
+### Commands / workflows (`.agents/commands`)
+
+| Platform | Global | Project |
+|---|---|---|
+| Claude Code | `~/.claude/commands` | `.claude/commands` |
+| Codex | `~/.codex/skills` | `.codex/skills` |
+| GitHub Copilot | `~/.copilot/prompts` | `.copilot/prompts` |
+| Gemini CLI | `~/.gemini/commands` | `.gemini/commands` |
+| Windsurf | `~/.codeium/windsurf/`**`global_workflows`** | `.codeium/windsurf/`**`workflows`** |
+| Antigravity | `~/.gemini/antigravity/`**`global_workflows`** | `.gemini/antigravity/`**`workflows`** |
+
+### Rules (`.agents/rules`)
+
+Standard markdown rule files, discovered from the dirs below and consolidated
+into `.agents/rules/`. They are **not** symlinked back — the whole
+`.agents/rules/` dir is `@`-imported into `AGENTS.md` (see SKILL.md Phase 4), so
+every platform picks them up via the master chain. Codex and Windsurf have no
+rules dir to discover from.
+
+| Platform | Global | Project |
+|---|---|---|
+| Claude Code | `~/.claude/rules` | `.claude/rules` |
+| Gemini CLI | `~/.gemini/rules` | `.gemini/rules` |
+| Antigravity | `~/.gemini/antigravity/rules` | `.gemini/antigravity/rules` |
+| GitHub Copilot | — | `.github/instructions` |
+| Codex / Windsurf | — | — |
+
+## Collapsed directories
+
+These targets hold more than one type, so reverse-discovery must read item
+frontmatter / the `x-ai-agents-type` metadata to recover the true type:
+
+- `.codex/skills` — skills **and** agents **and** commands.
+
+When symlinking back, use per-item links so these merged directories do not
+collide.
+
+## Format normalization
+
+- Workflows are stored under `.agents/commands/` (the universal name); migrate
+  any legacy `.agents/workflows/` into it.
+- Gemini commands are TOML and convert to markdown skills in
+  `.agents/skills/<name>/SKILL.md` (reverse of `convertToGeminiCommandTOML`
+  in `src/utils/toml.ts`). See SKILL.md Phase 3.
+
+## Hook-config files (session-start)
+
+Always append into the existing file; back up first; never overwrite.
+
+| Platform | Global | Project | Format |
+|---|---|---|---|
+| Claude Code | `~/.claude/settings.json` | `.claude/settings.json` | JSON |
+| Gemini / Antigravity | `~/.gemini/settings.json` | `.gemini/settings.json` | JSON |
+| Codex | `~/.codex/config.toml` | `.codex/config.toml` | TOML |
+| Windsurf | — | — | no session-start event; one-time symlink only |
+| GitHub Copilot | `~/.copilot/hooks/agent-setup.json` | `.github/hooks/agent-setup.json` | JSON |
+
+## Master-instruction files
+
+| Platform | File |
+|---|---|
+| Claude Code | `CLAUDE.md` |
+| Codex / Antigravity / Windsurf | `AGENTS.md` |
+| Gemini CLI | `GEMINI.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+
+Canonical consolidated target: root `AGENTS.md` (also copied into
+`.agents/rules/`).

package/dist/skills/universalize-agents/scripts/agent-setup.ps1

@@ -0,0 +1,83 @@
+#!/usr/bin/env pwsh
+# Generated by the `universalize-agents` skill. Windows only
+# (see agent-setup.sh for macOS/Linux). Safe to re-run (idempotent).
+# Project scope fills relative paths; global scope fills absolute paths.
+# Creating symlinks on Windows requires Developer Mode or an elevated shell.
+
+$ErrorActionPreference = 'Stop'
+
+$AgentsDir = '__AGENTS_DIR__'
+
+# __LINK_MAP__ contract: one "SRC_SUBDIR|DEST_DIR" line per (platform x type),
+# where SRC_SUBDIR is skills|agents|commands and DEST_DIR matches the scope.
+$LinkMap = @'
+__LINK_MAP__
+'@
+
+function Write-AgentLog($message) { Write-Host "agent-setup: $message" }
+
+# Relative paths (project scope) resolve from the repo root; this script lives
+# at <root>\.agents\hooks\, so move two levels up. Absolute paths are untouched.
+$IsRelative = -not [System.IO.Path]::IsPathRooted($AgentsDir)
+if ($IsRelative) { Set-Location (Join-Path $PSScriptRoot '..\..') }
+
+function Set-AgentLink($src, $dest) {
+	if (Test-Path -LiteralPath $dest) {
+		$existing = Get-Item -LiteralPath $dest -Force
+		if ($existing.LinkType -eq 'SymbolicLink' -and $existing.Target -eq $src) {
+			return
+		}
+		if ($existing.LinkType -ne 'SymbolicLink') {
+			# Refuse to replace a real (non-symlink) path that a user may own.
+			Write-AgentLog "SKIP (real path in the way): $dest"
+			return
+		}
+		Remove-Item -LiteralPath $dest -Force
+	}
+	New-Item -ItemType SymbolicLink -Path $dest -Target $src | Out-Null
+}
+
+foreach ($line in $LinkMap -split "`r?`n") {
+	$line = $line.Trim()
+	if (-not $line) { continue }
+
+	$sub, $destDir = $line -split '\|', 2
+	if (-not $sub -or -not $destDir) { continue }
+
+	$srcDir = Join-Path $AgentsDir $sub
+	if (-not (Test-Path -LiteralPath $srcDir)) { continue }
+	if (-not (Test-Path -LiteralPath $destDir)) {
+		New-Item -ItemType Directory -Path $destDir -Force | Out-Null
+	} else {
+		# Clean up dangling symlinks in $destDir
+		foreach ($link in Get-ChildItem -LiteralPath $destDir -Force) {
+			if ($link.LinkType -eq 'SymbolicLink' -and -not (Test-Path -LiteralPath $link.FullName)) {
+				Write-AgentLog "removing broken symlink: $($link.FullName)"
+				Remove-Item -LiteralPath $link.FullName -Force
+			}
+		}
+	}
+
+	# Project scope only: keep the generated symlinks out of git via a single
+	# .gitignore per platform base dir (the dest's parent), listing each
+	# symlink subdir. The canonical content lives in (tracked) .agents/.
+	if ($IsRelative) {
+		$gi = Join-Path (Split-Path -Parent $destDir) '.gitignore'
+		$entry = (Split-Path -Leaf $destDir) + '/'
+		$lines = @()
+		if (Test-Path -LiteralPath $gi) { $lines = @(Get-Content -LiteralPath $gi) }
+		if ($lines -notcontains $entry) { Add-Content -LiteralPath $gi -Value $entry }
+	}
+
+	foreach ($item in Get-ChildItem -LiteralPath $srcDir -Force) {
+		$dest = Join-Path $destDir $item.Name
+		if ($IsRelative) {
+			$target = [System.IO.Path]::GetRelativePath($destDir, (Join-Path $srcDir $item.Name))
+		} else {
+			$target = $item.FullName
+		}
+		Set-AgentLink $target $dest
+	}
+}
+
+Write-AgentLog 'done.'

package/dist/skills/universalize-agents/scripts/agent-setup.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Generated by the `universalize-agents` skill. macOS/Linux only
+# (see agent-setup.ps1 for Windows). Safe to re-run (idempotent).
+# Project scope fills relative paths; global scope fills absolute paths.
+
+set -euo pipefail
+
+AGENTS_DIR="__AGENTS_DIR__"
+
+# __LINK_MAP__ contract: one "SRC_SUBDIR|DEST_DIR" line per (platform x type),
+# where SRC_SUBDIR is skills|agents|commands and DEST_DIR matches the scope
+# (relative to repo root for project scope, absolute for global scope).
+LINK_MAP="$(
+	cat <<'EOF'
+__LINK_MAP__
+EOF
+)"
+
+log() { printf 'agent-setup: %s\n' "$1" >&2; }
+
+# Relative paths (project scope) resolve from the repo root; this script lives
+# at <root>/.agents/hooks/, so cd two levels up. Absolute paths are untouched.
+case "$AGENTS_DIR" in
+	/*) ;;
+	*) cd "$(dirname "$0")/../.." ;;
+esac
+
+# Echo the "../" prefix climbing from a relative dir back to the repo root,
+# so a symlink's target is correct relative to the link's own location.
+up_to_root() {
+	up=""
+	old_ifs="$IFS"
+	IFS=/
+	for _seg in $1; do up="../$up"; done
+	IFS="$old_ifs"
+	printf '%s' "$up"
+}
+
+link_item() {
+	src="$1"
+	dest="$2"
+
+	if [ -L "$dest" ] && [ "$(readlink "$dest")" = "$src" ]; then
+		return 0
+	fi
+
+	# Refuse to replace a real (non-symlink) path that a user may own.
+	if [ -e "$dest" ] && [ ! -L "$dest" ]; then
+		log "SKIP (real path in the way): $dest"
+		return 0
+	fi
+
+	rm -f "$dest"
+	ln -s "$src" "$dest"
+}
+
+printf '%s\n' "$LINK_MAP" | while IFS='|' read -r sub destdir; do
+	[ -z "${sub:-}" ] && continue
+	[ -z "${destdir:-}" ] && continue
+
+	srcdir="$AGENTS_DIR/$sub"
+	[ -d "$srcdir" ] || continue
+
+	mkdir -p "$destdir"
+
+	# Clean up dangling symlinks in $destdir
+	for link in "$destdir"/*; do
+		[ -e "$link" ] || [ -L "$link" ] || continue
+		if [ -L "$link" ] && [ ! -e "$link" ]; then
+			log "removing broken symlink: $link"
+			rm -f "$link"
+		fi
+	done
+
+	# Project scope only: keep the generated symlinks out of git via a single
+	# .gitignore per platform base dir (the dest's parent), listing each
+	# symlink subdir. The canonical content lives in (tracked) .agents/.
+	prefix=""
+	case "$AGENTS_DIR" in
+		/*) ;;
+		*)
+			prefix="$(up_to_root "$destdir")"
+			gi="$(dirname "$destdir")/.gitignore"
+			entry="$(basename "$destdir")/"
+			if [ ! -f "$gi" ] || ! grep -qxF "$entry" "$gi"; then
+				printf '%s\n' "$entry" >>"$gi"
+			fi
+			;;
+	esac
+
+	for item in "$srcdir"/*; do
+		[ -e "$item" ] || continue
+		name="$(basename "$item")"
+		link_item "${prefix}${srcdir}/${name}" "$destdir/$name"
+	done
+done
+
+log "done."

package/dist/skills/update-agents-md/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: update-agents-md
+description: Refactor a project's AGENTS.md (or CLAUDE.md) file to follow progressive disclosure. Use when requested to reorganize workspace instructions, reduce context bloat, group guidelines, or extract essential workflows.
+---
+
+# Update Agents MD
+
+Refactor `AGENTS.md` (or `CLAUDE.md`) to follow progressive disclosure principles, ensuring context-window efficiency and clarity.
+
+## Workflow
+
+### 1. Analyze and Identify
+
+- Read the existing `AGENTS.md` (or `CLAUDE.md`) file in the workspace root.
+- Find contradictions or overlapping rules/instructions.
+- Flag instructions that are redundant, vague, or overly obvious for deletion (e.g., basic IDE usage, standard Git commands, or generic advice).
+- Identify the core essentials for the root file:
+  - A one-line description of the project.
+  - The package manager used (e.g., `npm`, `pnpm`, `yarn`, `bun`).
+  - Core build, typecheck, lint, and test commands.
+  - The 2–3 most critical workflows (e.g., local development, running tests, preparing a release).
+
+### 2. User Alignment
+
+- Present all identified contradictions, redundancies, and proposed deletions to the user.
+- Ask the user which conflicting instructions to keep and confirm the items proposed for deletion.
+- **Stop and wait** for explicit user confirmation before proceeding with modifications.
+
+### 3. Extract and Delegate
+
+- Group the remaining guidelines and instructions into clear, logical categories (e.g., database, testing, frontend styling, deployment).
+- For each category, create a separate markdown file under a `docs/` folder (e.g., `docs/database-guidelines.md`).
+- For any complex procedural instructions or task-specific workflows (e.g., how to run a custom migration script, how to publish a package), extract them into a local skill under `.agents/skills/<name>/SKILL.md`.
+
+### 4. Construct Minimal Root File
+
+- Re-write the root `AGENTS.md` (or `CLAUDE.md`) to be extremely minimal.
+- Structure it to contain:
+  1. A one-line description of the project.
+  2. The package manager and build/typecheck commands.
+  3. The 2–3 most critical workflows formatted as numbered steps.
+  4. A list of links to the category files under `docs/` (e.g., `[Database Guidelines](docs/database.md)`), with a one-line description explaining when to consult each file.
+- Replace verbose inline code snippets in instructions with precise `file:line` links pointing directly to the source code (e.g., `see [main.ts:L45-L60](file:///path/to/main.ts#L45-L60)`).