iskills 0.2.59 → 0.2.61

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.
Files changed (134) hide show
  1. package/AGENT-CLI.md +61 -0
  2. package/README.md +20 -17
  3. package/README.zh-CN.md +20 -17
  4. package/bin/command-route.mjs +15 -0
  5. package/bin/iskills.js +14 -7
  6. package/dist/src/cli.js +4 -12
  7. package/dist/src/cli.js.map +1 -1
  8. package/dist/src/commands/agent/arguments.d.ts +10 -0
  9. package/dist/src/commands/agent/arguments.js +60 -0
  10. package/dist/src/commands/agent/arguments.js.map +1 -0
  11. package/dist/src/commands/agent/index.d.ts +1 -0
  12. package/dist/src/commands/agent/index.js +773 -0
  13. package/dist/src/commands/agent/index.js.map +1 -0
  14. package/dist/src/commands/browser-actions.js +36 -7
  15. package/dist/src/commands/browser-actions.js.map +1 -1
  16. package/dist/src/commands/index.d.ts +0 -3
  17. package/dist/src/commands/index.js +0 -33
  18. package/dist/src/commands/index.js.map +1 -1
  19. package/dist/src/commands/library.js +79 -146
  20. package/dist/src/commands/library.js.map +1 -1
  21. package/dist/src/commands/mcp.d.ts +1 -3
  22. package/dist/src/commands/mcp.js +7 -240
  23. package/dist/src/commands/mcp.js.map +1 -1
  24. package/dist/src/domain/agent-collection-write.d.ts +2 -0
  25. package/dist/src/domain/agent-collection-write.js +230 -0
  26. package/dist/src/domain/agent-collection-write.js.map +1 -0
  27. package/dist/src/domain/agent-mcp-write.d.ts +23 -0
  28. package/dist/src/domain/agent-mcp-write.js +927 -0
  29. package/dist/src/domain/agent-mcp-write.js.map +1 -0
  30. package/dist/src/domain/agent-read.d.ts +38 -0
  31. package/dist/src/domain/agent-read.js +524 -0
  32. package/dist/src/domain/agent-read.js.map +1 -0
  33. package/dist/src/domain/agent-skill-write.d.ts +34 -0
  34. package/dist/src/domain/agent-skill-write.js +859 -0
  35. package/dist/src/domain/agent-skill-write.js.map +1 -0
  36. package/dist/src/domain/agent-write.d.ts +9 -0
  37. package/dist/src/domain/agent-write.js +127 -0
  38. package/dist/src/domain/agent-write.js.map +1 -0
  39. package/dist/src/domain/collection-write.d.ts +3 -1
  40. package/dist/src/domain/collection-write.js +109 -33
  41. package/dist/src/domain/collection-write.js.map +1 -1
  42. package/dist/src/domain/core.d.ts +11 -0
  43. package/dist/src/domain/core.js +39 -1
  44. package/dist/src/domain/core.js.map +1 -1
  45. package/dist/src/domain/cross-agent-install.js +3 -5
  46. package/dist/src/domain/cross-agent-install.js.map +1 -1
  47. package/dist/src/domain/errors.d.ts +2 -1
  48. package/dist/src/domain/errors.js +5 -2
  49. package/dist/src/domain/errors.js.map +1 -1
  50. package/dist/src/domain/git.d.ts +19 -1
  51. package/dist/src/domain/git.js +112 -72
  52. package/dist/src/domain/git.js.map +1 -1
  53. package/dist/src/domain/install-target.d.ts +2 -0
  54. package/dist/src/domain/install-target.js +68 -0
  55. package/dist/src/domain/install-target.js.map +1 -0
  56. package/dist/src/domain/mcp/collection.d.ts +3 -0
  57. package/dist/src/domain/mcp/collection.js +26 -4
  58. package/dist/src/domain/mcp/collection.js.map +1 -1
  59. package/dist/src/domain/mcp/dialects/borrow.js +1 -5
  60. package/dist/src/domain/mcp/dialects/borrow.js.map +1 -1
  61. package/dist/src/domain/mcp/index.d.ts +1 -1
  62. package/dist/src/domain/mcp/index.js +1 -1
  63. package/dist/src/domain/mcp/index.js.map +1 -1
  64. package/dist/src/domain/mcp/io.js +1 -1
  65. package/dist/src/domain/mcp/io.js.map +1 -1
  66. package/dist/src/domain/mcp/location-write.d.ts +3 -0
  67. package/dist/src/domain/mcp/location-write.js +39 -0
  68. package/dist/src/domain/mcp/location-write.js.map +1 -0
  69. package/dist/src/domain/mcp/probe.d.ts +2 -0
  70. package/dist/src/domain/mcp/probe.js +2 -1
  71. package/dist/src/domain/mcp/probe.js.map +1 -1
  72. package/dist/src/domain/mcp/recipe.d.ts +1 -1
  73. package/dist/src/domain/mcp/recipe.js +6 -5
  74. package/dist/src/domain/mcp/recipe.js.map +1 -1
  75. package/dist/src/domain/mcp/secrets.js +12 -11
  76. package/dist/src/domain/mcp/secrets.js.map +1 -1
  77. package/dist/src/domain/mcp/types.d.ts +2 -0
  78. package/dist/src/domain/mcp/write.js +49 -35
  79. package/dist/src/domain/mcp/write.js.map +1 -1
  80. package/dist/src/domain/operation.d.ts +30 -0
  81. package/dist/src/domain/operation.js +107 -0
  82. package/dist/src/domain/operation.js.map +1 -0
  83. package/dist/src/domain/process.d.ts +3 -0
  84. package/dist/src/domain/process.js +81 -0
  85. package/dist/src/domain/process.js.map +1 -0
  86. package/dist/src/domain/tags.d.ts +11 -0
  87. package/dist/src/domain/tags.js +42 -0
  88. package/dist/src/domain/tags.js.map +1 -0
  89. package/dist/src/domain/user-config.js +9 -1
  90. package/dist/src/domain/user-config.js.map +1 -1
  91. package/dist/src/i18n/en.js +52 -28
  92. package/dist/src/i18n/en.js.map +1 -1
  93. package/dist/src/i18n/index.js +2 -0
  94. package/dist/src/i18n/index.js.map +1 -1
  95. package/dist/src/i18n/zh.d.ts +53 -29
  96. package/dist/src/i18n/zh.js +53 -29
  97. package/dist/src/i18n/zh.js.map +1 -1
  98. package/dist/src/ui/browser/browse-capabilities.js +7 -1
  99. package/dist/src/ui/browser/browse-capabilities.js.map +1 -1
  100. package/dist/src/ui/browser/browse-session.d.ts +2 -0
  101. package/dist/src/ui/browser/browse-session.js +4 -0
  102. package/dist/src/ui/browser/browse-session.js.map +1 -1
  103. package/dist/src/ui/browser/browser.js +18 -1
  104. package/dist/src/ui/browser/browser.js.map +1 -1
  105. package/dist/src/ui/browser/index.js +3 -1
  106. package/dist/src/ui/browser/index.js.map +1 -1
  107. package/dist/src/ui/browser/types.d.ts +5 -0
  108. package/dist/src/ui/components/mouse/provider.d.ts +4 -0
  109. package/dist/src/ui/components/mouse/provider.js +22 -6
  110. package/dist/src/ui/components/mouse/provider.js.map +1 -1
  111. package/dist/src/ui/footer/resolve-footer.js +3 -0
  112. package/dist/src/ui/footer/resolve-footer.js.map +1 -1
  113. package/dist/src/ui/footer/types.d.ts +1 -0
  114. package/dist/src/ui/mcp/browse-capabilities.d.ts +1 -0
  115. package/dist/src/ui/mcp/browse-capabilities.js +1 -0
  116. package/dist/src/ui/mcp/browse-capabilities.js.map +1 -1
  117. package/dist/src/ui/mcp/browser.d.ts +2 -1
  118. package/dist/src/ui/mcp/browser.js +33 -5
  119. package/dist/src/ui/mcp/browser.js.map +1 -1
  120. package/dist/src/ui/mcp/index.js +29 -2
  121. package/dist/src/ui/mcp/index.js.map +1 -1
  122. package/dist/src/ui/overlay/bridge.d.ts +2 -0
  123. package/dist/src/ui/overlay/bridge.js +6 -2
  124. package/dist/src/ui/overlay/bridge.js.map +1 -1
  125. package/dist/src/ui/prompts/index.d.ts +1 -1
  126. package/dist/src/ui/prompts/index.js +1 -1
  127. package/dist/src/ui/prompts/index.js.map +1 -1
  128. package/dist/src/ui/prompts/present.d.ts +4 -0
  129. package/dist/src/ui/prompts/present.js +9 -0
  130. package/dist/src/ui/prompts/present.js.map +1 -1
  131. package/dist/src/ui/shell/lifecycle.js +2 -0
  132. package/dist/src/ui/shell/lifecycle.js.map +1 -1
  133. package/dist/src/ui/shell/run.js +1 -1
  134. package/package.json +3 -2
