@kurokeita/add-skill 1.21.0 → 2.0.0

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)`).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurokeita/add-skill",
-	"version": "1.21.0",
+	"version": "2.0.0",
 	"description": "CLI to install AI agent skills to various platforms",
 	"type": "module",
 	"bin": {
@@ -12,7 +12,6 @@
 	],
 	"scripts": {
 		"dev": "tsx bin/cli.ts",
-		"update:readme": "tsx scripts/update-readme.ts",
 		"build": "tsc --noEmit && esbuild bin/cli.ts --bundle --platform=node --format=esm --outfile=dist/bin/cli.js --packages=external && tsx scripts/copy-assets.ts",
 		"prepublishOnly": "pnpm run build",
 		"test": "vitest run",
@@ -41,17 +40,15 @@
 		"@clack/prompts": "^1.2.0",
 		"commander": "^14.0.2",
 		"fs-extra": "^11.3.3",
-		"js-yaml": "^4.1.1",
 		"picocolors": "^1.1.1"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.3.11",
 		"@semantic-release/git": "^10.0.1",
 		"@types/fs-extra": "^11.0.4",
-		"@types/js-yaml": "^4.0.9",
 		"@types/node": "^25.0.9",
 		"@vitest/coverage-v8": "^4.0.18",
-		"esbuild": "^0.25.0",
+		"esbuild": "^0.28.1",
 		"markdownlint-cli": "^0.47.0",
 		"semantic-release": "^25.0.2",
 		"tsx": "^4.21.0",