@rtorcato/repo-tooling 3.9.2 → 3.10.1

package/AGENTS.md

@@ -82,12 +82,19 @@ npx @rtorcato/repo-tooling fix dependabot --yes --json
 npx @rtorcato/repo-tooling fix engines --yes --json
 npx @rtorcato/repo-tooling fix docs-site --yes --json   # scaffold a Docusaurus docs site under apps/docs
 npx @rtorcato/repo-tooling fix bun --yes --json         # Bun runtime/test config
+
+# Opt-in only — writes user-global state, so a bare `fix` / `fix --yes` skips it.
+# Installs the ai-issue-loop skill to ~/.claude/skills. Override with --skills-dir,
+# which is required alongside --yes/--json when that directory doesn't exist.
+npx @rtorcato/repo-tooling fix claude-skills --yes --json
 ```
 
 ## Drift policy (important)
 
 `fix` defaults the confirm prompt to **No** for drift cases (existing file that doesn't extend our preset). The `--yes` flag is required to overwrite drift. Safe-merge fixers (`engines`, `husky`, `package-json`) never overwrite — they add/merge — and use friendlier prompt wording. `fix --json` implies `--yes` (prompts would corrupt JSON output).
 
+Fixers marked `explicitOnly` are exempt from `fix` all *and* from `fix --yes` — they only run when named as the target. Today that is `claude-skills`, the one fixer whose blast radius is outside the repo.
+
 ## Source-of-truth files in the repo
 
 - `src/cli/commands/setup.ts` — `ProjectConfig` interface and the setup orchestrator

package/README.md

@@ -174,14 +174,25 @@ ln -sf ../../node_modules/@rtorcato/repo-tooling/tooling/claude/repo-tooling.md
 ### Use with Claude Code (plugin)
 
 This repo is also a self-hosted Claude Code marketplace. Install the plugin to
-get two skills — `repo-tooling` (adopt/audit the presets via the CLI) and
-`npm-publish` (the family's release rules) — in any session:
+get three skills — `repo-tooling` (adopt/audit the presets via the CLI),
+`npm-publish` (the family's release rules) and `ai-issue-loop` (the label-driven
+issue → PR pipeline) — in any session:
 
 ```
 /plugin marketplace add rtorcato/repo-tooling
 /plugin install repo-tooling@repo-tooling
 ```
 
+`ai-issue-loop` also installs on its own, user-globally, so every repo on the
+machine shares one copy:
+
+```bash
+npx @rtorcato/repo-tooling fix claude-skills   # → ~/.claude/skills/ai-issue-loop/SKILL.md
+```
+
+It writes outside the repo, so it is opt-in: a bare `fix` skips it. See the
+[AI Issue Loop guide](https://rtorcato.github.io/repo-tooling/guides/ai-issue-loop/).
+
 ### Use with other AI tools (Cursor / Copilot / Codex)
 
 [`AGENTS.md`](AGENTS.md) at the repo root carries the same guidance in the
@@ -217,7 +228,8 @@ MIT — see [LICENSE](LICENSE).
 Any agent that supports the [`skills`](https://www.npmjs.com/package/skills) CLI can install this repo's skills straight from GitHub — no clone, no package install:
 
 ```bash
-npx skills add https://github.com/rtorcato/repo-tooling --skill repo-tooling
+npx skills add https://github.com/rtorcato/repo-tooling --skill ai-issue-loop
 npx skills add https://github.com/rtorcato/repo-tooling --skill npm-publish
