@frcloudsolutions/agent-skills 0.0.0-stage → 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Felipe da Silva Rezende
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,99 @@
1
- # Temporary Holding Version
1
+ # agent-skills
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![validate](https://github.com/rezendesfelipe/agent-skills/actions/workflows/validate.yml/badge.svg)](https://github.com/rezendesfelipe/agent-skills/actions/workflows/validate.yml)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
5
+
6
+ A public collection of [Agent Skills](https://docs.claude.com/en/docs/claude-code/skills) for Claude Code and other agents that read `SKILL.md` files. Every skill here is designed spec-first with [OpenSpec](https://github.com/Fission-AI/OpenSpec).
7
+
8
+ ## Install
9
+
10
+ Works with **Claude Code**, **OpenAI Codex**, **Gemini CLI**, **Cursor** and **GitHub Copilot**. Requires Node.js 20 or later.
11
+
12
+ ### With the CLI (any tool)
13
+
14
+ ```bash
15
+ npx @frcloudsolutions/agent-skills add
16
+ ```
17
+
18
+ In a terminal, `add` shows every skill in this repository in a checkbox list (arrow keys to move, space to select, `a` for all, enter to confirm). It then asks which tools to install into, with the tools found on your machine already selected, and whether to install for your user or only for the current project. It shows a summary to confirm before writing anything.
19
+
20
+ Pass flags to skip the questions, for example in scripts or when another agent runs the command:
21
+
22
+ ```bash
23
+ npx @frcloudsolutions/agent-skills list # every available skill
24
+ npx @frcloudsolutions/agent-skills add <skill> [<skill>...] --tool claude,codex [--scope user|project]
25
+ npx @frcloudsolutions/agent-skills remove <skill> --tool claude # only removes what the CLI installed
26
+ ```
27
+
28
+ Other options: `--force` (replace a skill folder that already exists), `--yes` (skip the confirmation), `--dry-run` (show what would change), `--json` (machine-readable output). Run with `--help` for details.
29
+
30
+ | Tool | `--tool` | User scope (default) | Project scope |
31
+ |-------|-----------|----------------------|---------------|
32
+ | Claude Code | `claude` | `~/.claude/skills/` | `.claude/skills/` |
33
+ | OpenAI Codex | `codex` | `~/.agents/skills/` | `.agents/skills/` |
34
+ | Gemini CLI | `gemini` | `~/.gemini/skills/` | `.gemini/skills/` |
35
+ | Cursor | `cursor` | `~/.cursor/skills/` | `.cursor/skills/` |
36
+ | GitHub Copilot | `copilot` | `~/.copilot/skills/` | `.github/skills/` |
37
+
38
+ Notes:
39
+ - Gemini CLI may need Agent Skills enabled in its settings ([docs](https://geminicli.com/docs/cli/skills/)).
40
+ - Cursor also reads `.claude/skills/`, and Copilot also reads `.claude/skills/` and `.agents/skills/`. If you install the same skill for Claude Code and one of these, that agent may list it twice. Installing for just one of them is enough.
41
+
42
+ ### As a Claude Code plugin marketplace
43
+
44
+ ```text
45
+ /plugin marketplace add rezendesfelipe/agent-skills
46
+ /plugin install <plugin-name>@rezendesfelipe-agent-skills
47
+ ```
48
+
49
+ Run `/plugin` to browse the plugins this marketplace offers.
50
+
51
+ ### Copy a skill by hand
52
+
53
+ ```bash
54
+ git clone https://github.com/rezendesfelipe/agent-skills.git
55
+ skill=agent-skills/plugins/<plugin>/skills/<skill>
56
+
57
+ # For your user (all projects): pick the line for your tool
58
+ cp -r "$skill" ~/.claude/skills/ # Claude Code
59
+ cp -r "$skill" ~/.agents/skills/ # OpenAI Codex
60
+ cp -r "$skill" ~/.gemini/skills/ # Gemini CLI
61
+ cp -r "$skill" ~/.cursor/skills/ # Cursor
62
+ cp -r "$skill" ~/.copilot/skills/ # GitHub Copilot
63
+
64
+ # Or only for one project, from the project folder
65
+ cp -r "$skill" .claude/skills/ # Claude Code
66
+ cp -r "$skill" .agents/skills/ # OpenAI Codex
67
+ cp -r "$skill" .gemini/skills/ # Gemini CLI
68
+ cp -r "$skill" .cursor/skills/ # Cursor
69
+ cp -r "$skill" .github/skills/ # GitHub Copilot
70
+ ```
71
+
72
+ Create the target folder first (`mkdir -p <folder>`) if it does not exist.
73
+
74
+ ## Catalog
75
+
76
+ | Plugin | Skills | Description |
77
+ |--------|--------|-------------|
78
+ | _none yet_ | | The first skills are coming soon. |
79
+
80
+ ## Layout
81
+
82
+ ```text
83
+ .claude-plugin/marketplace.json # marketplace manifest: lists every plugin
84
+ plugins/<plugin>/skills/<skill>/SKILL.md
85
+ templates/skill/SKILL.md # starting point for new skills
86
+ openspec/specs/ # current specs of this repository
87
+ openspec/changes/ # proposed changes being worked on
88
+ scripts/validate-skills.mjs # format and manifest checks (also run in CI)
89
+ bin/, src/ # the agent-skills CLI published to npm
90
+ test/ # CLI tests (npm test)
91
+ ```
92
+
93
+ ## Contributing
94
+
95
+ Every skill starts as an OpenSpec change. See [CONTRIBUTING.md](CONTRIBUTING.md).
96
+
97
+ ## License
98
+
99
+ [MIT](LICENSE)
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env node
2
+ const major = Number(process.versions.node.split(".")[0]);
3
+ if (major < 20) {
4
+ console.error(`agent-skills requires Node.js 20 or later (found ${process.version}).`);
5
+ process.exit(1);
6
+ }
7
+ const { main } = await import("../src/cli/main.mjs");
8
+ process.exitCode = await main(process.argv.slice(2));
package/package.json CHANGED
@@ -1,6 +1,42 @@
1
1
  {
2
2
  "name": "@frcloudsolutions/agent-skills",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Install Agent Skills (SKILL.md) into Claude Code, OpenAI Codex, Gemini CLI, Cursor and GitHub Copilot.",
5
+ "type": "module",
6
+ "bin": {
7
+ "agent-skills": "bin/agent-skills.mjs"
8
+ },
9
+ "files": [
10
+ "bin/",
11
+ "src/",
12
+ "plugins/*/skills/**",
13
+ "README.md",
14
+ "LICENSE"
15
+ ],
16
+ "scripts": {
17
+ "test": "node --test",
18
+ "validate": "node scripts/validate-skills.mjs"
19
+ },
20
+ "engines": {
21
+ "node": ">=20"
22
+ },
23
+ "keywords": [
24
+ "agent-skills",
25
+ "skills",
26
+ "claude-code",
27
+ "codex",
28
+ "gemini-cli",
29
+ "cursor",
30
+ "github-copilot"
31
+ ],
32
+ "repository": {
33
+ "type": "git",
34
+ "url": "git+https://github.com/rezendesfelipe/agent-skills.git"
35
+ },
36
+ "homepage": "https://github.com/rezendesfelipe/agent-skills#readme",
37
+ "bugs": "https://github.com/rezendesfelipe/agent-skills/issues",
38
+ "license": "MIT",
39
+ "publishConfig": {
40
+ "access": "public"
41
+ }
42
+ }
@@ -0,0 +1,222 @@
1
+ // agent-skills command line: list, add and remove skills for supported tools.
2
+ import { readFileSync } from "node:fs";
3
+ import { homedir } from "node:os";
4
+ import { fileURLToPath } from "node:url";
5
+ import { parseArgs } from "node:util";
6
+ import { TOOLS, TOOL_IDS, SCOPES, detectTools, overlaps } from "../lib/tools.mjs";
7
+ import { findSkills } from "../lib/catalog.mjs";
8
+ import { OK_STATUSES, PACKAGE_NAME, install, installedSkills, planTargets, remove } from "../lib/install.mjs";
9
+ import * as prompts from "./prompt.mjs";
10
+
11
+ const PACKAGE_ROOT = fileURLToPath(new URL("../..", import.meta.url));
12
+
13
+ export const EXIT = { OK: 0, FAILED: 1, USAGE: 2 };
14
+
15
+ class UsageError extends Error {}
16
+
17
+ const HELP = `Usage: npx ${PACKAGE_NAME} <command> [options]
18
+
19
+ Commands:
20
+ list Show every skill available in this repository
21
+ add [<skill>...] Install skills into tools' skills folders
22
+ remove [<skill>...] Remove skills that agent-skills installed
23
+
24
+ Options:
25
+ --tool <ids> Comma-separated tools: ${TOOL_IDS.join(", ")}
26
+ --scope <scope> user (default, home folder) or project (current folder)
27
+ --force add: replace a skill folder that already exists
28
+ --yes, -y Skip the confirmation summary
29
+ --dry-run Show what would change, change nothing
30
+ --json Print a JSON result on stdout, messages on stderr
31
+ --help, -h Show this help
32
+ --version, -v Show the version
33
+
34
+ In a terminal, add and remove ask for any skill, tool or scope not given.
35
+
36
+ Tools and folders (user scope | project scope):
37
+ ${TOOL_IDS.map((id) => ` ${id.padEnd(8)} ~/${TOOLS[id].user} | ./${TOOLS[id].project}`).join("\n")}
38
+ `;
39
+
40
+ /**
41
+ * @param {string[]} argv arguments after the program name
42
+ * @param {object} [io] injectable streams and environment (tests)
43
+ * @returns {Promise<number>} exit code
44
+ */
45
+ export async function main(argv, io = {}) {
46
+ const stdout = io.stdout ?? process.stdout;
47
+ const stderr = io.stderr ?? process.stderr;
48
+ const stdin = io.stdin ?? process.stdin;
49
+ const env = { home: io.home ?? homedir(), cwd: io.cwd ?? process.cwd() };
50
+ const root = io.root ?? process.env.AGENT_SKILLS_ROOT ?? PACKAGE_ROOT;
51
+ const interactive = io.interactive ?? Boolean(stdin.isTTY && stderr.isTTY);
52
+ const version = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
53
+
54
+ let args;
55
+ try {
56
+ args = parseArgs({
57
+ args: argv,
58
+ allowPositionals: true,
59
+ options: {
60
+ tool: { type: "string" },
61
+ scope: { type: "string" },
62
+ force: { type: "boolean", default: false },
63
+ yes: { type: "boolean", short: "y", default: false },
64
+ "dry-run": { type: "boolean", default: false },
65
+ json: { type: "boolean", default: false },
66
+ help: { type: "boolean", short: "h", default: false },
67
+ version: { type: "boolean", short: "v", default: false },
68
+ },
69
+ });
70
+ } catch (e) {
71
+ stderr.write(`${e.message}\nRun with --help for usage.\n`);
72
+ return EXIT.USAGE;
73
+ }
74
+ const { values: opts, positionals } = args;
75
+ const [command, ...names] = positionals;
76
+ const json = opts.json;
77
+ const say = (line) => (json ? stderr : stdout).write(line + "\n");
78
+ const ask = { input: stdin, output: stderr };
79
+
80
+ if (opts.version) return stdout.write(version + "\n"), EXIT.OK;
81
+ if (opts.help || !command) {
82
+ (opts.help ? stdout : stderr).write(HELP);
83
+ return opts.help ? EXIT.OK : EXIT.USAGE;
84
+ }
85
+
86
+ const catalog = findSkills(root);
87
+ const byName = new Map(catalog.map((s) => [s.name, s]));
88
+
89
+ try {
90
+ if (command === "list") {
91
+ if (json) stdout.write(JSON.stringify(catalog.map(({ name, plugin, description }) => ({ name, plugin, description }))) + "\n");
92
+ else if (!catalog.length) stdout.write("No skills available yet.\n");
93
+ else {
94
+ const width = Math.max(...catalog.map((s) => s.name.length));
95
+ for (const s of catalog) stdout.write(`${s.name.padEnd(width)} ${s.plugin} ${s.description}\n`);
96
+ }
97
+ return EXIT.OK;
98
+ }
99
+ if (command !== "add" && command !== "remove") throw new UsageError(`Unknown command "${command}". Run with --help for usage.`);
100
+
101
+ const unknown = names.filter((n) => !byName.has(n));
102
+ if (unknown.length)
103
+ throw new UsageError(`Unknown skill: ${unknown.join(", ")}. Run "agent-skills list" to see the available skills.`);
104
+
105
+ // Tools
106
+ let tools = opts.tool ? [...new Set(opts.tool.split(",").map((a) => a.trim()).filter(Boolean))] : null;
107
+ if (tools) {
108
+ const bad = tools.filter((a) => !TOOLS[a]);
109
+ if (bad.length) throw new UsageError(`Unknown tool: ${bad.join(", ")}. Supported tools: ${TOOL_IDS.join(", ")}.`);
110
+ }
111
+ if (opts.scope && !SCOPES.includes(opts.scope))
112
+ throw new UsageError(`Unknown scope "${opts.scope}". Use "user" or "project".`);
113
+
114
+ const detected = detectTools(env.home);
115
+ const askTools = async () => {
116
+ if (tools) return tools;
117
+ if (!interactive)
118
+ throw new UsageError(
119
+ `Missing --tool. Detected tools: ${detected.join(", ") || "none"}. ` +
120
+ `Example: --tool ${detected[0] ?? "claude"}. Supported: ${TOOL_IDS.join(", ")}.`,
121
+ );
122
+ return prompts.checkbox({
123
+ ...ask,
124
+ message: command === "add" ? "Install for which tools?" : "Remove from which tools?",
125
+ choices: TOOL_IDS.map((id) => ({ value: id, label: TOOLS[id].label, hint: id, checked: detected.includes(id) })),
126
+ });
127
+ };
128
+ const askScope = async () => {
129
+ if (opts.scope) return opts.scope;
130
+ if (!interactive) return "user";
131
+ return prompts.select({
132
+ ...ask,
133
+ message: "Scope?",
134
+ initial: "user",
135
+ choices: [
136
+ { value: "user", label: "user", hint: "your home folder, all projects" },
137
+ { value: "project", label: "project", hint: `this folder (${env.cwd})` },
138
+ ],
139
+ });
140
+ };
141
+ const askSkills = async (choices, emptyMessage) => {
142
+ if (names.length) return names;
143
+ if (!interactive)
144
+ throw new UsageError(
145
+ `Missing skill name. Available skills: ${catalog.map((s) => s.name).join(", ") || "none"}.`,
146
+ );
147
+ if (!choices.length) return say(emptyMessage), [];
148
+ return prompts.checkbox({
149
+ ...ask,
150
+ message: command === "add" ? "Which skills do you want to install?" : "Which skills do you want to remove?",
151
+ choices: choices.map((s) => ({ value: s.name, label: s.name, hint: s.description })),
152
+ });
153
+ };
154
+
155
+ let skills, scope;
156
+ if (command === "add") {
157
+ skills = await askSkills(catalog, "No skills available yet.");
158
+ if (skills === null || !skills.length) return cancelled(stderr, skills);
159
+ tools = await askTools();
160
+ if (tools === null || !tools.length) return cancelled(stderr, tools);
161
+ scope = await askScope();
162
+ if (scope === null) return cancelled(stderr, null);
163
+ } else {
164
+ tools = await askTools();
165
+ if (tools === null || !tools.length) return cancelled(stderr, tools);
166
+ scope = await askScope();
167
+ if (scope === null) return cancelled(stderr, null);
168
+ const installed = installedSkills(catalog, tools, scope, env);
169
+ skills = await askSkills(installed, `No skills installed by agent-skills for ${tools.join(", ")} at ${scope} scope.`);
170
+ if (skills === null) return cancelled(stderr, null);
171
+ if (!skills.length) {
172
+ if (installed.length) return cancelled(stderr, []);
173
+ if (json) stdout.write(JSON.stringify({ ok: true, results: [], notes: [] }) + "\n");
174
+ return EXIT.OK;
175
+ }
176
+ }
177
+
178
+ const targets = planTargets(skills.map((n) => byName.get(n)), tools, scope, env);
179
+ const dryRun = opts["dry-run"];
180
+
181
+ if (interactive && !opts.yes && !dryRun) {
182
+ const verb = command === "add" ? "Install" : "Remove";
183
+ stderr.write(`\n${verb} ${skills.length} skill(s) for ${tools.join(", ")} at ${scope} scope:\n`);
184
+ for (const t of targets) stderr.write(` ${t.path}\n`);
185
+ const ok = await prompts.confirm({ ...ask, message: "Continue?" });
186
+ if (!ok) return cancelled(stderr, null);
187
+ }
188
+
189
+ const results = targets.map((t) => {
190
+ const r = command === "add" ? install(t, { force: opts.force, dryRun, version }) : remove(t, { dryRun });
191
+ return { skill: t.skill.name, tools: t.tools, path: t.path, ...r };
192
+ });
193
+ const ok = results.every((r) => OK_STATUSES.has(r.status));
194
+
195
+ const notes = [];
196
+ if (command === "add" && results.some((r) => OK_STATUSES.has(r.status))) {
197
+ for (const o of overlaps(tools, scope))
198
+ notes.push(`${TOOLS[o.reader].label} also reads ${o.path}, so it may list skills installed for ${o.other} twice.`);
199
+ for (const a of tools) if (TOOLS[a].note) notes.push(TOOLS[a].note);
200
+ }
201
+
202
+ if (json) stdout.write(JSON.stringify({ ok, results, notes }) + "\n");
203
+ else {
204
+ for (const r of results) stdout.write(`${r.status.padEnd(13)} ${r.path}${r.message ? ` (${r.message})` : ""}\n`);
205
+ }
206
+ for (const n of notes) say(`note: ${n}`);
207
+ return ok ? EXIT.OK : EXIT.FAILED;
208
+ } catch (e) {
209
+ if (e instanceof UsageError) {
210
+ if (json) stdout.write(JSON.stringify({ ok: false, error: e.message }) + "\n");
211
+ stderr.write(e.message + "\n");
212
+ return EXIT.USAGE;
213
+ }
214
+ throw e;
215
+ }
216
+ }
217
+
218
+ function cancelled(stderr, value) {
219
+ stderr.write(value === null ? "Cancelled.\n" : "Nothing selected. Cancelled.\n");
220
+ return EXIT.FAILED;
221
+ }
222
+
@@ -0,0 +1,142 @@
1
+ // Small terminal prompts with no dependencies: checkbox list, single select, confirm.
2
+ // Keys: up/down (or k/j) move, space toggles, "a" toggles all, enter confirms,
3
+ // Ctrl+C or Esc cancels (resolves to null). Prompts draw on `output` (stderr by default)
4
+ // so stdout stays clean for --json.
5
+ import { emitKeypressEvents } from "node:readline";
6
+
7
+ const CSI = "\x1b[";
8
+
9
+ function run({ input, output, render, onKey }) {
10
+ return new Promise((resolve) => {
11
+ emitKeypressEvents(input);
12
+ const wasRaw = input.isRaw;
13
+ input.setRawMode?.(true);
14
+ input.resume();
15
+ output.write(`${CSI}?25l`);
16
+ let drawn = 0;
17
+
18
+ const draw = (text) => {
19
+ const cols = Math.max(20, (output.columns || 80) - 1);
20
+ const lines = text.split("\n").map((l) => (visibleLength(l) > cols ? truncate(l, cols) : l));
21
+ if (drawn) output.write(`\r${CSI}${drawn}A${CSI}0J`);
22
+ output.write(lines.join("\n") + "\n");
23
+ drawn = lines.length;
24
+ };
25
+
26
+ const finish = (value, summary) => {
27
+ input.off("keypress", handler);
28
+ input.setRawMode?.(wasRaw ?? false);
29
+ input.pause();
30
+ draw(summary);
31
+ output.write(`${CSI}?25h`);
32
+ resolve(value);
33
+ };
34
+
35
+ const handler = (str, key = {}) => {
36
+ if ((key.ctrl && key.name === "c") || key.name === "escape") return finish(null, render({ cancelled: true }));
37
+ const result = onKey(str, key);
38
+ if (result && "done" in result) return finish(result.value, render({ done: true }));
39
+ draw(render({}));
40
+ };
41
+
42
+ input.on("keypress", handler);
43
+ draw(render({}));
44
+ });
45
+ }
46
+
47
+ const visibleLength = (s) => s.replace(/\x1b\[[0-9;]*m/g, "").length;
48
+ const truncate = (s, n) => s.replace(/\x1b\[[0-9;]*m/g, "").slice(0, n - 1) + "…";
49
+ const dim = (s) => `${CSI}2m${s}${CSI}22m`;
50
+ const bold = (s) => `${CSI}1m${s}${CSI}22m`;
51
+
52
+ function windowed(choices, cursor, rows) {
53
+ const size = Math.min(choices.length, Math.max(3, (rows || 24) - 4));
54
+ const start = Math.min(Math.max(0, cursor - Math.floor(size / 2)), Math.max(0, choices.length - size));
55
+ return { start, end: start + size };
56
+ }
57
+
58
+ function move(cursor, key, length) {
59
+ if (key.name === "up" || key.name === "k") return (cursor - 1 + length) % length;
60
+ if (key.name === "down" || key.name === "j") return (cursor + 1) % length;
61
+ return cursor;
62
+ }
63
+
64
+ /**
65
+ * @param {{message: string, choices: {value: string, label: string, hint?: string, checked?: boolean}[], input, output}} o
66
+ * @returns {Promise<string[]|null>} selected values, [] when confirmed empty, null when cancelled
67
+ */
68
+ export function checkbox({ message, choices, input = process.stdin, output = process.stderr }) {
69
+ let cursor = 0;
70
+ const checked = new Set(choices.filter((c) => c.checked).map((c) => c.value));
71
+ const selected = () => choices.filter((c) => checked.has(c.value)).map((c) => c.value);
72
+ return run({
73
+ input,
74
+ output,
75
+ render: ({ done, cancelled }) => {
76
+ if (cancelled) return `${bold("?")} ${message} ${dim("cancelled")}`;
77
+ if (done) return `${bold("✔")} ${message} ${selected().join(", ") || dim("none")}`;
78
+ const { start, end } = windowed(choices, cursor, output.rows);
79
+ const lines = [`${bold("?")} ${message} ${dim("(↑/↓ move, space select, a all, enter confirm)")}`];
80
+ if (start > 0) lines.push(dim(" ↑ more"));
81
+ for (let i = start; i < end; i++) {
82
+ const c = choices[i];
83
+ const pointer = i === cursor ? "❯" : " ";
84
+ const box = checked.has(c.value) ? "◉" : "◯";
85
+ lines.push(`${pointer} ${box} ${c.label}${c.hint ? dim(` — ${c.hint}`) : ""}`);
86
+ }
87
+ if (end < choices.length) lines.push(dim(" ↓ more"));
88
+ return lines.join("\n");
89
+ },
90
+ onKey: (str, key) => {
91
+ if (key.name === "return" || key.name === "enter") return { done: true, value: selected() };
92
+ if (key.name === "space") {
93
+ const v = choices[cursor].value;
94
+ checked.has(v) ? checked.delete(v) : checked.add(v);
95
+ } else if (str === "a") {
96
+ if (checked.size === choices.length) checked.clear();
97
+ else choices.forEach((c) => checked.add(c.value));
98
+ } else cursor = move(cursor, key, choices.length);
99
+ },
100
+ });
101
+ }
102
+
103
+ /** @returns {Promise<string|null>} */
104
+ export function select({ message, choices, initial, input = process.stdin, output = process.stderr }) {
105
+ let cursor = Math.max(0, choices.findIndex((c) => c.value === initial));
106
+ return run({
107
+ input,
108
+ output,
109
+ render: ({ done, cancelled }) => {
110
+ if (cancelled) return `${bold("?")} ${message} ${dim("cancelled")}`;
111
+ if (done) return `${bold("✔")} ${message} ${choices[cursor].value}`;
112
+ const lines = [`${bold("?")} ${message} ${dim("(↑/↓ move, enter confirm)")}`];
113
+ choices.forEach((c, i) => {
114
+ lines.push(`${i === cursor ? "❯" : " "} ${c.label}${c.hint ? dim(` — ${c.hint}`) : ""}`);
115
+ });
116
+ return lines.join("\n");
117
+ },
118
+ onKey: (_str, key) => {
119
+ if (key.name === "return" || key.name === "enter") return { done: true, value: choices[cursor].value };
120
+ cursor = move(cursor, key, choices.length);
121
+ },
122
+ });
123
+ }
124
+
125
+ /** @returns {Promise<boolean|null>} */
126
+ export function confirm({ message, initial = true, input = process.stdin, output = process.stderr }) {
127
+ let answer = initial;
128
+ return run({
129
+ input,
130
+ output,
131
+ render: ({ done, cancelled }) => {
132
+ if (cancelled) return `${bold("?")} ${message} ${dim("cancelled")}`;
133
+ if (done) return `${bold("✔")} ${message} ${answer ? "yes" : "no"}`;
134
+ return `${bold("?")} ${message} ${dim(initial ? "(Y/n)" : "(y/N)")}`;
135
+ },
136
+ onKey: (str, key) => {
137
+ if (key.name === "return" || key.name === "enter") return { done: true, value: answer };
138
+ if (str === "y" || str === "Y") return { done: true, value: (answer = true) };
139
+ if (str === "n" || str === "N") return { done: true, value: (answer = false) };
140
+ },
141
+ });
142
+ }
@@ -0,0 +1,28 @@
1
+ // Finds the skills bundled under <root>/plugins/<plugin>/skills/<skill>/SKILL.md.
2
+ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { parseFrontmatter } from "./frontmatter.mjs";
5
+
6
+ export function subdirs(path) {
7
+ if (!existsSync(path)) return [];
8
+ return readdirSync(path)
9
+ .filter((d) => !d.startsWith(".") && statSync(join(path, d)).isDirectory())
10
+ .sort();
11
+ }
12
+
13
+ /** @returns {{name: string, plugin: string, description: string, dir: string}[]} sorted by name */
14
+ export function findSkills(root) {
15
+ const skills = [];
16
+ const pluginsDir = join(root, "plugins");
17
+ for (const plugin of subdirs(pluginsDir)) {
18
+ const skillsDir = join(pluginsDir, plugin, "skills");
19
+ for (const folder of subdirs(skillsDir)) {
20
+ const dir = join(skillsDir, folder);
21
+ const file = join(dir, "SKILL.md");
22
+ if (!existsSync(file)) continue;
23
+ const fm = parseFrontmatter(readFileSync(file, "utf8")) ?? {};
24
+ skills.push({ name: fm.name || folder, plugin, description: fm.description || "", dir });
25
+ }
26
+ }
27
+ return skills.sort((a, b) => a.name.localeCompare(b.name));
28
+ }
@@ -0,0 +1,23 @@
1
+ // Minimal YAML frontmatter reader for SKILL.md files: top-level `key: value`
2
+ // pairs, quoted values and `>` / `|` block scalars. No dependencies.
3
+
4
+ export function parseFrontmatter(text) {
5
+ const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
6
+ if (!m) return null;
7
+ const data = {};
8
+ const lines = m[1].split(/\r?\n/);
9
+ for (let i = 0; i < lines.length; i++) {
10
+ const kv = lines[i].match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
11
+ if (!kv) continue;
12
+ let [, key, value] = kv;
13
+ if (/^[>|][+-]?$/.test(value)) {
14
+ const block = [];
15
+ while (i + 1 < lines.length && (/^\s+/.test(lines[i + 1]) || lines[i + 1] === "")) block.push(lines[++i].trim());
16
+ value = block.join(value.startsWith(">") ? " " : "\n").trim();
17
+ } else if (/^(['"]).*\1$/.test(value)) {
18
+ value = value.slice(1, -1);
19
+ }
20
+ data[key] = value.trim();
21
+ }
22
+ return data;
23
+ }
@@ -0,0 +1,67 @@
1
+ // Plans and performs skill installs and removals in tools' skills folders.
2
+ import { cpSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
3
+ import { basename, join } from "node:path";
4
+ import { skillsDir } from "./tools.mjs";
5
+
6
+ export const PACKAGE_NAME = "@frcloudsolutions/agent-skills";
7
+ export const MARKER = ".agent-skills.json";
8
+ const SKIP = new Set(["node_modules", MARKER]);
9
+
10
+ /**
11
+ * One target per (skill, folder). Tools that resolve to the same folder share a target.
12
+ * @returns {{skill: object, tools: string[], path: string}[]}
13
+ */
14
+ export function planTargets(skills, tools, scope, env) {
15
+ const targets = new Map();
16
+ for (const skill of skills) {
17
+ for (const tool of tools) {
18
+ const path = join(skillsDir(tool, scope, env), skill.name);
19
+ if (!targets.has(path)) targets.set(path, { skill, tools: [], path });
20
+ targets.get(path).tools.push(tool);
21
+ }
22
+ }
23
+ return [...targets.values()];
24
+ }
25
+
26
+ export function readMarker(path) {
27
+ try {
28
+ const data = JSON.parse(readFileSync(join(path, MARKER), "utf8"));
29
+ return data?.package === PACKAGE_NAME ? data : null;
30
+ } catch {
31
+ return null;
32
+ }
33
+ }
34
+
35
+ /** @returns {"installed"|"replaced"|"skipped"|"would-install"|"would-replace"} */
36
+ export function install(target, { force = false, dryRun = false, version, now = new Date() }) {
37
+ const exists = existsSync(target.path);
38
+ if (exists && !force) return { status: "skipped", message: "already exists (use --force to replace it)" };
39
+ if (dryRun) return { status: exists ? "would-replace" : "would-install" };
40
+ if (exists) rmSync(target.path, { recursive: true, force: true });
41
+ cpSync(target.skill.dir, target.path, {
42
+ recursive: true,
43
+ filter: (src) => !SKIP.has(basename(src)),
44
+ });
45
+ const marker = { package: PACKAGE_NAME, version, skill: target.skill.name, installedAt: now.toISOString() };
46
+ writeFileSync(join(target.path, MARKER), JSON.stringify(marker, null, 2) + "\n");
47
+ return { status: exists ? "replaced" : "installed" };
48
+ }
49
+
50
+ /** @returns {"removed"|"would-remove"|"not-found"|"not-managed"} */
51
+ export function remove(target, { dryRun = false }) {
52
+ if (!existsSync(target.path)) return { status: "not-found", message: "not installed here" };
53
+ if (!readMarker(target.path)) return { status: "not-managed", message: "not installed by agent-skills; left in place" };
54
+ if (dryRun) return { status: "would-remove" };
55
+ rmSync(target.path, { recursive: true, force: true });
56
+ return { status: "removed" };
57
+ }
58
+
59
+ // "not-found" counts as success: removal is idempotent, the requested end state already holds.
60
+ export const OK_STATUSES = new Set(["installed", "replaced", "would-install", "would-replace", "removed", "would-remove", "not-found"]);
61
+
62
+ /** Skills from the catalog that this CLI installed for at least one of the tools. */
63
+ export function installedSkills(catalog, tools, scope, env) {
64
+ return catalog.filter((skill) =>
65
+ tools.some((tool) => readMarker(join(skillsDir(tool, scope, env), skill.name))),
66
+ );
67
+ }
@@ -0,0 +1,77 @@
1
+ // Where each supported tool reads Agent Skills from.
2
+ // User-scope paths are relative to the home directory, project-scope paths to the
3
+ // current working directory. Checked against each vendor's docs on 2026-11-19.
4
+ import { existsSync } from "node:fs";
5
+ import { join } from "node:path";
6
+
7
+ export const TOOLS = {
8
+ claude: {
9
+ label: "Claude Code",
10
+ user: ".claude/skills",
11
+ project: ".claude/skills",
12
+ detect: [".claude"],
13
+ source: "https://docs.claude.com/en/docs/claude-code/skills",
14
+ },
15
+ codex: {
16
+ label: "OpenAI Codex",
17
+ user: ".agents/skills",
18
+ project: ".agents/skills",
19
+ detect: [".codex", ".agents"],
20
+ source: "https://developers.openai.com/codex/skills",
21
+ },
22
+ gemini: {
23
+ label: "Gemini CLI",
24
+ user: ".gemini/skills",
25
+ project: ".gemini/skills",
26
+ detect: [".gemini"],
27
+ alsoReads: [".agents/skills"],
28
+ note: "Gemini CLI may need Agent Skills enabled in its settings: https://geminicli.com/docs/cli/skills/",
29
+ source: "https://geminicli.com/docs/cli/skills/",
30
+ },
31
+ cursor: {
32
+ label: "Cursor",
33
+ user: ".cursor/skills",
34
+ project: ".cursor/skills",
35
+ detect: [".cursor"],
36
+ alsoReads: [".claude/skills", ".codex/skills"],
37
+ source: "https://cursor.com/docs/skills",
38
+ },
39
+ copilot: {
40
+ label: "GitHub Copilot",
41
+ user: ".copilot/skills",
42
+ project: ".github/skills",
43
+ detect: [".copilot"],
44
+ alsoReads: [".claude/skills", ".agents/skills"],
45
+ source: "https://docs.github.com/en/copilot/concepts/agents/about-agent-skills",
46
+ },
47
+ };
48
+
49
+ export const TOOL_IDS = Object.keys(TOOLS);
50
+ export const SCOPES = ["user", "project"];
51
+
52
+ /** Absolute skills folder for an tool and scope. */
53
+ export function skillsDir(tool, scope, { home, cwd }) {
54
+ const a = TOOLS[tool];
55
+ return scope === "project" ? join(cwd, a.project) : join(home, a.user);
56
+ }
57
+
58
+ /** Tools whose user configuration folder exists in `home`. */
59
+ export function detectTools(home) {
60
+ return TOOL_IDS.filter((id) => TOOLS[id].detect.some((d) => existsSync(join(home, d))));
61
+ }
62
+
63
+ /**
64
+ * Pairs of selected tools where one also reads the other's folder, so a skill
65
+ * installed for both may be listed twice by the first.
66
+ */
67
+ export function overlaps(tools, scope) {
68
+ const out = [];
69
+ for (const reader of tools) {
70
+ for (const other of tools) {
71
+ if (reader === other) continue;
72
+ const otherPath = TOOLS[other][scope];
73
+ if ((TOOLS[reader].alsoReads ?? []).includes(otherPath)) out.push({ reader, other, path: otherPath });
74
+ }
75
+ }
76
+ return out;
77
+ }
@@ -0,0 +1,83 @@
1
+ // Repository checks for skills and the plugin marketplace manifest.
2
+ import { existsSync, readFileSync } from "node:fs";
3
+ import { join, relative, resolve } from "node:path";
4
+ import { parseFrontmatter } from "./frontmatter.mjs";
5
+ import { subdirs } from "./catalog.mjs";
6
+
7
+ const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
8
+
9
+ export function validateSkill(skillDir, { root, expectedName = skillDir.split(/[\\/]/).pop() }) {
10
+ const rel = (p) => relative(root, p);
11
+ const file = join(skillDir, "SKILL.md");
12
+ const out = [];
13
+ if (!existsSync(file)) return [`${rel(skillDir)}: missing SKILL.md`];
14
+ const fm = parseFrontmatter(readFileSync(file, "utf8"));
15
+ if (!fm) return [`${rel(file)}: missing YAML frontmatter`];
16
+ if (!fm.name) out.push(`${rel(file)}: frontmatter is missing "name"`);
17
+ else {
18
+ if (!NAME_RE.test(fm.name)) out.push(`${rel(file)}: name "${fm.name}" must be kebab-case`);
19
+ if (fm.name.length > 64) out.push(`${rel(file)}: name is longer than 64 characters`);
20
+ if (expectedName && fm.name !== expectedName)
21
+ out.push(`${rel(file)}: name "${fm.name}" does not match folder "${expectedName}"`);
22
+ }
23
+ if (!fm.description) out.push(`${rel(file)}: frontmatter is missing "description"`);
24
+ else if (fm.description.length > 1024) out.push(`${rel(file)}: description is longer than 1024 characters`);
25
+ return out;
26
+ }
27
+
28
+ /** @returns {{errors: string[], skillCount: number}} */
29
+ export function validateRepo(root, { template = "skill-name" } = {}) {
30
+ const rel = (p) => relative(root, p);
31
+ const errors = [];
32
+ const pluginsDir = join(root, "plugins");
33
+
34
+ // Skills, and unique names across plugins
35
+ let skillCount = 0;
36
+ const byName = new Map();
37
+ for (const plugin of subdirs(pluginsDir)) {
38
+ for (const skill of subdirs(join(pluginsDir, plugin, "skills"))) {
39
+ skillCount++;
40
+ const dir = join(pluginsDir, plugin, "skills", skill);
41
+ errors.push(...validateSkill(dir, { root }));
42
+ if (!byName.has(skill)) byName.set(skill, []);
43
+ byName.get(skill).push(rel(dir));
44
+ }
45
+ }
46
+ for (const [name, dirs] of byName) {
47
+ if (dirs.length > 1) errors.push(`skill name "${name}" is used more than once: ${dirs.join(", ")}`);
48
+ }
49
+
50
+ // Template (validated against its placeholder name)
51
+ const templateDir = join(root, "templates", "skill");
52
+ if (existsSync(templateDir)) errors.push(...validateSkill(templateDir, { root, expectedName: template }));
53
+
54
+ // Manifest
55
+ const manifestPath = join(root, ".claude-plugin", "marketplace.json");
56
+ let manifest;
57
+ try {
58
+ manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
59
+ } catch (e) {
60
+ errors.push(`${rel(manifestPath)}: ${e.message}`);
61
+ }
62
+ if (manifest) {
63
+ if (!manifest.name) errors.push(`${rel(manifestPath)}: missing "name"`);
64
+ if (!manifest.owner?.name) errors.push(`${rel(manifestPath)}: missing "owner.name"`);
65
+ if (!Array.isArray(manifest.plugins)) errors.push(`${rel(manifestPath)}: "plugins" must be an array`);
66
+ else {
67
+ const listed = new Set();
68
+ for (const p of manifest.plugins) {
69
+ if (!p.name || !p.source) {
70
+ errors.push(`${rel(manifestPath)}: plugin entry needs "name" and "source": ${JSON.stringify(p)}`);
71
+ continue;
72
+ }
73
+ listed.add(resolve(root, p.source));
74
+ if (!existsSync(resolve(root, p.source)))
75
+ errors.push(`${rel(manifestPath)}: plugin "${p.name}" source "${p.source}" does not exist`);
76
+ }
77
+ for (const plugin of subdirs(pluginsDir)) {
78
+ if (!listed.has(join(pluginsDir, plugin))) errors.push(`plugins/${plugin}: not listed in ${rel(manifestPath)}`);
79
+ }
80
+ }
81
+ }
82
+ return { errors, skillCount };
83
+ }