feat(sync): link skills into .agents/skills

Also removes links left in skills/ by earlier syncs, matched by name
since their targets may no longer exist.

Author: natemoo-re

.changeset/sync-agents-skills.md

@@ -0,0 +1,5 @@
+---
+'@bomb.sh/tools': minor
+---
+
+Changes `bsh sync` to link skills into `.agents/skills/` instead of `skills/`. Re-run `bsh sync` to move existing links; it removes the old `skills/` links and updates the `.gitignore` and `AGENTS.md` entries.

README.md

@@ -16,4 +16,4 @@ If you'd like to use this package for your own projects, please consider forking
 
 ## Agent Skills
 
-If you use an AI coding agent, run `pnpm bsh sync` to symlink this package's skill files into your project's `skills/` directory. Synced skills are automatically added to your `.gitignore`, and an index of them is maintained in your `AGENTS.md`. Claude Code users: add `@AGENTS.md` to your project's `CLAUDE.md`.
+If you use an AI coding agent, run `pnpm bsh sync` to symlink this package's skill files into your project's `.agents/skills/` directory. Synced skills are automatically added to your `.gitignore`, and an index of them is maintained in your `AGENTS.md`.

src/commands/sync.ts

@@ -13,6 +13,9 @@ const SENTINEL_START = '<!-- bsh:skills -->';
 const SENTINEL_END = '<!-- /bsh:skills -->';
 const GITIGNORE_START = '# bsh:skills';
 const GITIGNORE_END = '# /bsh:skills';
+const SKILLS_DIR = '.agents/skills/';
+// Where syncs before `.agents/skills/` linked skills.
+const LEGACY_SKILLS_DIR = 'skills/';
 
 export async function sync(_ctx: CommandContext): Promise<void> {
 	const parentPkg = await findParentPackage();
@@ -29,11 +32,12 @@ export async function sync(_ctx: CommandContext): Promise<void> {
 		return;
 	}
 
-	const skills = await copySkills({ source, dest: new URL('skills/', root) });
+	const skills = await copySkills({ source, dest: new URL(SKILLS_DIR, root) });
+	await removeLegacyLinks({ dir: new URL(LEGACY_SKILLS_DIR, root), skills });
 	await updateGitignore({ root, skills });
 	await updateAgentsMd({ root, skills });
 
-	console.info(`Synced ${skills.length} skills to skills/`);
+	console.info(`Synced ${skills.length} skills to ${SKILLS_DIR}`);
 }
 
 interface SkillInfo {
@@ -105,12 +109,33 @@ async function pruneStaleLinks(options: {
 	}
 }
 
+/**
+ * Remove links from syncs that predate `.agents/skills/`. Match by name, not
+ * target: after an upgrade those links point into a store path that may no
+ * longer exist. Anything that isn't a symlink is left alone.
+ */
+async function removeLegacyLinks(options: { dir: URL; skills: SkillInfo[] }): Promise<void> {
+	const { dir, skills } = options;
+	if (!(await hfs.isDirectory(dir))) return;
+
+	const names = new Set(skills.map((s) => s.name));
+	let remaining = 0;
+	for await (const entry of hfs.list(dir)) {
+		if (entry.isSymlink && names.has(entry.name)) {
+			await rm(fileURLToPath(new URL(entry.name, dir)));
+		} else {
+			remaining++;
+		}
+	}
+	if (remaining === 0) await hfs.delete(dir);
+}
+
 async function updateGitignore(options: { root: URL; skills: SkillInfo[] }): Promise<void> {
 	const { root, skills } = options;
 	const gitignorePath = new URL('.gitignore', root);
 	let content = (await hfs.text(gitignorePath)) ?? '';
 
-	const lines = skills.map((s) => `skills/${s.name}/`);
+	const lines = skills.map((s) => `${SKILLS_DIR}${s.name}/`);
 	const section = [GITIGNORE_START, ...lines, GITIGNORE_END].join('\n');
 
 	const startIdx = content.indexOf(GITIGNORE_START);
@@ -133,7 +158,8 @@ async function updateAgentsMd(options: { root: URL; skills: SkillInfo[] }): Prom
 
 	const lines = skills.map((s) => {
 		const desc = s.description.split('.')[0]?.trim();
-		return `- **${s.name}** — [skills/${s.name}/SKILL.md](skills/${s.name}/SKILL.md)${desc ? ` - ${desc}` : ''}`;
+		const path = `${SKILLS_DIR}${s.name}/SKILL.md`;
+		return `- **${s.name}** — [${path}](${path})${desc ? ` - ${desc}` : ''}`;
 	});
 
 	const section = [