@@ -0,0 +1,773 @@
1
+ import { stat, readFile, mkdir, writeFile } from 'node:fs/promises';
2
+ import { resolve, join } from 'node:path';
3
+ import { collectionPaths, readState } from '../../domain/core.js';
4
+ import { readUserConfig } from '../../domain/user-config.js';
5
+ import { OperationFailure, operationError, redactOutput, } from '../../domain/operation.js';
6
+ import { readSkills, readMcps, readResult, readAgents, readStatus, readSkillLocations, readMcpLocations, publicLocation, publicMcp, secretStatus, readDiscovery, readSearch, optionalGit, } from '../../domain/agent-read.js';
7
+ import { parseArguments, requirePositionals, stringOption, listOption, } from './arguments.js';
8
+ import { executeSkillWrite } from '../../domain/agent-skill-write.js';
9
+ import { executeMcpWrite } from '../../domain/agent-mcp-write.js';
10
+ import { executeCollectionWrite } from '../../domain/agent-collection-write.js';
11
+ import { probeCollectedHttp } from '../../domain/mcp/write.js';
12
+ import { withProcessSignal } from '../../domain/process.js';
13
+ const READ_OPTIONS = {
14
+ agents: {},
15
+ status: {},
16
+ 'skill.list': { query: 'string', tag: 'multiple' },
17
+ 'skill.show': { body: 'boolean' },
18
+ 'skill.locations': { agent: 'multiple', scope: 'string', root: 'string' },
19
+ 'skill.discover': { git: 'string', local: 'string' },
20
+ 'skill.search': { limit: 'string' },
21
+ 'mcp.list': { query: 'string', tag: 'multiple' },
22
+ 'mcp.show': {},
23
+ 'mcp.locations': { agent: 'multiple', scope: 'string' },
24
+ 'mcp.secret.status': {},
25
+ 'collection.remote.get': {},
26
+ 'config.get': {},
27
+ };
28
+ const META_OPTIONS = {
29
+ tags: 'string',
30
+ 'add-tag': 'multiple',
31
+ 'remove-tag': 'multiple',
32
+ note: 'string',
33
+ };
34
+ const WRITE_OPTIONS = {
35
+ 'skill.create': {},
36
+ 'skill.adopt': { all: 'boolean' },
37
+ 'skill.import': {
38
+ git: 'string',
39
+ local: 'string',
40
+ path: 'multiple',
41
+ all: 'boolean',
42
+ 'expect-commit': 'string',
43
+ replace: 'boolean',
44
+ tag: 'multiple',
45
+ },
46
+ 'skill.install': {
47
+ 'from-location': 'multiple',
48
+ agent: 'multiple',
49
+ scope: 'string',
50
+ to: 'string',
51
+ copy: 'boolean',
52
+ replace: 'boolean',
53
+ },
54
+ 'skill.remove': { yes: 'boolean' },
55
+ 'skill.uninstall': { yes: 'boolean' },
56
+ 'skill.materialize': {},
57
+ 'skill.update': { all: 'boolean', 'allow-delete': 'boolean', yes: 'boolean' },
58
+ 'skill.edit': META_OPTIONS,
59
+ 'skill.tag.rename': {},
60
+ 'skill.source.bind': { git: 'string', path: 'string', replace: 'boolean' },
61
+ 'skill.source.unbind': { yes: 'boolean' },
62
+ 'mcp.create': { input: 'string' },
63
+ 'mcp.import': {
64
+ input: 'string',
65
+ location: 'multiple',
66
+ name: 'string',
67
+ replace: 'boolean',
68
+ },
69
+ 'mcp.add': { agent: 'multiple', scope: 'string', replace: 'boolean' },
70
+ 'mcp.update': { location: 'multiple', replace: 'boolean' },
71
+ 'mcp.enable': {},
72
+ 'mcp.disable': {},
73
+ 'mcp.uninstall': { yes: 'boolean' },
74
+ 'mcp.remove': { yes: 'boolean' },
75
+ 'mcp.rename': {},
76
+ 'mcp.edit': {
77
+ ...META_OPTIONS,
78
+ 'recipe-input': 'string',
79
+ description: 'string',
80
+ },
81
+ 'mcp.tag.rename': {},
82
+ 'mcp.secret.set': {
83
+ env: 'string',
84
+ header: 'string',
85
+ url: 'boolean',
86
+ 'value-stdin': 'boolean',
87
+ 'value-file': 'string',
88
+ },
89
+ 'mcp.secret.unset': {
90
+ env: 'string',
91
+ header: 'string',
92
+ url: 'boolean',
93
+ yes: 'boolean',
94
+ },
95
+ 'collection.init': { remote: 'string', replace: 'boolean' },
96
+ 'collection.sync': {},
97
+ 'collection.remote.set': { replace: 'boolean' },
98
+ 'collection.remote.clear': { yes: 'boolean' },
99
+ 'config.set': {},
100
+ };
101
+ const COMMAND_OPTIONS = {
102
+ ...READ_OPTIONS,
103
+ ...Object.fromEntries(Object.entries(WRITE_OPTIONS).map(([command, options]) => [
104
+ command,
105
+ { ...options, 'dry-run': 'boolean' },
106
+ ])),
107
+ 'mcp.probe': {},
108
+ };
109
+ function commandPath(argv) {
110
+ const depth = ['skill', 'mcp', 'collection', 'config'].includes(argv[0] ?? '')
111
+ ? ['tag', 'source', 'secret', 'remote'].includes(argv[1] ?? '')
112
+ ? 3
113
+ : 2
114
+ : 1;
115
+ return { command: argv.slice(0, depth).join('.'), rest: argv.slice(depth) };
116
+ }
117
+ function scopes(args) {
118
+ const scope = stringOption(args, 'scope');
119
+ if (scope && !['project', 'global'].includes(scope))
120
+ throw new OperationFailure('usage.invalidArguments', 'Invalid scope.', {
121
+ scope,
122
+ });
123
+ return scope ? [scope] : ['project', 'global'];
124
+ }
125
+ function filterItems(items, args) {
126
+ const query = stringOption(args, 'query')?.toLowerCase();
127
+ const tags = listOption(args, 'tag');
128
+ return items.filter((item) => (!query ||
129
+ `${item.name} ${item.description}`.toLowerCase().includes(query)) &&
130
+ tags.every((tag) => item.tags.includes(tag)));
131
+ }
132
+ async function executeRead(command, args, project, signal) {
133
+ if (command === 'agents' || command === 'status') {
134
+ requirePositionals(args, 0);
135
+ return command === 'agents' ? readAgents(project) : readStatus(signal);
136
+ }
137
+ if (command === 'config.get') {
138
+ const [key] = requirePositionals(args, 0, 1);
139
+ if (key && !['locale', 'mcpSecretsInGit'].includes(key))
140
+ throw new OperationFailure('usage.invalidArguments', 'Unknown configuration key.', { key });
141
+ const config = await readUserConfig();
142
+ return {
143
+ result: key
144
+ ? { key, value: config[key] }
145
+ : { config },
146
+ };
147
+ }
148
+ if (command === 'collection.remote.get') {
149
+ requirePositionals(args, 0);
150
+ return {
151
+ result: {
152
+ origin: await optionalGit(collectionPaths().root, ['remote', 'get-url', 'origin'], signal),
153
+ },
154
+ };
155
+ }
156
+ if (command === 'skill.locations' || command === 'mcp.locations') {
157
+ requirePositionals(args, 0);
158
+ const names = listOption(args, 'agent');
159
+ const selectedScopes = scopes(args);
160
+ const root = stringOption(args, 'root');
161
+ if (root && (names.length || args.options.scope))
162
+ throw new OperationFailure('usage.invalidArguments', 'A custom root cannot be combined with agent or scope.');
163
+ if (command === 'skill.locations')
164
+ return readSkillLocations(project, names, selectedScopes, root);
165
+ const locations = await readMcpLocations(project, names, selectedScopes);
166
+ return readResult({
167
+ items: locations.entries.map((entry) => publicLocation(entry, project)),
168
+ }, locations.issues);
169
+ }
170
+ if (command === 'skill.discover') {
171
+ requirePositionals(args, 0);
172
+ const git = stringOption(args, 'git');
173
+ const local = stringOption(args, 'local');
174
+ if (Boolean(git) === Boolean(local))
175
+ throw new OperationFailure('usage.invalidArguments', 'Choose exactly one source: --git or --local.');
176
+ return readDiscovery(project, { ...(git ? { git } : {}), ...(local ? { local } : {}) }, signal);
177
+ }
178
+ if (command === 'skill.search') {
179
+ const [query] = requirePositionals(args, 1);
180
+ const limit = Number(stringOption(args, 'limit') ?? 20);
181
+ if (query.length < 2 || !Number.isSafeInteger(limit) || limit < 1)
182
+ throw new OperationFailure('usage.invalidArguments', 'Search requires at least two characters and a positive integer limit.');
183
+ return readSearch(query, limit, signal);
184
+ }
185
+ const collection = command.startsWith('skill.')
186
+ ? await readSkills()
187
+ : await readMcps();
188
+ if (command.endsWith('.list')) {
189
+ requirePositionals(args, 0);
190
+ const items = filterItems(collection.items, args);
191
+ return readResult({
192
+ items: command.startsWith('mcp.')
193
+ ? await Promise.all(items.map(async (item) => ({
194
+ ...publicMcp(item),
195
+ secrets: await secretStatus(item),
196
+ })))
197
+ : items,
198
+ }, collection.issues);
199
+ }
200
+ const [name] = requirePositionals(args, 1);
201
+ const item = collection.items.find((value) => value.name === name);
202
+ if (!item)
203
+ throw new OperationFailure('usage.selectionNotFound', 'The selected collection item does not exist.', { name });
204
+ if (command === 'skill.show') {
205
+ const state = await readState();
206
+ return {
207
+ result: {
208
+ item: {
209
+ ...item,
210
+ links: state.links.filter((link) => link.skill === name),
211
+ ...(args.options.body
212
+ ? {
213
+ body: await readFile(join(collectionPaths().skills, name, 'SKILL.md'), 'utf8'),
214
+ }
215
+ : {}),
216
+ },
217
+ },
218
+ };
219
+ }
220
+ const mcp = item;
221
+ if (command === 'mcp.secret.status')
222
+ return readResult({ items: await secretStatus(mcp) });
223
+ return {
224
+ result: { item: { ...publicMcp(mcp), secrets: await secretStatus(mcp) } },
225
+ };
226
+ }
227
+ export async function main(argv = process.argv.slice(2)) {
228
+ const help = ['help', '--help', '-h'].includes(argv[0] ?? '') ||
229
+ argv.includes('--help') ||
230
+ argv.includes('-h');
231
+ const invocation = ['help', '--help', '-h'].includes(argv[0] ?? '')
232
+ ? argv.slice(1)
233
+ : argv.filter((token) => !['--help', '-h'].includes(token));
234
+ const parsed = commandPath(invocation);
235
+ const command = Object.hasOwn(COMMAND_OPTIONS, parsed.command)
236
+ ? parsed.command
237
+ : null;
238
+ const context = {
239
+ project: resolve('.'),
240
+ collection: collectionPaths().root,
241
+ dryRun: false,
242
+ };
243
+ const controller = new AbortController();
244
+ const interrupt = () => controller.abort();
245
+ process.on('SIGINT', interrupt);
246
+ process.on('SIGTERM', interrupt);
247
+ let outcome = 'succeeded';
248
+ let result = null;
249
+ let error = null;
250
+ let warnings = [];
251
+ try {
252
+ if (help) {
253
+ if (!command) {
254
+ const namespace = parsed.command;
255
+ if (namespace === 'skill') {
256
+ process.stdout.write(`iskills skill <action> [arguments] [options]
257
+
258
+ Non-interactive Skill actions. Returns one JSON document.
259
+
260
+ Actions:
261
+ list List collected Skills (--query, --tag)
262
+ show <name> Show collected Skill metadata (--body)
263
+ locations List absolute installation paths and link status
264
+ search <query> Search remote catalog on skills.sh (--limit)
265
+ discover Inspect candidate Skills (--git, --local)
266
+ import Validate and collect Skills (--git, --local, --path, --all, --expect-commit)
267
+ create <name> Create a minimal new collected Skill
268
+ adopt [name...] Adopt existing Skill directory lacking collection metadata
269
+ install [name...] Install collected Skills (--agent, --scope, --to, --copy)
270
+ uninstall <path...> Remove installation path and unregister link (--yes)
271
+ materialize <path..> Replace collection symlink in current project with physical copy
272
+ update [name...] Update Skills from recorded upstream Git source
273
+ edit <name> Update tags (--tags, --add-tag, --remove-tag) and note (--note)
274
+ tag rename <old> <new> Rename a Skill tag throughout the collection
275
+ source bind <name> Bind a Skill to a Git repository (--git, --path)
276
+ source unbind <name> Remove recorded Git source binding (--yes)
277
+ remove <name...> Remove collected Skill and unregister usage links (--yes)
278
+
279
+ Run \`iskills help skill <action>\` for detailed arguments, options, and JSON examples.
280
+ `);
281
+ return;
282
+ }
283
+ if (namespace === 'mcp') {
284
+ process.stdout.write(`iskills mcp <action> [arguments] [options]
285
+
286
+ Non-interactive MCP actions. Returns one JSON document.
287
+
288
+ Actions:
289
+ list List collected MCP recipes and secret status
290
+ show <name> Show a collected MCP recipe and secret status
291
+ locations List MCP locations, ownership, and opaque selectors
292
+ create <name> Create collected MCP from recipe input (--input <file|->)
293
+ import Import from native JSON snippet or existing location (--input, --location)
294
+ add <name...> Install collected MCPs to agents (--agent, --scope)
295
+ update <name> Update existing owned MCP location from collected recipe (--location)
296
+ enable <selector..> Enable MCP location
297
+ disable <selector..> Disable MCP location
298
+ uninstall <selector> Remove MCP from target agent config (--yes)
299
+ remove <name...> Remove MCP recipe and overlay secrets from collection (--yes)
300
+ edit <name> Edit recipe, description, tags, note (--recipe-input, --tags)
301
+ rename <old> <new> Rename collected MCP recipe
302
+ tag rename <old> <new> Rename an MCP tag throughout the collection
303
+ probe <name> Probe remote HTTP/SSE MCP endpoint for connectivity and auth
304
+ secret status <name> List declared and configured secret keys
305
+ secret set <name> Set environment variable, header, or URL secret (--env, --header, --url)
306
+ secret unset <name> Delete secret overlay value (--env, --header, --url, --yes)
307
+
308
+ Run \`iskills help mcp <action>\` for detailed arguments, options, and JSON examples.
309
+ `);
310
+ return;
311
+ }
312
+ if (namespace === 'collection') {
313
+ process.stdout.write(`iskills collection <action> [arguments] [options]
314
+
315
+ Manage collection Git repository and synchronization.
316
+
317
+ Actions:
318
+ init Initialize collection Git repository (--remote)
319
+ sync Synchronize collection with remote Git repository in foreground
320
+ remote get Show configured Git remote URL
321
+ remote set <url> Configure Git remote URL
322
+ remote clear Remove configured Git remote URL (--yes)
323
+
324
+ Run \`iskills help collection <action>\` for details.
325
+ `);
326
+ return;
327
+ }
328
+ if (namespace === 'config') {
329
+ process.stdout.write(`iskills config <action> [arguments]
330
+
331
+ Manage collection preferences.
332
+
333
+ Actions:
334
+ get [key] Read all config or a specific key (locale, mcpSecretsInGit)
335
+ set <key> <value> Update a config key (locale: system|zh|en, mcpSecretsInGit: true|false)
336
+
337
+ Run \`iskills help config <action>\` for details.
338
+ `);
339
+ return;
340
+ }
341
+ if (invocation.length === 0) {
342
+ process.stdout.write('iskills Agent CLI\n\nCommands: agents, status, skill <action>, mcp <action>, collection <action>, config get|set\n\nRun `iskills help <command path>` for a command description, arguments, options, output format, and exit codes.\nAgent commands never prompt and emit one JSON document. Use --dry-run to inspect writes before applying them.\n');
343
+ return;
344
+ }
345
+ }
346
+ }
347
+ if (!command)
348
+ throw new OperationFailure('usage.unknownCommand', 'Unknown command.', {
349
+ command: parsed.command,
350
+ });
351
+ if (help) {
352
+ const argumentsByCommand = {
353
+ 'skill.show': '<name>',
354
+ 'skill.search': '<query>',
355
+ 'skill.create': '<name>',
356
+ 'skill.adopt': '[name...]',
357
+ 'skill.install': '[name...]',
358
+ 'skill.remove': '<name...>',
359
+ 'skill.update': '[name...]',
360
+ 'skill.uninstall': '<absolute-path...>',
361
+ 'skill.materialize': '<absolute-path...>',
362
+ 'skill.edit': '<name>',
363
+ 'skill.tag.rename': '<from> <to>',
364
+ 'skill.source.bind': '<name>',
365
+ 'skill.source.unbind': '<name>',
366
+ 'mcp.show': '<name>',
367
+ 'mcp.create': '<name>',
368
+ 'mcp.add': '<name...>',
369
+ 'mcp.update': '<name>',
370
+ 'mcp.enable': '<selector...>',
371
+ 'mcp.disable': '<selector...>',
372
+ 'mcp.uninstall': '<selector...>',
373
+ 'mcp.remove': '<name...>',
374
+ 'mcp.edit': '<name>',
375
+ 'mcp.rename': '<from> <to>',
376
+ 'mcp.tag.rename': '<from> <to>',
377
+ 'mcp.probe': '<name>',
378
+ 'mcp.secret.set': '<name>',
379
+ 'mcp.secret.unset': '<name>',
380
+ 'mcp.secret.status': '<name>',
381
+ 'collection.remote.set': '<source>',
382
+ 'config.get': '[key]',
383
+ 'config.set': '<key> <value>',
384
+ };
385
+ const OPTION_DOCS = {
386
+ project: 'Target project root directory (defaults to current working directory).',
387
+ 'dry-run': 'Preflight and validate the operation, computing items and git actions without persisting changes.',
388
+ query: 'Substring filter matched against name and description (case-insensitive).',
389
+ tag: 'Filter by tag (all specified tags must match) or assign tags on import.',
390
+ body: 'Include full SKILL.md file content in the returned item object.',
391
+ agent: 'Target Agent identifier(s) (e.g. claude, codex, cursor, opencode, trae, windsurf, pi).',
392
+ scope: 'Target configuration scope: "project" or "global".',
393
+ root: 'Custom destination skill root directory for locations query.',
394
+ git: 'Git repository specifier (owner/repo, https://... or git@...).',
395
+ local: 'Absolute or relative path to a local directory.',
396
+ limit: 'Maximum number of items to return (positive integer).',
397
+ path: 'Relative path within the source repository/directory to the skill directory (e.g. skills/my-skill, or "." if root is the skill itself). Required unless --all is specified.',
398
+ all: 'Target all discovered or eligible skills/locations instead of specifying individual names (or specify --all to import all skills from source).',
399
+ 'expect-commit': 'Expected Git commit hash; rejects import if repository HEAD differs without pinning the ref.',
400
+ replace: 'Explicitly authorize replacing existing content or configuration.',
401
+ yes: 'Explicitly authorize destructive operations (delete, remove, uninstall, clear).',
402
+ 'from-location': 'Source skill installation path to replicate across other agents.',
403
+ to: 'Custom installation root directory.',
404
+ copy: 'Install skill as a directory copy rather than a symlink reference.',
405
+ 'allow-delete': 'Explicitly allow skill update to delete a local skill if it was deleted in upstream Git.',
406
+ tags: 'Full replacement array of tags as a JSON string (e.g. \'["tag1", "tag2"]\').',
407
+ 'add-tag': 'Tag name to add to existing tags.',
408
+ 'remove-tag': 'Tag name to remove from existing tags.',
409
+ note: 'Private note text (pass empty string to clear).',
410
+ input: 'Path to UTF-8 JSON file containing recipe or server snippet (or "-" for stdin).',
411
+ location: 'Target opaque MCP location selector string returned by `mcp locations`.',
412
+ name: 'Explicit name for the MCP or skill.',
413
+ 'recipe-input': 'Path to UTF-8 JSON file containing updated recipe object (or "-" for stdin).',
414
+ description: 'Updated description text for MCP.',
415
+ env: 'Environment variable name for MCP secret.',
416
+ header: 'HTTP header name for MCP secret (e.g. Authorization; case-insensitive).',
417
+ url: 'Set the full URL secret (used when recipe URL omits query parameters or credentials).',
418
+ 'value-stdin': 'Read secret value directly from standard input (stripped of single trailing newline).',
419
+ 'value-file': 'Path to file containing the secret value (stripped of single trailing newline).',
420
+ remote: 'Remote Git repository URL for the collection.',
421
+ };
422
+ const COMMAND_EXAMPLES = {
423
+ 'skill.list': [
424
+ 'iskills skill list --query review',
425
+ 'iskills skill list --tag linter --tag git',
426
+ ],
427
+ 'skill.show': [
428
+ 'iskills skill show my-skill',
429
+ 'iskills skill show my-skill --body',
430
+ ],
431
+ 'skill.search': [
432
+ 'iskills skill search "code review"',
433
+ 'iskills skill search security --limit 5',
434
+ ],
435
+ 'skill.discover': [
436
+ 'iskills skill discover --git anthropics/skills',
437
+ 'iskills skill discover --local ../my-skills-repo',
438
+ ],
439
+ 'skill.import': [
440
+ 'iskills skill import --git anthropics/skills --path skills/review',
441
+ 'iskills skill import --git anthropics/skills --all --expect-commit a1b2c3d --dry-run',
442
+ 'iskills skill import --local ./my-skill-dir --path . --dry-run',
443
+ 'iskills skill import --local ./skills-monorepo --all',
444
+ ],
445
+ 'skill.create': [
446
+ 'iskills skill create my-new-skill',
447
+ ],
448
+ 'skill.install': [
449
+ 'iskills skill install my-skill --agent codex --scope project',
450
+ 'iskills skill install my-skill --agent cursor --scope global --copy',
451
+ 'iskills skill install my-skill --to ./custom/agent/skills',
452
+ ],
453
+ 'skill.locations': [
454
+ 'iskills skill locations --scope project',
455
+ 'iskills skill locations --agent codex',
456
+ ],
457
+ 'skill.uninstall': [
458
+ 'iskills skill uninstall /path/to/project/.agents/skills/my-skill --yes',
459
+ ],
460
+ 'skill.materialize': [
461
+ 'iskills skill materialize /path/to/project/.agents/skills/my-skill',
462
+ ],
463
+ 'skill.update': [
464
+ 'iskills skill update my-skill',
465
+ 'iskills skill update --all --dry-run',
466
+ 'iskills skill update my-skill --allow-delete --yes',
467
+ ],
468
+ 'skill.edit': [
469
+ 'iskills skill edit my-skill --add-tag featured --note "Production ready"',
470
+ 'iskills skill edit my-skill --tags \'["ci", "testing"]\'',
471
+ ],
472
+ 'skill.remove': [
473
+ 'iskills skill remove my-skill --yes',
474
+ ],
475
+ 'mcp.list': [
476
+ 'iskills mcp list',
477
+ 'iskills mcp list --query github',
478
+ ],
479
+ 'mcp.create': [
480
+ 'iskills mcp create github-mcp --input recipe.json',
481
+ ],
482
+ 'mcp.import': [
483
+ 'iskills mcp import --input snippet.json --name custom-server',
484
+ 'iskills mcp import --location "<selector-from-mcp-locations>"',
485
+ ],
486
+ 'mcp.locations': [
487
+ 'iskills mcp locations',
488
+ 'iskills mcp locations --agent claude --scope project',
489
+ ],
490
+ 'mcp.add': [
491
+ 'iskills mcp add github-mcp --agent claude --scope project',
492
+ 'iskills mcp add github-mcp --agent cursor --scope global --replace',
493
+ ],
494
+ 'mcp.secret.set': [
495
+ 'iskills mcp secret set github-mcp --header Authorization --value-file token.txt',
496
+ 'printf \'%s\' "$SECRET" | iskills mcp secret set github-mcp --env GITHUB_TOKEN --value-stdin',
497
+ ],
498
+ 'mcp.secret.status': [
499
+ 'iskills mcp secret status github-mcp',
500
+ ],
501
+ 'mcp.probe': [
502
+ 'iskills mcp probe github-mcp',
503
+ ],
504
+ 'mcp.enable': [
505
+ 'iskills mcp enable "<selector>"',
506
+ ],
507
+ 'mcp.disable': [
508
+ 'iskills mcp disable "<selector>"',
509
+ ],
510
+ 'mcp.uninstall': [
511
+ 'iskills mcp uninstall "<selector>" --yes',
512
+ ],
513
+ 'mcp.remove': [
514
+ 'iskills mcp remove github-mcp --yes',
515
+ ],
516
+ 'collection.init': [
517
+ 'iskills collection init',
518
+ 'iskills collection init --remote git@github.com:user/skills-collection.git',
519
+ ],
520
+ 'collection.sync': [
521
+ 'iskills collection sync --dry-run',
522
+ 'iskills collection sync',
523
+ ],
524
+ 'config.get': [
525
+ 'iskills config get',
526
+ 'iskills config get locale',
527
+ ],
528
+ 'config.set': [
529
+ 'iskills config set locale en',
530
+ 'iskills config set mcpSecretsInGit true',
531
+ ],
532
+ };
533
+ const SHAPES = {
534
+ 'skill.import': `Skill Directory Requirements:
535
+ A valid Skill is a standalone directory containing a top-level SKILL.md file.
536
+ Subdirectories and files are permitted, but symlinks that escape the skill tree root are rejected.`,
537
+ 'skill.create': `Created Skill Structure:
538
+ <collection-root>/skills/<name>/
539
+ └── SKILL.md (minimal markdown template containing skill name and description)`,
540
+ 'mcp.create': `Expected --input JSON shape:
541
+ {
542
+ "recipe": {
543
+ "transport": "stdio" | "http" | "sse",
544
+ "command": "string (required for stdio)",
545
+ "args": ["string"],
546
+ "cwd": "string",
547
+ "url": "string (required for http/sse)",
548
+ "envKeys": ["ENV_VAR_NAME"],
549
+ "headerKeys": ["HEADER_NAME"]
550
+ },
551
+ "description": "Optional human readable description",
552
+ "tags": ["tag1", "tag2"],
553
+ "note": "Optional private note"
554
+ }
555
+ Note: Do not put secret values in recipe. Use \`iskills mcp secret set\` to configure secrets securely.`,
556
+ 'mcp.edit': `Expected --recipe-input JSON shape:
557
+ {
558
+ "transport": "stdio" | "http" | "sse",
559
+ "command": "string (for stdio)",
560
+ "args": ["string"],
561
+ "cwd": "string",
562
+ "url": "string (for http/sse)",
563
+ "envKeys": ["ENV_VAR_NAME"],
564
+ "headerKeys": ["HEADER_NAME"]
565
+ }`,
566
+ };
567
+ const DESCRIPTIONS = {
568
+ root: 'Agent CLI for Skills, MCP servers, and the collection. Use `iskills agents` to inspect capabilities, `iskills status` to inspect state, and `iskills <command> --help` for command details. Query commands do not mutate state. Write commands support --dry-run; inspect the JSON result before retrying failed or unknown-state operations.',
569
+ agents: 'List supported Agents and their configured capabilities.',
570
+ status: 'Inspect collection initialization, Git state, conflicts, and read issues without changing state.',
571
+ 'skill.list': 'List collected Skills; filter by name/description substring and all requested tags.',
572
+ 'skill.show': 'Show one exact collected Skill. --body includes SKILL.md content.',
573
+ 'skill.search': 'Search the remote Skill catalog; this does not collect or install results.',
574
+ 'skill.discover': 'Inspect a local directory or Git repository and return candidate Skills without collecting them.',
575
+ 'skill.import': 'Validate and collect selected Skills from a local directory or Git source. Local import moves the source; inspect --dry-run first.',
576
+ 'skill.create': 'Create a minimal new collected Skill.',
577
+ 'skill.adopt': 'Adopt valid Skill directories that lack collection metadata; does not infer their source.',
578
+ 'skill.install': 'Install collected Skills as references or copies. Choose explicit --agent/--scope or a custom --to root.',
579
+ 'skill.locations': 'List absolute installation paths and their relationship to the collection.',
580
+ 'skill.uninstall': 'Remove selected installation paths and their registration, preserving collected Skills. Requires --yes.',
581
+ 'skill.materialize': 'Replace eligible collection references in the current project with physical copies.',
582
+ 'skill.remove': 'Remove collected Skills and report origin restoration and removed usage paths. Requires --yes.',
583
+ 'skill.update': 'Update Skills from their recorded source. Upstream deletion requires both --allow-delete and --yes.',
584
+ 'skill.edit': 'Update tags and/or private note for a collected Skill.',
585
+ 'skill.tag.rename': 'Rename a Skill tag throughout the collection.',
586
+ 'skill.source.bind': 'Bind a collected Skill to a Git source and establish its current tree as the baseline.',
587
+ 'skill.source.unbind': 'Remove a recorded Git source binding. Requires --yes.',
588
+ 'mcp.list': 'List collected MCP recipes and secret key/configuration status; never returns secret values.',
589
+ 'mcp.show': 'Show a collected MCP recipe and secret key/configuration status; never returns secret values.',
590
+ 'mcp.locations': 'List MCP locations and their opaque selectors. Pass selectors back unchanged for location actions.',
591
+ 'mcp.create': 'Create a collected MCP from the strict recipe JSON input shape.',
592
+ 'mcp.import': 'Collect MCPs from native JSON snippets or selected MCP locations without changing their source configuration.',
593
+ 'mcp.add': 'Write collected MCPs to explicitly selected Agent and scope targets.',
594
+ 'mcp.update': 'Update only the selected owned MCP locations from a collected recipe.',
595
+ 'mcp.enable': 'Enable selected MCP locations; this sets state and is safe to repeat.',
596
+ 'mcp.disable': 'Disable selected MCP locations; this sets state and is safe to repeat.',
597
+ 'mcp.uninstall': 'Remove selected owned MCP locations while preserving the collected recipe. Requires --yes.',
598
+ 'mcp.remove': 'Remove collected MCP recipes and secrets without changing installed locations. Requires --yes.',
599
+ 'mcp.edit': 'Replace recipe and/or edit metadata for a collected MCP; changing endpoint clears prior endpoint secrets.',
600
+ 'mcp.rename': 'Rename a collected MCP and its secret-overlay key; does not change Agent native keys.',
601
+ 'mcp.tag.rename': 'Rename an MCP tag throughout the collection.',
602
+ 'mcp.probe': 'Explicitly probe a collected HTTP/SSE endpoint; does not start stdio servers.',
603
+ 'mcp.secret.set': 'Set one MCP secret from stdin or a file; the secret value is never accepted as an argv string.',
604
+ 'mcp.secret.unset': 'Delete a secret value. Requires --yes.',
605
+ 'mcp.secret.status': 'List declared/configured secret keys without returning their values.',
606
+ 'collection.init': 'Initialize collection Git and optionally configure its remote.',
607
+ 'collection.sync': 'Explicitly synchronize the collection with its configured remote in the foreground.',
608
+ 'collection.remote.get': 'Read the collection Git origin without initializing or changing anything.',
609
+ 'collection.remote.set': 'Set the collection Git origin; does not synchronize.',
610
+ 'collection.remote.clear': 'Remove the collection Git origin. Requires --yes.',
611
+ 'config.get': 'Read all supported configuration or one key.',
612
+ 'config.set': 'Set locale or MCP-secret Git tracking preference.',
613
+ };
614
+ const usageLine = `Usage: iskills ${command.replaceAll('.', ' ')}${argumentsByCommand[command] ? ` ${argumentsByCommand[command]}` : ''} [options]`;
615
+ const descriptionText = DESCRIPTIONS[command] ?? 'Run this command.';
616
+ const optionLines = [
617
+ ' --project <directory> ' + OPTION_DOCS.project,
618
+ ' -h, --help Show help for this command.',
619
+ ...Object.entries(COMMAND_OPTIONS[command]).map(([key, kind]) => {
620
+ const typeLabel = kind === 'boolean' ? '' : ' <value>';
621
+ const repLabel = kind === 'multiple' ? ' (repeatable)' : '';
622
+ const optStr = ` --${key}${typeLabel}${repLabel}`;
623
+ const doc = OPTION_DOCS[key] ?? '';
624
+ return doc ? `${optStr.padEnd(28)} ${doc}` : optStr;
625
+ }),
626
+ ].join('\n');
627
+ const shapeSection = SHAPES[command] ? `\nInput Shape:\n${SHAPES[command]}\n` : '';
628
+ const examples = COMMAND_EXAMPLES[command]?.length
629
+ ? `\nExamples:\n${COMMAND_EXAMPLES[command].map((cmd) => ` ${cmd}`).join('\n')}\n`
630
+ : '';
631
+ process.stdout.write(`${usageLine}\n\n${descriptionText}\n\nOptions:\n${optionLines}\n${shapeSection}${examples}\nOutput: one JSON document (except help/version). Writes support --dry-run.\nExit codes: 0 success, 2 usage/selection/authorization, 3 preflight conflict, 1 runtime failure, 130 interrupted.\n`);
632
+ return;
633
+ }
634
+ const args = parseArguments(parsed.rest, COMMAND_OPTIONS[command]);
635
+ const stdinConsumers = ['input', 'recipe-input', 'value-file'].filter((key) => args.options[key] === '-').length + (args.options['value-stdin'] ? 1 : 0);
636
+ if (stdinConsumers > 1)
637
+ throw new OperationFailure('usage.invalidArguments', 'Only one stdin consumer is allowed.');
638
+ context.dryRun = args.options['dry-run'] === true;
639
+ context.project = resolve(stringOption(args, 'project') ?? '.');
640
+ try {
641
+ if (!(await stat(context.project)).isDirectory())
642
+ throw new Error();
643
+ }
644
+ catch {
645
+ const path = context.project;
646
+ context.project = null;
647
+ throw new OperationFailure('usage.invalidLocation', 'The project must be an existing directory.', { path });
648
+ }
649
+ process.env.SK_NO_BACKGROUND_SYNC = '1';
650
+ process.env.ISKILLS_AGENT_CLI = '1';
651
+ const project = context.project;
652
+ const response = await withProcessSignal(controller.signal, async () => command in READ_OPTIONS
653
+ ? executeRead(command, args, project, controller.signal)
654
+ : command === 'mcp.probe'
655
+ ? executeProbe(args, controller.signal)
656
+ : command.startsWith('skill.')
657
+ ? executeSkillWrite({
658
+ command,
659
+ project,
660
+ names: args.positional,
661
+ options: args.options,
662
+ signal: controller.signal,
663
+ })
664
+ : command.startsWith('mcp.')
665
+ ? executeMcpWrite({
666
+ command,
667
+ project,
668
+ names: args.positional,
669
+ options: args.options,
670
+ signal: controller.signal,
671
+ })
672
+ : executeCollectionWrite(command, args.positional, args.options, controller.signal));
673
+ result = response.result;
674
+ error = response.error ?? null;
675
+ warnings = response.warnings ?? [];
676
+ if (controller.signal.aborted && !error)
677
+ error = {
678
+ code: 'execution.interrupted',
679
+ message: 'The operation was interrupted.',
680
+ details: {},
681
+ retry: 'inspect-state',
682
+ };
683
+ outcome = response.partial ? 'partial' : error ? 'failed' : 'succeeded';
684
+ process.exitCode = controller.signal.aborted
685
+ ? 130
686
+ : (response.exitCode ?? 0);
687
+ }
688
+ catch (cause) {
689
+ error = controller.signal.aborted
690
+ ? {
691
+ code: 'execution.interrupted',
692
+ message: 'The operation was interrupted.',
693
+ details: {},
694
+ retry: 'inspect-state',
695
+ }
696
+ : operationError(cause);
697
+ outcome = 'failed';
698
+ process.exitCode = controller.signal.aborted
699
+ ? 130
700
+ : cause instanceof OperationFailure
701
+ ? cause.exitCode
702
+ : error.code.startsWith('usage.')
703
+ ? 2
704
+ : 1;
705
+ }
706
+ finally {
707
+ process.off('SIGINT', interrupt);
708
+ process.off('SIGTERM', interrupt);
709
+ }
710
+ process.stdout.once('error', (cause) => {
711
+ if (cause.code === 'EPIPE')
712
+ process.exitCode = 1;
713
+ });
714
+ const envelope = {
715
+ schemaVersion: 1,
716
+ command,
717
+ outcome,
718
+ context,
719
+ result,
720
+ warnings,
721
+ error,
722
+ };
723
+ if (error &&
724
+ process.exitCode === 1 &&
725
+ command &&
726
+ Object.hasOwn(WRITE_OPTIONS, command) &&
727
+ !context.dryRun &&
728
+ Array.isArray(result?.items) &&
729
+ result.items.some((item) => item.status === 'failed')) {
730
+ try {
731
+ const directory = join(collectionPaths().local, 'logs');
732
+ const logPath = join(directory, `${Date.now()}-${process.pid}-agent.json`);
733
+ await mkdir(directory, { recursive: true });
734
+ await writeFile(logPath, `${JSON.stringify(redactOutput(envelope))}\n`, {
735
+ mode: 0o600,
736
+ });
737
+ envelope.logPath = logPath;
738
+ }
739
+ catch { }
740
+ }
741
+ process.stdout.write(`${JSON.stringify(redactOutput(envelope))}\n`);
742
+ }
743
+ async function executeProbe(args, signal) {
744
+ const [name] = requirePositionals(args, 1);
745
+ const mcp = (await readMcps()).items.find((item) => item.name === name);
746
+ if (!mcp)
747
+ throw new OperationFailure('usage.selectionNotFound', 'The MCP is not collected.', { name });
748
+ if (mcp.recipe.transport === 'stdio')
749
+ throw new OperationFailure('usage.unsupportedCapability', 'Only HTTP/SSE endpoints can be probed.', { name });
750
+ let httpStatus = null;
751
+ const status = await probeCollectedHttp(name, {
752
+ timeoutMs: 30_000,
753
+ signal,
754
+ onResponse: (value) => {
755
+ httpStatus = value;
756
+ },
757
+ });
758
+ return {
759
+ result: { status, httpStatus },
760
+ ...(status === 'failed'
761
+ ? {
762
+ error: {
763
+ code: 'execution.networkFailed',
764
+ message: 'The MCP endpoint could not be reached.',
765
+ details: { name, timeoutMs: 30_000 },
766
+ retry: 'after-fix',
767
+ },
768
+ exitCode: 1,
769
+ }
770
+ : {}),
771
+ };
772
+ }
773
+ //# sourceMappingURL=index.js.map