@inbeat/standards 0.14.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.15.0](https://github.com/Genoux/ib-toolkit/compare/standards-v0.14.0...standards-v0.15.0) (2026-11-14)
4
+
5
+
6
+ ### Features
7
+
8
+ * **standards:** install shared third-party skills on create, sync and install ([#74](https://github.com/Genoux/ib-toolkit/issues/74)) ([c9a3388](https://github.com/Genoux/ib-toolkit/commit/c9a3388a405e3815c09a9be8016880f2d524ded7))
9
+
10
+
11
+ ### Bug Fixes
12
+
13
+ * **standards:** pin biome in the app template ([#67](https://github.com/Genoux/ib-toolkit/issues/67)) ([0a14baa](https://github.com/Genoux/ib-toolkit/commit/0a14baa9de9e6c8ff1c9464df0a70bbc94dbe026))
14
+
3
15
  ## [0.14.0](https://github.com/Genoux/ib-toolkit/compare/standards-v0.13.0...standards-v0.14.0) (2026-11-13)
4
16
 
5
17
 
@@ -0,0 +1,23 @@
1
+ # Skills every project gets. The toolkit's sync downloads the latest version
2
+ # of each from GitHub into the project's .agents/skills/, linked into
3
+ # .claude/skills/ for Claude Code (never committed).
4
+ #
5
+ # <owner/repo> <folder in the repo> [installed name]
6
+ # folder/* every skill folder inside folder
7
+ # file.md a single-file agent or skill, installed as <name>/SKILL.md
8
+ # . the whole repo is one skill (give the name)
9
+
10
+ # Design and UI
11
+ emilkowalski/skills skills/*
12
+ anthropics/skills skills/frontend-design
13
+ leonxlnx/taste-skill skills/taste-skill
14
+
15
+ # Code
16
+ anthropics/claude-plugins-official plugins/code-simplifier/agents/code-simplifier.md
17
+ planetscale/database-skills skills/postgres
18
+
19
+ # Workflow
20
+ mattpocock/skills skills/productivity/grill-me
21
+ mattpocock/skills skills/productivity/handoff
22
+ affaan-m/everything-claude-code skills/strategic-compact
23
+ rebelytics/one-skill-to-rule-them-all . task-observer
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@inbeat/standards",
3
- "version": "0.14.0",
4
- "description": "Agent standards for inBeat apps: managed AGENTS.md block, skills under .agents/skills, ib CLI",
3
+ "version": "0.15.0",
4
+ "description": "Agent standards for inBeat apps: managed AGENTS.md block, skills under .agents/skills, shared third-party skills, ib CLI",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "ib": "./src/cli.ts"
@@ -11,6 +11,7 @@
11
11
  "src",
12
12
  "agents",
13
13
  "skills",
14
+ "external-skills.txt",
14
15
  "template",
15
16
  "!src/**/*.test.ts",
16
17
  "!template/**/node_modules",
@@ -31,7 +32,7 @@
31
32
  "test": "bun --bun vitest run"
32
33
  },
33
34
  "devDependencies": {
34
- "@inbeat/config": "^0.14.0",
35
+ "@inbeat/config": "^0.15.0",
35
36
  "vitest": "^4.1.1"
36
37
  },
37
38
  "repository": {
package/src/cli.ts CHANGED
@@ -2,6 +2,7 @@
2
2
  import { resolve } from "node:path";
3
3
  import { create } from "./create";
4
4
  import { parseCreateArgs } from "./create-args";
5
+ import { formatReport, installExternalSkills } from "./external-skills";
5
6
  import { foundationProblems } from "./foundation";
6
7
  import { runMcp } from "./mcp";
7
8
  import { claudeFilesIgnoringAgents, staleFiles, write } from "./sync";
@@ -18,6 +19,23 @@ const USAGE = [
18
19
  const [command = "help", ...args] = process.argv.slice(2);
19
20
  const appDir = resolve(args.find((arg) => !arg.startsWith("--")) ?? ".");
20
21
 
22
+ // Downloads the shared third-party skills. A failed download warns and never fails the command.
23
+ // CI never uses them, and the app's postinstall would otherwise fetch them on every CI install.
24
+ function syncExternalSkills(dir: string): void {
25
+ // biome-ignore lint/style/noProcessEnv: CI is set by the CI provider, not app config
26
+ if (process.env.CI) {
27
+ console.info("skipped the shared skills (CI)");
28
+ return;
29
+ }
30
+ const report = installExternalSkills(dir);
31
+ for (const line of formatReport(report)) console.info(line);
32
+ if (report.failed.length > 0) {
33
+ console.warn(
34
+ `could not download some skills (offline?); run \`ib sync\` again later:\n ${report.failed.join("\n ")}`,
35
+ );
36
+ }
37
+ }
38
+
21
39
  const commands: Record<string, () => number | Promise<number>> = {
22
40
  create: async () => {
23
41
  let parsed: ReturnType<typeof parseCreateArgs>;
@@ -31,12 +49,14 @@ const commands: Record<string, () => number | Promise<number>> = {
31
49
  console.error(USAGE);
32
50
  return 1;
33
51
  }
52
+ // The skills arrive through the app's postinstall (`ib sync`), run by create's `bun install`.
34
53
  await create(parsed.dir, { local: parsed.local });
35
54
  return 0;
36
55
  },
37
56
  sync: () => {
38
57
  const written = write(appDir);
39
58
  console.info(written.length ? `updated:\n ${written.join("\n ")}` : "already up to date");
59
+ syncExternalSkills(appDir);
40
60
  return 0;
41
61
  },
42
62
  check: () => {
package/src/create.ts CHANGED
@@ -21,6 +21,7 @@ export type Manifest = {
21
21
  dependencies?: Dependencies;
22
22
  devDependencies?: Dependencies;
23
23
  peerDependencies?: Dependencies;
24
+ scripts?: Record<string, string>;
24
25
  [field: string]: unknown;
25
26
  };
26
27
 
@@ -77,6 +78,13 @@ export function rewriteManifest(
77
78
  ...manifest,
78
79
  ...resolved,
79
80
  name,
81
+ // `bun install` after a clone fetches the shared skills, which are never
82
+ // committed. Added here, not in the template: the template is a workspace of
83
+ // ib-toolkit, where it would download them on every toolkit install.
84
+ scripts: {
85
+ ...(manifest.scripts as Record<string, string> | undefined),
86
+ postinstall: "ib sync",
87
+ },
80
88
  ...(tarballs && { overrides: tarballs }),
81
89
  };
82
90
  }
@@ -0,0 +1,243 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import {
3
+ cpSync,
4
+ existsSync,
5
+ lstatSync,
6
+ mkdirSync,
7
+ mkdtempSync,
8
+ readdirSync,
9
+ readFileSync,
10
+ rmSync,
11
+ symlinkSync,
12
+ writeFileSync,
13
+ } from "node:fs";
14
+ import { tmpdir } from "node:os";
15
+ import { basename, dirname, join, relative, resolve, sep } from "node:path";
16
+ import { PACKAGE_ROOT } from "./sync";
17
+
18
+ // Third-party skills every app gets, downloaded fresh on each `ib sync` and
19
+ // never committed. The files go in .agents/skills/, which Codex, Cursor,
20
+ // Gemini CLI, Copilot and OpenCode read; Claude Code reads only
21
+ // .claude/skills/, so each skill is linked there too (copied where links fail).
22
+
23
+ export const EXTERNAL_SKILLS_LIST = join(PACKAGE_ROOT, "external-skills.txt");
24
+ export const SKILLS_DIR = join(".agents", "skills");
25
+ export const CLAUDE_SKILLS_DIR = join(".claude", "skills");
26
+ // Present in every folder this installer wrote; a folder without it is the app's own.
27
+ export const MARKER = ".toolkit-source";
28
+ const CLAUDE_IGNORE_HEADER = "# Written by ib sync: links to the shared skills in .agents/skills.";
29
+
30
+ export type ExternalSkill = { repo: string; path: string; name?: string };
31
+
32
+ export type InstallReport = {
33
+ installed: string[];
34
+ removed: string[];
35
+ /** Folders kept because the app owns a skill with that name. */
36
+ kept: string[];
37
+ /** Repos or entries that could not be fetched, with the reason. */
38
+ failed: string[];
39
+ };
40
+
41
+ export function parseList(text: string): ExternalSkill[] {
42
+ return text
43
+ .split("\n")
44
+ .map((line) => line.replace(/#.*/, "").trim())
45
+ .filter(Boolean)
46
+ .map((line) => {
47
+ const [repo, path, name] = line.split(/\s+/);
48
+ if (!repo || !path || (path === "." && !name)) {
49
+ throw new Error(
50
+ `external-skills.txt: expected "<owner/repo> <folder> [name]", got "${line}"`,
51
+ );
52
+ }
53
+ return { repo, path, name };
54
+ });
55
+ }
56
+
57
+ function repoUrl(repo: string): string {
58
+ return repo.includes(":") || repo.startsWith("/") ? repo : `https://github.com/${repo}.git`;
59
+ }
60
+
61
+ function git(args: string[]): { ok: boolean; out: string } {
62
+ // An empty askpass answer makes a private or missing repo fail instead of prompting.
63
+ const result = spawnSync("git", ["-c", "core.askPass=true", ...args], { encoding: "utf8" });
64
+ return { ok: result.status === 0, out: `${result.stdout ?? ""}${result.stderr ?? ""}`.trim() };
65
+ }
66
+
67
+ function sparseDir(path: string): string {
68
+ if (path.endsWith("/*")) return path.slice(0, -2);
69
+ if (path.endsWith(".md")) return dirname(path);
70
+ return path;
71
+ }
72
+
73
+ type Source = { name: string; from: string; file: boolean };
74
+
75
+ function sources(checkout: string, entry: ExternalSkill): Source[] {
76
+ const at = join(checkout, entry.path === "." ? "" : entry.path);
77
+ if (entry.path.endsWith("/*")) {
78
+ const dir = join(checkout, sparseDir(entry.path));
79
+ return readdirSync(dir)
80
+ .filter((child) => existsSync(join(dir, child, "SKILL.md")))
81
+ .map((child) => ({ name: child, from: join(dir, child), file: false }));
82
+ }
83
+ if (entry.path.endsWith(".md")) {
84
+ return [{ name: entry.name ?? basename(entry.path, ".md"), from: at, file: true }];
85
+ }
86
+ return [{ name: entry.name ?? basename(entry.path), from: at, file: false }];
87
+ }
88
+
89
+ /** What sits at a skill path: nothing, something this installer wrote, or the app's own. */
90
+ function ownerOf(path: string): "none" | "ours" | "app" {
91
+ try {
92
+ const stat = lstatSync(path);
93
+ return stat.isSymbolicLink() || existsSync(join(path, MARKER)) ? "ours" : "app";
94
+ } catch {
95
+ return "none";
96
+ }
97
+ }
98
+
99
+ function place(skillsDir: string, source: Source, provenance: string): "installed" | "kept" {
100
+ const dest = join(skillsDir, source.name);
101
+ if (ownerOf(dest) === "app") return "kept";
102
+ rmSync(dest, { recursive: true, force: true });
103
+ if (source.file) {
104
+ mkdirSync(dest, { recursive: true });
105
+ cpSync(source.from, join(dest, "SKILL.md"));
106
+ } else {
107
+ cpSync(source.from, dest, {
108
+ recursive: true,
109
+ filter: (path) => !/^\.git(hub)?$/.test(relative(source.from, path).split(sep)[0] ?? ""),
110
+ });
111
+ }
112
+ writeFileSync(join(dest, ".gitignore"), "*\n");
113
+ writeFileSync(join(dest, MARKER), `${provenance}\n`);
114
+ return "installed";
115
+ }
116
+
117
+ /** Points .claude/skills/<name> at .agents/skills/<name>; false when the app owns that name. */
118
+ function linkForClaude(appDir: string, name: string): boolean {
119
+ const target = join(appDir, SKILLS_DIR, name);
120
+ const link = join(appDir, CLAUDE_SKILLS_DIR, name);
121
+ if (ownerOf(link) === "app") return false;
122
+ rmSync(link, { recursive: true, force: true });
123
+ mkdirSync(dirname(link), { recursive: true });
124
+ try {
125
+ // A junction needs no admin rights on Windows and wants an absolute target;
126
+ // elsewhere a relative link keeps working when the app folder moves.
127
+ if (process.platform === "win32") symlinkSync(resolve(target), link, "junction");
128
+ else symlinkSync(relative(dirname(link), target), link);
129
+ } catch {
130
+ cpSync(target, link, { recursive: true });
131
+ }
132
+ return true;
133
+ }
134
+
135
+ /** Keeps the Claude links out of git; leaves a .gitignore the app wrote alone. */
136
+ function ignoreClaudeLinks(appDir: string, names: string[]): void {
137
+ const path = join(appDir, CLAUDE_SKILLS_DIR, ".gitignore");
138
+ if (existsSync(path) && !readFileSync(path, "utf8").startsWith(CLAUDE_IGNORE_HEADER)) return;
139
+ if (names.length === 0) {
140
+ rmSync(path, { force: true });
141
+ return;
142
+ }
143
+ mkdirSync(dirname(path), { recursive: true });
144
+ writeFileSync(path, [CLAUDE_IGNORE_HEADER, ".gitignore", ...[...names].sort()].join("\n") + "\n");
145
+ }
146
+
147
+ export function installExternalSkills(
148
+ appDir: string,
149
+ listPath: string = EXTERNAL_SKILLS_LIST,
150
+ ): InstallReport {
151
+ const report: InstallReport = { installed: [], removed: [], kept: [], failed: [] };
152
+ const skillsDir = join(appDir, SKILLS_DIR);
153
+ const byRepo = new Map<string, ExternalSkill[]>();
154
+ for (const entry of parseList(readFileSync(listPath, "utf8"))) {
155
+ byRepo.set(entry.repo, [...(byRepo.get(entry.repo) ?? []), entry]);
156
+ }
157
+
158
+ for (const [repo, entries] of byRepo) {
159
+ const tmp = mkdtempSync(join(tmpdir(), "ib-skills-"));
160
+ try {
161
+ const checkout = join(tmp, "repo");
162
+ const whole = entries.some((entry) => entry.path === ".");
163
+ const clone = git([
164
+ "clone",
165
+ "--quiet",
166
+ "--depth=1",
167
+ "--filter=blob:none",
168
+ ...(whole ? [] : ["--sparse"]),
169
+ repoUrl(repo),
170
+ checkout,
171
+ ]);
172
+ if (!clone.ok) {
173
+ report.failed.push(`${repo}: ${clone.out.split("\n").pop()}`);
174
+ continue;
175
+ }
176
+ if (!whole) {
177
+ const dirs = [...new Set(entries.map((entry) => sparseDir(entry.path)))];
178
+ const sparse = git(["-C", checkout, "sparse-checkout", "set", ...dirs]);
179
+ if (!sparse.ok) {
180
+ report.failed.push(`${repo}: ${sparse.out.split("\n").pop()}`);
181
+ continue;
182
+ }
183
+ }
184
+ const commit = git(["-C", checkout, "rev-parse", "--short", "HEAD"]).out;
185
+ for (const entry of entries) {
186
+ let found: Source[];
187
+ try {
188
+ found = sources(checkout, entry).filter(
189
+ (source) =>
190
+ existsSync(source.from) && (source.file || existsSync(join(source.from, "SKILL.md"))),
191
+ );
192
+ } catch {
193
+ found = [];
194
+ }
195
+ if (found.length === 0) {
196
+ report.failed.push(`${repo}: no skill at ${entry.path}`);
197
+ continue;
198
+ }
199
+ mkdirSync(skillsDir, { recursive: true });
200
+ for (const source of found) {
201
+ const outcome = place(skillsDir, source, `${repo} ${entry.path} ${commit}`);
202
+ report[outcome].push(source.name);
203
+ }
204
+ }
205
+ } finally {
206
+ rmSync(tmp, { recursive: true, force: true });
207
+ }
208
+ }
209
+
210
+ // Drop skills that left the list, but only after a complete download, so a
211
+ // network failure never deletes anything.
212
+ if (report.failed.length === 0) {
213
+ for (const dir of [SKILLS_DIR, CLAUDE_SKILLS_DIR]) {
214
+ const at = join(appDir, dir);
215
+ if (!existsSync(at)) continue;
216
+ for (const name of readdirSync(at)) {
217
+ if (ownerOf(join(at, name)) !== "ours" || report.installed.includes(name)) continue;
218
+ rmSync(join(at, name), { recursive: true, force: true });
219
+ if (!report.removed.includes(name)) report.removed.push(name);
220
+ }
221
+ }
222
+ }
223
+
224
+ const linked = report.installed.filter((name) => linkForClaude(appDir, name));
225
+ report.kept.push(...report.installed.filter((name) => !linked.includes(name)));
226
+ ignoreClaudeLinks(appDir, linked);
227
+ return report;
228
+ }
229
+
230
+ export function formatReport(report: InstallReport): string[] {
231
+ const lines: string[] = [];
232
+ if (report.installed.length) {
233
+ lines.push(
234
+ `skills (${SKILLS_DIR}, linked in ${CLAUDE_SKILLS_DIR}): ${report.installed.join(", ")}`,
235
+ );
236
+ }
237
+ if (report.removed.length)
238
+ lines.push(`removed skills no longer listed: ${report.removed.join(", ")}`);
239
+ if (report.kept.length) {
240
+ lines.push(`kept your own skills with the same name: ${report.kept.join(", ")}`);
241
+ }
242
+ return lines;
243
+ }
@@ -41,7 +41,7 @@
41
41
  "zod": "^4.3.6"
42
42
  },
43
43
  "devDependencies": {
44
- "@biomejs/biome": "^2.5.15",
44
+ "@biomejs/biome": "2.5.15",
45
45
  "@inbeat/config": "workspace:^",
46
46
  "@inbeat/standards": "workspace:^",
47
47
  "@tailwindcss/postcss": "^4.3.3",