+npx skills add https://github.com/rtorcato/repo-tooling --skill repo-tooling
 ```
 <!-- js-tooling:skills:end -->

package/dist/base/checks.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import fs from 'fs-extra';
 import { BLOCK_START, hasStaleAgentBlock } from '../cli/generators/agent-rules.js';
 import { BADGE_START, hasPublicOnlyBadges } from '../cli/generators/badges.js';
+import { claudeSkillStatus, SHIPPED_SKILL } from '../cli/generators/claude-skills.js';
 import { detectNestedLanguages } from '../cli/utils/detect-language.js';
 /**
  * Root-only detection is the decision (#317), not an oversight — but it used to
@@ -428,6 +429,43 @@ export async function checkAiSetup(dir) {
         hint: 'Run `npx @rtorcato/repo-tooling fix ai` to scaffold agent rules for every AI tool',
     };
 }
+/**
+ * The user-global agent skills this package ships (#404).
+ *
+ * The only check that reports on state *outside* the repo being audited, which
+ * is why it never returns `drift` or `missing`: an out-of-date `~/.claude/skills`
+ * is not a defect in this repo, and either of those statuses would fail its CI
+ * over a file CI has never seen. `optional-missing` is the honest verdict — an
+ * opt-in workflow tool that isn't configured — and it leaves the exit code alone.
+ */
+export async function checkClaudeSkills() {
+    const check = 'Claude skills';
+    const hint = `Run \`npx @rtorcato/repo-tooling fix claude-skills\` to install the ${SHIPPED_SKILL} skill (writes outside the repo; opt-in, so \`fix\` alone skips it)`;
+    const status = await claudeSkillStatus();
+    if (!status.installed) {
+        return {
+            check,
+            status: 'optional-missing',
+            detail: status.file
+                ? `${SHIPPED_SKILL} skill is not installed`
+                : `no ~/.claude/skills — the ${SHIPPED_SKILL} skill is not installed`,
+            hint,
+        };
+    }
+    if (status.needsInstall) {
+        return {
+            check,
+            status: 'optional-missing',
+            detail: `${SHIPPED_SKILL} skill is at ${status.installedVersion ?? 'an unstamped version'}; this package ships ${status.shippedVersion}`,
+            hint,
+        };
+    }
+    return {
+        check,
+        status: 'ok',
+        detail: `${SHIPPED_SKILL} skill installed at ${status.installedVersion}`,
+    };
+}
 /**
  * Conventional Commits is a repo convention, not a JavaScript one — the config
  * file is the same in any repo that has node available to run commitlint, so

package/dist/base/fixers.js

@@ -11,8 +11,12 @@
  * language-shaped (CI steps, recorded tool choices), so each module ships its
  * own — see src/base/ci.ts for the shell they share.
  */
+import os from 'node:os';
+import path from 'node:path';
 import chalk from 'chalk';
+import inquirer from 'inquirer';
 import { installAgentRules, installAiSetup } from '../cli/generators/agent-rules.js';
+import { installClaudeSkill, resolveSkillsDir, SHIPPED_SKILL, } from '../cli/generators/claude-skills.js';
 import { generateBrand } from '../cli/generators/brand.js';
 import { generateCommunityHealth } from '../cli/generators/community-health.js';
 import { generateCommitlintConfig } from '../cli/generators/git.js';
@@ -27,6 +31,31 @@ import { closeCompletedMilestones } from './milestones.js';
 async function moduleFor(targetDir) {
     return resolveLanguageModule(await detectLanguage(targetDir));
 }
