@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 +21 -0
- package/README.md +98 -2
- package/bin/agent-skills.mjs +8 -0
- package/package.json +40 -4
- package/src/cli/main.mjs +222 -0
- package/src/cli/prompt.mjs +142 -0
- package/src/lib/catalog.mjs +28 -0
- package/src/lib/frontmatter.mjs +23 -0
- package/src/lib/install.mjs +67 -0
- package/src/lib/tools.mjs +77 -0
- package/src/lib/validate.mjs +83 -0
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
|
-
#
|
|
1
|
+
# agent-skills
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/rezendesfelipe/agent-skills/actions/workflows/validate.yml)
|
|
4
|
+
[](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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|
package/src/cli/main.mjs
ADDED
|
@@ -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
|
+
}
|