+/**
+ * Where to install user-global skills, asking only when nothing resolves. Under
+ * `--yes` / `--json` a prompt is not available — `--json` would have its payload
+ * corrupted by one — so an unresolvable destination becomes an advisory and a
+ * no-op rather than a guess at a directory the user never mentioned.
+ */
+async function resolveInstallDir(explicit, assumeYes) {
+    const { dir } = await resolveSkillsDir(explicit);
+    if (dir)
+        return dir;
+    if (assumeYes) {
+        console.error(chalk.yellow('   skipped — no ~/.claude/skills found; pass --skills-dir <path>'));
+        return null;
+    }
+    const { answer } = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'answer',
+            message: 'Install agent skills where?',
+            default: path.join(os.homedir(), '.claude', 'skills'),
+        },
+    ]);
+    const trimmed = typeof answer === 'string' ? answer.trim() : '';
+    return trimmed ? path.resolve(trimmed) : null;
+}
 export const BASE_FIXERS = [
     {
         target: 'editorconfig',
@@ -219,6 +248,37 @@ export const BASE_FIXERS = [
             return { filesWritten: [result.target] };
         },
     },
+    {
+        target: 'claude-skills',
+        description: `Install the ${SHIPPED_SKILL} Claude Code skill into the user-level skills dir (~/.claude/skills, or --skills-dir). Writes outside the repo`,
+        appliesTo: ['Claude skills'],
+        outputs: [`~/.claude/skills/${SHIPPED_SKILL}/SKILL.md`],
+        // safe-add is load-bearing for the same reason it is on github-settings:
+        // it exempts this fixer from the `--diff` shadow-run, which copies the repo
+        // to tmp and *executes* run() — here that would write to the real home dir
+        // during what the user asked to be a preview.
+        riskLevel: 'safe-add',
+        explicitOnly: true,
+        canFixDrift: true,
+        async run({ skillsDir, assumeYes }) {
+            const dir = await resolveInstallDir(skillsDir, assumeYes);
+            if (!dir)
+                return { filesWritten: [] };
+            const result = await installClaudeSkill(dir);
+            if (result.status === 'declined-downgrade') {
+                console.error(chalk.yellow(`   skipped — ${result.file} is at ${result.installedVersion}, newer than the ${result.shippedVersion} this package ships`));
+                return { filesWritten: [] };
+            }
+            if (result.status === 'up-to-date')
+                return { filesWritten: [] };
+            // Report the resolved real path when the skill is a stow symlink: the bytes
+            // landed in a dotfiles checkout, and that is where the user has to commit them.
+            if (result.viaSymlink) {
+                console.error(chalk.dim(`   wrote through a symlink — commit ${result.realFile}`));
+            }
+            return { filesWritten: [result.realFile] };
+        },
+    },
     {
         target: 'cursor-rules',
         description: 'Install the repo-tooling rules for Cursor (.cursor/rules/repo-tooling.mdc)',

package/dist/cli/commands/doctor.js

@@ -17,7 +17,7 @@ import { checkMilestones } from '../../base/milestones.js';
 import { checkGitIdentity } from '../../base/git-identity.js';
 import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
 import { declinedInLock, getFixTargetForCheck } from './fix-targets.js';
-import { checkAiSetup, checkBrand, checkCodeowners, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkNestedLanguages, checkPrePushHook, checkReadmeBadges, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
+import { checkAiSetup, checkBrand, checkCodeowners, checkClaudeSkills, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkNestedLanguages, checkPrePushHook, checkReadmeBadges, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
 import { allDeps, checkAreTheTypesWrong, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
 export { evaluateNodeVersion };
 const PACKAGE = '@rtorcato/repo-tooling';
@@ -171,6 +171,8 @@ async function runBaseChecks(dir, lock, opts) {
     results.push(await checkCommunityHealth(dir));
     results.push(await checkBrand(dir));
     results.push(await checkAiSetup(dir));
+    // User-global, not repo state — see checkClaudeSkills on why it never returns drift.
+    results.push(await checkClaudeSkills());
     results.push(await checkReadmeBadges(dir, opts.badges.audience, opts.badges.fixTarget));
     results.push(await checkCoverageUpload(dir));
     return results;

package/dist/cli/commands/fix-targets.js

@@ -46,6 +46,7 @@ export const FIX_TARGETS = {
     TypeDoc: 'typedoc',
     'AI setup': 'ai',
     'Claude worktree settings': 'ai',
+    'Claude skills': 'claude-skills',
 };
 /**
  * Where the Swift module's fixers shadow (or extend) the JS-named defaults

package/dist/cli/commands/fix.js

@@ -132,7 +132,8 @@ async function previewFixer(fixer, result, targetDir, pkg, lock) {
                 return first !== 'node_modules' && first !== 'dist' && first !== 'build' && first !== '.git';
             },
         });
-        await fixer.run({ targetDir: tmpDir, pkg, result, lock });
+        // assumeYes: a preview must never prompt.
+        await fixer.run({ targetDir: tmpDir, pkg, result, lock, assumeYes: true });
         const previews = [];
         const seen = new Set();
         for (const output of fixer.outputs) {
@@ -186,14 +187,14 @@ function printPreviews(previews) {
         }
     }
 }
-async function applyFixer(fixer, result, targetDir, pkg, lock, dryRun, silent) {
+async function applyFixer(fixer, result, targetDir, pkg, lock, dryRun, silent, opts) {
     if (dryRun) {
         if (!silent) {
             console.log(chalk.cyan(`  [dry-run] would write: ${fixer.outputs.join(', ')}`));
         }
         return { filesWritten: [], dryRun: true };
     }
-    const { filesWritten } = await fixer.run({ targetDir, pkg, result, lock });
+    const { filesWritten } = await fixer.run({ targetDir, pkg, result, lock, ...opts });
     if (!silent && filesWritten.length > 0) {
         console.log(chalk.green(`  ✅ wrote ${filesWritten.join(', ')}`));
     }
@@ -397,7 +398,10 @@ export async function fixCommand(target, options = {}) {
             console.log(chalk.gray('   skipped\n'));
             return;
         }
-        const outcome = await applyFixer(fixer, effectiveResult, targetDir, pkg, lock, dryRun, silent);
+        const outcome = await applyFixer(fixer, effectiveResult, targetDir, pkg, lock, dryRun, silent, {
+            skillsDir: options.skillsDir,
+            assumeYes,
+        });
         actions.push(recordFor(fixer.target, result.check, effectiveResult.status, outcome.dryRun ? 'dry-run' : 'applied', outcome.filesWritten, conflict));
         if (json)
             return emitJson(fixer.target);
@@ -429,6 +433,15 @@ export async function fixCommand(target, options = {}) {
         if (!silent) {
             console.log(`  ${chalk.bold(result.check)} (${result.status}) → ${fixer.target}`);
         }
+        // Opt-in only — `--yes` must not sweep in a fixer that writes outside the repo.
+        if (fixer.explicitOnly) {
+            actions.push(recordFor(fixer.target, result.check, result.status, 'skipped', []));
+            if (!silent) {
+                console.log(chalk.gray(`    skipped — run \`fix ${fixer.target}\` explicitly`));
+            }
+            skippedCount++;
+            continue;
+        }
         const conflict = noteLockConflict(result.check);
         if (showDiff && (fixer.riskLevel ?? 'destructive') !== 'safe-add') {
             const previews = await previewFixer(fixer, result, targetDir, pkg, lock);
@@ -442,7 +455,10 @@ export async function fixCommand(target, options = {}) {
             skippedCount++;
             continue;
         }
-        const outcome = await applyFixer(fixer, result, targetDir, pkg, lock, dryRun, silent);
+        const outcome = await applyFixer(fixer, result, targetDir, pkg, lock, dryRun, silent, {
+            skillsDir: options.skillsDir,
+            assumeYes,
+        });
         actions.push(recordFor(fixer.target, result.check, result.status, outcome.dryRun ? 'dry-run' : 'applied', outcome.filesWritten, conflict));
         appliedCount++;
     }

package/dist/cli/generators/agent-rules.js

@@ -1,7 +1,9 @@
+import { glob } from 'node:fs/promises';
 import path from 'node:path';
 import fs from 'fs-extra';
 import { copyPreset, getPackageRoot } from '../utils/copy-preset.js';
 import { LEGACY_TOOL_NAME } from '../utils/lockfile.js';
+import { parseWorkspacePackages } from './misc.js';
 import { installSkillsInstallDocs } from './skills-install.js';
 /**
  * All agent rule files are generated from one source of truth — the shipped
@@ -41,6 +43,62 @@ function asObject(value) {
         ? value
         : null;
 }
+/**
+ * True when `rel` resolves to something at or under `targetDir`. The entries
+ * this guards end up in `worktree.symlinkDirectories`, which Claude Code reads
+ * as symlink targets — an escaping path would point a worktree symlink outside
+ * the repo, so a workspace glob is never trusted to stay inside on its own.
+ */
+function isInside(targetDir, rel) {
+    const outward = path.relative(path.resolve(targetDir), path.resolve(targetDir, rel));
+    return outward !== '' && !outward.startsWith('..') && !path.isAbsolute(outward);
+}
+/**
+ * The repo's own workspace globs, from `pnpm-workspace.yaml` and/or
+ * package.json `workspaces` (both array and `{ packages: [] }` forms). Both
+ * are read because a pnpm repo can keep its globs in either file.
+ *
+ * Negations (`!apps/x`) are dropped, and so is anything absolute or containing
+ * a `..` segment: a `packages: - '../shared-lib'` entry reads as plausible in a
+ * monorepo but would write an out-of-repo symlink target into settings.json.
+ */
+async function workspaceGlobs(targetDir) {
+    const yamlFile = path.join(targetDir, 'pnpm-workspace.yaml');
+    const yaml = (await fs.pathExists(yamlFile)) ? await fs.readFile(yamlFile, 'utf-8') : '';
+    const pkg = asObject(await fs.readJson(path.join(targetDir, 'package.json')).catch(() => null));
+    const field = Array.isArray(pkg?.workspaces)
+        ? pkg.workspaces
+        : asObject(pkg?.workspaces)?.packages;
+    const declared = Array.isArray(field) ? field : [];
+    return [...parseWorkspacePackages(yaml), ...declared].filter((g) => typeof g === 'string' &&
+        !g.startsWith('!') &&
+        !path.isAbsolute(g) &&
+        !g.split(/[\\/]/).includes('..'));
+}
+/**
+ * The nested `<workspace>/node_modules` to symlink alongside the root one
+ * (#406). Without them a workspace-scoped command in a fresh worktree fails on
+ * a missing binary — `pnpm --filter <pkg> build` can't find its bin shims —
+ * which reads as a broken toolchain rather than a missing symlink.
+ *
+ * Derived from the repo's own workspace globs, never a hardcoded layout: this
+ * is a public CLI and every consumer nests its packages differently.
+ * Workspaces with no `node_modules` in the main checkout are skipped, because
+ * an entry pointing at nothing warns on every worktree creation.
+ */
+export async function workspaceSymlinkDirs(targetDir) {
+    const globs = await workspaceGlobs(targetDir);
+    if (globs.length === 0)
+        return [];
+    const found = [];
+    for await (const match of glob(globs.map((g) => `${g}/node_modules`), { cwd: targetDir })) {
+        // Belt and braces: the glob result is what actually gets written, so it is
+        // re-checked for containment even though the input globs were filtered.
+        if (isInside(targetDir, match))
+            found.push(match.split(path.sep).join('/'));
+    }
+    return found.sort();
+}
 /** Parsed `.claude/settings.json`, or null when absent, malformed, or not an object. */
 export async function readClaudeSettings(targetDir) {
     try {
@@ -74,10 +132,8 @@ export async function installClaudeSettings(targetDir) {
     if (!settings)
         return null;
     const existing = worktreeSymlinkDirs(settings);
-    const symlinkDirectories = [
-        ...existing,
-        ...WORKTREE_SYMLINK_DIRS.filter((d) => !existing.includes(d)),
-    ];
+    const wanted = [...WORKTREE_SYMLINK_DIRS, ...(await workspaceSymlinkDirs(targetDir))];
+    const symlinkDirectories = [...existing, ...wanted.filter((d) => !existing.includes(d))];
     const worktree = { ...asObject(settings.worktree), symlinkDirectories };
     await fs.outputJson(file, { ...settings, worktree }, { spaces: 2 });
     return CLAUDE_SETTINGS_FILE;

package/dist/cli/generators/claude-skills.js

@@ -0,0 +1,144 @@
+/**
+ * User-global agent skills (#404). Every other generator writes inside the repo;
+ * this one writes to `~/.claude/skills/<name>/SKILL.md`, which is shared by every
+ * project on the machine. That difference drives all three rules below — the
+ * version stamp, the symlink handling, and the fixer's opt-in `explicitOnly`.
+ */
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'fs-extra';
+import { getPackageRoot } from '../utils/copy-preset.js';
+/** Skills this package owns the content of and keeps up to date. */
+export const SHIPPED_SKILL = 'ai-issue-loop';
+/**
+ * Stamped into the installed copy's frontmatter so a second repo pinned to an
+ * older release can tell it would be a downgrade and skip. Without it two repos
+ * on different versions overwrite each other's skill on every `fix`, and neither
+ * is wrong to do so.
+ */
+export const VERSION_KEY = 'repo-tooling-version';
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
+/**
+ * Where to install. `explicit` is `--skills-dir`; otherwise the user-level
+ * `~/.claude/skills` when it already exists. A machine with neither resolves to
+ * null rather than creating `~/.claude` uninvited.
+ *
+ * There is deliberately no separate "symlinked" case: a stow-managed
+ * `SKILL.md` symlink lives *inside* that same directory, and writing through it
+ * is what `installClaudeSkill` already does. See its note.
+ */
+export async function resolveSkillsDir(explicit, home = os.homedir()) {
+    if (explicit)
+        return { dir: path.resolve(explicit), source: 'explicit' };
+    const userDir = path.join(home, '.claude', 'skills');
+    if (await fs.pathExists(userDir))
+        return { dir: userDir, source: 'user' };
+    return { dir: null, source: 'none' };
+}
+/** The version recorded in an installed copy, or null if it predates the stamp. */
+export function readSkillVersion(content) {
+    return content.match(new RegExp(`^${VERSION_KEY}:\\s*(.+)$`, 'm'))?.[1]?.trim() ?? null;
+}
+/**
+ * Replace (or add) the version line in the frontmatter. Appending it last is
+ * safe even after a multi-line `description: |` block: an unindented key ends
+ * the block scalar, which is exactly what this line is.
+ */
+export function stampSkillVersion(content, version) {
+    const stamp = `${VERSION_KEY}: ${version}`;
+    const match = content.match(FRONTMATTER);
+    if (!match)
+        return `---\n${stamp}\n---\n\n${content}`;
+    const fields = (match[1] ?? '')
+        .split('\n')
+        .filter((line) => !line.startsWith(`${VERSION_KEY}:`))
+        .join('\n');
+    return `---\n${fields}\n${stamp}\n---\n${content.slice(match[0].length)}`;
+}
+function versionParts(version) {
+    return version.split('.').map((n) => Number.parseInt(n, 10) || 0);
+}
+/** True when `a` is a strictly higher version than `b`. Prerelease tags are ignored. */
+export function isNewerVersion(a, b) {
+    const [left, right] = [versionParts(a), versionParts(b)];
+    for (let i = 0; i < 3; i++) {
+        const [x, y] = [left[i] ?? 0, right[i] ?? 0];
+        if (x !== y)
+            return x > y;
+    }
+    return false;
+}
+/** The skill source and the package version that will be stamped into it. */
+export async function readShippedSkill(name = SHIPPED_SKILL) {
+    const root = getPackageRoot();
+    const content = await fs.readFile(path.join(root, 'skills', name, 'SKILL.md'), 'utf8');
+    const pkg = await fs.readJson(path.join(root, 'package.json'));
+    return { content, version: String(pkg.version) };
+}
+/** Whether `file` is itself a symlink, as opposed to merely resolving through one. */
+async function isSymlink(file) {
+    return await fs
+        .lstat(file)
+        .then((stat) => stat.isSymbolicLink())
+        .catch(() => false);
+}
+/**
+ * Install (or refresh) one shipped skill under `skillsDir`.
+ *
+ * **Writes through a symlink on purpose.** stow symlinks dotfiles at *file*
+ * level, so `~/.claude/skills/ai-issue-loop/SKILL.md` is routinely a link into a
+ * dotfiles checkout while its parent directories are real. `fs.writeFile`
+ * follows the link and updates the dotfiles copy in place, which is the whole
+ * point — the skill stays version-controlled with the rest of the Claude config.
+ * Never swap this for an atomic-rename helper (`write-file-atomic` and friends):
+ * rename *replaces* the symlink with a real file, orphaning the dotfiles copy
+ * with no error at all, which is the split-brain this feature exists to end.
+ */
+export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL) {
+    const shipped = await readShippedSkill(name);
+    const file = path.join(skillsDir, name, 'SKILL.md');
+    const existing = (await fs.pathExists(file)) ? await fs.readFile(file, 'utf8') : null;
+    const installedVersion = existing ? readSkillVersion(existing) : null;
+    const viaSymlink = await isSymlink(file);
+    const base = {
+        name,
+        file,
+        viaSymlink,
+        realFile: viaSymlink ? await fs.realpath(file) : file,
+        installedVersion,
+        shippedVersion: shipped.version,
+    };
+    if (installedVersion && isNewerVersion(installedVersion, shipped.version)) {
+        return { ...base, status: 'declined-downgrade' };
+    }
+    const next = stampSkillVersion(shipped.content, shipped.version);
+    if (existing === next)
+        return { ...base, status: 'up-to-date' };
+    await fs.ensureDir(path.dirname(file));
+    await fs.writeFile(file, next);
+    return { ...base, status: existing === null ? 'installed' : 'updated' };
+}
+/** Read-only counterpart of `installClaudeSkill`, for doctor. */
+export async function claudeSkillStatus(name = SHIPPED_SKILL, explicit) {
+    const { version } = await readShippedSkill(name);
+    const { dir } = await resolveSkillsDir(explicit);
+    const absent = {
+        installed: false,
+        installedVersion: null,
+        shippedVersion: version,
+        needsInstall: true,
+    };
+    if (!dir)
+        return { file: null, ...absent };
+    const file = path.join(dir, name, 'SKILL.md');
+    if (!(await fs.pathExists(file)))
+        return { file, ...absent };
+    const installedVersion = readSkillVersion(await fs.readFile(file, 'utf8'));
+    return {
+        file,
+        installed: true,
+        installedVersion,
+        shippedVersion: version,
+        needsInstall: installedVersion === null || isNewerVersion(version, installedVersion),
+    };
+}

package/dist/cli/generators/misc.js

@@ -256,7 +256,7 @@ export async function ensurePackageManager(targetDir, version = detectPnpmVersio
  * YAML dependency. Matches `- 'apps/*'` / `- "apps/*"` / `- apps/*` entries
  * under the `packages:` key, stopping at the next top-level key.
  */
-function parseWorkspacePackages(yaml) {
+export function parseWorkspacePackages(yaml) {
     const globs = [];
     let inPackages = false;
     for (const line of yaml.split('\n')) {

package/dist/cli/index.js

@@ -287,6 +287,12 @@ const TOOL_CATALOG = [
         exports: [],
         fixTarget: 'ai',
     },
+    {
+        name: 'Claude skills',
+        description: 'Install the ai-issue-loop skill into ~/.claude/skills (user-global, opt-in — see --skills-dir)',
+        exports: [],
+        fixTarget: 'claude-skills',
+    },
 ];
 program
     .command('list')
@@ -321,6 +327,7 @@ program
     .option('--list', 'List all registered fix targets and exit')
     .option('--resync', 'Re-scaffold every file recorded in .repo-tooling.json')
     .option('--diff', 'Show a unified diff of each change before confirming')
+    .option('--skills-dir <path>', 'Where `fix claude-skills` installs user-global agent skills (default: ~/.claude/skills). Required with --yes/--json when that directory does not exist')
     .action((target, options) => fixCommand(target, {
     directory: options.directory,
     yes: options.yes,
@@ -329,6 +336,7 @@ program
     list: options.list,
     resync: options.resync,
     diff: options.diff,
+    skillsDir: options.skillsDir,
 }));
 program.hook('preAction', async (_, actionCommand) => {
     const name = actionCommand.name();

package/dist/languages/js/checks.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import fs from 'fs-extra';
 import { hookHasUncommented } from '../../base/checks.js';
-import { CLAUDE_SETTINGS_FILE, readClaudeSettings, worktreeSymlinkDirs, } from '../../cli/generators/agent-rules.js';
+import { CLAUDE_SETTINGS_FILE, readClaudeSettings, workspaceSymlinkDirs, worktreeSymlinkDirs, } from '../../cli/generators/agent-rules.js';
 import { WORKSPACE_FILE, dependsOnEsbuild, familyGlob, missingPnpmSettings, } from '../../cli/generators/pnpm-workspace.js';
 const PACKAGE = '@rtorcato/repo-tooling';
 const NODE_MIN_MAJOR = 22;
@@ -980,13 +980,20 @@ export async function checkClaudeWorktreeSettings(dir) {
             hint: `Repair the JSON in ${CLAUDE_SETTINGS_FILE} by hand — \`fix ai\` refuses to overwrite it`,
         };
     }
-    if (worktreeSymlinkDirs(settings).includes('node_modules')) {
-        return { check, status: 'ok', detail: 'worktree.symlinkDirectories carries node_modules' };
+    const recorded = worktreeSymlinkDirs(settings);
+    const wanted = ['node_modules', ...(await workspaceSymlinkDirs(dir))];
+    const missing = wanted.filter((d) => !recorded.includes(d));
+    if (missing.length === 0) {
+        return {
+            check,
+            status: 'ok',
+            detail: `worktree.symlinkDirectories carries ${wanted.join(', ')}`,
+        };
     }
     return {
         check,
         status: 'optional-missing',
-        detail: `${CLAUDE_SETTINGS_FILE} has no worktree.symlinkDirectories entry for node_modules`,
+        detail: `${CLAUDE_SETTINGS_FILE} has no worktree.symlinkDirectories entry for ${missing.join(', ')}`,
         hint,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.9.2",
+	"version": "3.10.1",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [
@@ -108,6 +108,7 @@
 		"tooling/perl/perlcriticrc",
 		"tooling/perl/perltidyrc",
 		"tooling/github-actions/workflows/*.yml",
+		"skills/*/SKILL.md",
 		"README.md",
 		"AGENTS.md"
 	],