skill-rails 0.2.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/.claude-plugin/marketplace.json +16 -0
- package/.claude-plugin/plugin.json +16 -0
- package/.mcp.json +8 -0
- package/LICENSE +21 -0
- package/README.md +255 -0
- package/bin/skill-rails.js +4 -0
- package/dist/api.d.ts +38 -0
- package/dist/api.js +73 -0
- package/dist/api.js.map +1 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +112 -0
- package/dist/cli.js.map +1 -0
- package/dist/engine.d.ts +18 -0
- package/dist/engine.js +312 -0
- package/dist/engine.js.map +1 -0
- package/dist/expressions.d.ts +12 -0
- package/dist/expressions.js +44 -0
- package/dist/expressions.js.map +1 -0
- package/dist/flow.d.ts +11 -0
- package/dist/flow.js +137 -0
- package/dist/flow.js.map +1 -0
- package/dist/mcp.d.ts +5 -0
- package/dist/mcp.js +37 -0
- package/dist/mcp.js.map +1 -0
- package/dist/run.d.ts +6 -0
- package/dist/run.js +67 -0
- package/dist/run.js.map +1 -0
- package/dist/schema.d.ts +10 -0
- package/dist/schema.js +15 -0
- package/dist/schema.js.map +1 -0
- package/dist/state.d.ts +6 -0
- package/dist/state.js +24 -0
- package/dist/state.js.map +1 -0
- package/dist/testing.d.ts +50 -0
- package/dist/testing.js +233 -0
- package/dist/testing.js.map +1 -0
- package/dist/types.d.ts +200 -0
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -0
- package/docs/format.md +256 -0
- package/docs/testing.md +100 -0
- package/examples/hello/flow.yaml +32 -0
- package/examples/hello/tests/hello.test.yaml +22 -0
- package/examples/open-pr/flow.yaml +87 -0
- package/examples/open-pr/prompts/text.md +26 -0
- package/examples/open-pr/scripts/body-file.sh +10 -0
- package/examples/open-pr/scripts/context.sh +21 -0
- package/examples/open-pr/scripts/create.sh +6 -0
- package/examples/open-pr/scripts/push.sh +8 -0
- package/examples/open-pr/tests/open-pr.test.yaml +42 -0
- package/examples/open-pr/tests/stubs/gh +9 -0
- package/package.json +72 -0
- package/schema/flow.schema.json +440 -0
- package/skills/create-skill-rails/SKILL.md +72 -0
- package/skills/create-skill-rails/template/SKILL.md +24 -0
- package/skills/migrate-to-skill-rails/SKILL.md +78 -0
- package/skills/run-skill-rails/SKILL.md +63 -0
package/package.json
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "skill-rails",
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Deterministic, testable YAML flows for AI agent skills, in GitHub Actions syntax.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"bin": "bin/skill-rails.js",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./dist/api.d.ts",
|
|
11
|
+
"import": "./dist/api.js"
|
|
12
|
+
},
|
|
13
|
+
"./schema": "./schema/flow.schema.json"
|
|
14
|
+
},
|
|
15
|
+
"files": [
|
|
16
|
+
"bin",
|
|
17
|
+
"dist",
|
|
18
|
+
"schema",
|
|
19
|
+
"skills",
|
|
20
|
+
"docs",
|
|
21
|
+
"examples",
|
|
22
|
+
".claude-plugin",
|
|
23
|
+
".mcp.json"
|
|
24
|
+
],
|
|
25
|
+
"engines": {
|
|
26
|
+
"node": ">=20"
|
|
27
|
+
},
|
|
28
|
+
"scripts": {
|
|
29
|
+
"build": "tsc -p tsconfig.json",
|
|
30
|
+
"typecheck": "tsc -p tsconfig.test.json",
|
|
31
|
+
"test": "yarn build && vitest run",
|
|
32
|
+
"prepack": "yarn build",
|
|
33
|
+
"prepublishOnly": "yarn typecheck && yarn test"
|
|
34
|
+
},
|
|
35
|
+
"keywords": [
|
|
36
|
+
"agent",
|
|
37
|
+
"skills",
|
|
38
|
+
"claude-code",
|
|
39
|
+
"workflow",
|
|
40
|
+
"mcp",
|
|
41
|
+
"llm",
|
|
42
|
+
"github-actions"
|
|
43
|
+
],
|
|
44
|
+
"dependencies": {
|
|
45
|
+
"@actions/expressions": "^0.3.61",
|
|
46
|
+
"@modelcontextprotocol/sdk": "^1.32.2",
|
|
47
|
+
"ajv": "^8.17.1",
|
|
48
|
+
"js-yaml": "^4.1.0",
|
|
49
|
+
"zod": "^3.25.0"
|
|
50
|
+
},
|
|
51
|
+
"devDependencies": {
|
|
52
|
+
"@types/js-yaml": "^4.0.9",
|
|
53
|
+
"@types/node": "^22.20.5",
|
|
54
|
+
"typescript": "^5.9.3",
|
|
55
|
+
"vitest": "^4.1.4"
|
|
56
|
+
},
|
|
57
|
+
"author": {
|
|
58
|
+
"name": "Juani Galán",
|
|
59
|
+
"url": "https://github.com/juanigalan91"
|
|
60
|
+
},
|
|
61
|
+
"repository": {
|
|
62
|
+
"type": "git",
|
|
63
|
+
"url": "git+https://github.com/juanigalan91/skill-rails.git"
|
|
64
|
+
},
|
|
65
|
+
"homepage": "https://github.com/juanigalan91/skill-rails#readme",
|
|
66
|
+
"bugs": {
|
|
67
|
+
"url": "https://github.com/juanigalan91/skill-rails/issues"
|
|
68
|
+
},
|
|
69
|
+
"main": "./dist/api.js",
|
|
70
|
+
"types": "./dist/api.d.ts",
|
|
71
|
+
"packageManager": "yarn@4.18.0"
|
|
72
|
+
}
|
|
@@ -0,0 +1,440 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"$id": "https://raw.githubusercontent.com/juanigalan91/skill-rails/main/schema/flow.schema.json",
|
|
4
|
+
"title": "skill-rails flow",
|
|
5
|
+
"description": "A deterministic flow for an AI agent skill. The runner does the run and stop steps; the agent does the skill, prompt and ask steps, one at a time.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": [
|
|
8
|
+
"name",
|
|
9
|
+
"steps"
|
|
10
|
+
],
|
|
11
|
+
"additionalProperties": false,
|
|
12
|
+
"properties": {
|
|
13
|
+
"name": {
|
|
14
|
+
"$ref": "#/definitions/id",
|
|
15
|
+
"description": "The flow name. The state file and the done command use it."
|
|
16
|
+
},
|
|
17
|
+
"description": {
|
|
18
|
+
"type": "string"
|
|
19
|
+
},
|
|
20
|
+
"inputs": {
|
|
21
|
+
"type": "object",
|
|
22
|
+
"propertyNames": {
|
|
23
|
+
"pattern": "^[A-Za-z_][A-Za-z0-9_-]*$"
|
|
24
|
+
},
|
|
25
|
+
"additionalProperties": {
|
|
26
|
+
"type": "object",
|
|
27
|
+
"additionalProperties": false,
|
|
28
|
+
"properties": {
|
|
29
|
+
"type": {
|
|
30
|
+
"enum": [
|
|
31
|
+
"string",
|
|
32
|
+
"boolean",
|
|
33
|
+
"number"
|
|
34
|
+
]
|
|
35
|
+
},
|
|
36
|
+
"default": {
|
|
37
|
+
"type": [
|
|
38
|
+
"string",
|
|
39
|
+
"boolean",
|
|
40
|
+
"number"
|
|
41
|
+
]
|
|
42
|
+
},
|
|
43
|
+
"required": {
|
|
44
|
+
"type": "boolean"
|
|
45
|
+
},
|
|
46
|
+
"description": {
|
|
47
|
+
"type": "string"
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
},
|
|
52
|
+
"steps": {
|
|
53
|
+
"type": "array",
|
|
54
|
+
"minItems": 1,
|
|
55
|
+
"items": {
|
|
56
|
+
"$ref": "#/definitions/step"
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
},
|
|
60
|
+
"definitions": {
|
|
61
|
+
"id": {
|
|
62
|
+
"type": "string",
|
|
63
|
+
"pattern": "^[a-z][a-z0-9-]*$"
|
|
64
|
+
},
|
|
65
|
+
"if": {
|
|
66
|
+
"type": [
|
|
67
|
+
"string",
|
|
68
|
+
"boolean"
|
|
69
|
+
],
|
|
70
|
+
"description": "A ${{ }} expression or a bare expression. The step is skipped when it is false."
|
|
71
|
+
},
|
|
72
|
+
"outputSchema": {
|
|
73
|
+
"type": "object",
|
|
74
|
+
"description": "JSON Schema of the output that the agent reports. The runner validates it."
|
|
75
|
+
},
|
|
76
|
+
"promptFile": {
|
|
77
|
+
"type": "string",
|
|
78
|
+
"description": "A Markdown file with the instructions, relative to the flow file. Its ${{ }} expressions are filled."
|
|
79
|
+
},
|
|
80
|
+
"step": {
|
|
81
|
+
"oneOf": [
|
|
82
|
+
{
|
|
83
|
+
"$ref": "#/definitions/runStep"
|
|
84
|
+
},
|
|
85
|
+
{
|
|
86
|
+
"$ref": "#/definitions/skillStep"
|
|
87
|
+
},
|
|
88
|
+
{
|
|
89
|
+
"$ref": "#/definitions/promptStep"
|
|
90
|
+
},
|
|
91
|
+
{
|
|
92
|
+
"$ref": "#/definitions/askStep"
|
|
93
|
+
},
|
|
94
|
+
{
|
|
95
|
+
"$ref": "#/definitions/stopStep"
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
"$ref": "#/definitions/foreachStep"
|
|
99
|
+
},
|
|
100
|
+
{
|
|
101
|
+
"$ref": "#/definitions/usesStep"
|
|
102
|
+
},
|
|
103
|
+
{
|
|
104
|
+
"$ref": "#/definitions/breakStep"
|
|
105
|
+
}
|
|
106
|
+
]
|
|
107
|
+
},
|
|
108
|
+
"runStep": {
|
|
109
|
+
"type": "object",
|
|
110
|
+
"description": "A shell step that the runner runs with bash. It writes outputs to $FLOW_OUTPUT.",
|
|
111
|
+
"required": [
|
|
112
|
+
"run"
|
|
113
|
+
],
|
|
114
|
+
"additionalProperties": false,
|
|
115
|
+
"properties": {
|
|
116
|
+
"id": {
|
|
117
|
+
"$ref": "#/definitions/id"
|
|
118
|
+
},
|
|
119
|
+
"if": {
|
|
120
|
+
"$ref": "#/definitions/if"
|
|
121
|
+
},
|
|
122
|
+
"run": {
|
|
123
|
+
"type": "string",
|
|
124
|
+
"not": {
|
|
125
|
+
"pattern": "\\$\\{\\{"
|
|
126
|
+
},
|
|
127
|
+
"description": "Bash. Pass values with env: a ${{ }} in the command is a shell injection. The scripts/ folder next to the flow is in PATH."
|
|
128
|
+
},
|
|
129
|
+
"env": {
|
|
130
|
+
"type": "object",
|
|
131
|
+
"description": "Environment variables. Values can be ${{ }} expressions; a list becomes one line per item."
|
|
132
|
+
},
|
|
133
|
+
"continue-on-error": {
|
|
134
|
+
"type": "boolean",
|
|
135
|
+
"description": "Go on when the command fails. steps.<id>.outcome is then failure."
|
|
136
|
+
},
|
|
137
|
+
"until": {
|
|
138
|
+
"$ref": "#/definitions/if",
|
|
139
|
+
"description": "Poll: run the command again until this condition is true. steps.<id> holds the result of the last attempt."
|
|
140
|
+
},
|
|
141
|
+
"interval-seconds": {
|
|
142
|
+
"type": "number",
|
|
143
|
+
"description": "Poll: the wait between two attempts (default 30).",
|
|
144
|
+
"exclusiveMinimum": 0
|
|
145
|
+
},
|
|
146
|
+
"timeout-minutes": {
|
|
147
|
+
"type": "number",
|
|
148
|
+
"exclusiveMinimum": 0,
|
|
149
|
+
"description": "Poll: the time limit (default 30). With no until, the time limit of one run (default 10)."
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
},
|
|
153
|
+
"skillStep": {
|
|
154
|
+
"type": "object",
|
|
155
|
+
"description": "The agent invokes another skill, then follows the optional instructions.",
|
|
156
|
+
"required": [
|
|
157
|
+
"id",
|
|
158
|
+
"skill"
|
|
159
|
+
],
|
|
160
|
+
"not": {
|
|
161
|
+
"required": [
|
|
162
|
+
"prompt",
|
|
163
|
+
"prompt-file"
|
|
164
|
+
]
|
|
165
|
+
},
|
|
166
|
+
"additionalProperties": false,
|
|
167
|
+
"properties": {
|
|
168
|
+
"id": {
|
|
169
|
+
"$ref": "#/definitions/id"
|
|
170
|
+
},
|
|
171
|
+
"if": {
|
|
172
|
+
"$ref": "#/definitions/if"
|
|
173
|
+
},
|
|
174
|
+
"skill": {
|
|
175
|
+
"type": "string"
|
|
176
|
+
},
|
|
177
|
+
"with": {
|
|
178
|
+
"type": "string",
|
|
179
|
+
"description": "The arguments of the skill."
|
|
180
|
+
},
|
|
181
|
+
"prompt": {
|
|
182
|
+
"type": "string"
|
|
183
|
+
},
|
|
184
|
+
"prompt-file": {
|
|
185
|
+
"$ref": "#/definitions/promptFile"
|
|
186
|
+
},
|
|
187
|
+
"output": {
|
|
188
|
+
"$ref": "#/definitions/outputSchema"
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
},
|
|
192
|
+
"promptStep": {
|
|
193
|
+
"type": "object",
|
|
194
|
+
"description": "The agent follows the instructions.",
|
|
195
|
+
"required": [
|
|
196
|
+
"id"
|
|
197
|
+
],
|
|
198
|
+
"oneOf": [
|
|
199
|
+
{
|
|
200
|
+
"required": [
|
|
201
|
+
"prompt"
|
|
202
|
+
]
|
|
203
|
+
},
|
|
204
|
+
{
|
|
205
|
+
"required": [
|
|
206
|
+
"prompt-file"
|
|
207
|
+
]
|
|
208
|
+
}
|
|
209
|
+
],
|
|
210
|
+
"additionalProperties": false,
|
|
211
|
+
"properties": {
|
|
212
|
+
"id": {
|
|
213
|
+
"$ref": "#/definitions/id"
|
|
214
|
+
},
|
|
215
|
+
"if": {
|
|
216
|
+
"$ref": "#/definitions/if"
|
|
217
|
+
},
|
|
218
|
+
"prompt": {
|
|
219
|
+
"type": "string"
|
|
220
|
+
},
|
|
221
|
+
"prompt-file": {
|
|
222
|
+
"$ref": "#/definitions/promptFile"
|
|
223
|
+
},
|
|
224
|
+
"output": {
|
|
225
|
+
"$ref": "#/definitions/outputSchema"
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
},
|
|
229
|
+
"askStep": {
|
|
230
|
+
"type": "object",
|
|
231
|
+
"description": "The agent asks the user one or more multiple-choice questions.",
|
|
232
|
+
"required": [
|
|
233
|
+
"id",
|
|
234
|
+
"ask"
|
|
235
|
+
],
|
|
236
|
+
"additionalProperties": false,
|
|
237
|
+
"properties": {
|
|
238
|
+
"id": {
|
|
239
|
+
"$ref": "#/definitions/id"
|
|
240
|
+
},
|
|
241
|
+
"if": {
|
|
242
|
+
"$ref": "#/definitions/if"
|
|
243
|
+
},
|
|
244
|
+
"ask": {
|
|
245
|
+
"type": "array",
|
|
246
|
+
"minItems": 1,
|
|
247
|
+
"items": {
|
|
248
|
+
"$ref": "#/definitions/question"
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
},
|
|
253
|
+
"stopStep": {
|
|
254
|
+
"type": "object",
|
|
255
|
+
"description": "The runner ends the flow with a message.",
|
|
256
|
+
"required": [
|
|
257
|
+
"stop"
|
|
258
|
+
],
|
|
259
|
+
"additionalProperties": false,
|
|
260
|
+
"properties": {
|
|
261
|
+
"id": {
|
|
262
|
+
"$ref": "#/definitions/id"
|
|
263
|
+
},
|
|
264
|
+
"if": {
|
|
265
|
+
"$ref": "#/definitions/if"
|
|
266
|
+
},
|
|
267
|
+
"stop": {
|
|
268
|
+
"type": "string"
|
|
269
|
+
},
|
|
270
|
+
"outcome": {
|
|
271
|
+
"enum": [
|
|
272
|
+
"success",
|
|
273
|
+
"failure"
|
|
274
|
+
]
|
|
275
|
+
}
|
|
276
|
+
}
|
|
277
|
+
},
|
|
278
|
+
"question": {
|
|
279
|
+
"type": "object",
|
|
280
|
+
"required": [
|
|
281
|
+
"id",
|
|
282
|
+
"question",
|
|
283
|
+
"header"
|
|
284
|
+
],
|
|
285
|
+
"additionalProperties": false,
|
|
286
|
+
"properties": {
|
|
287
|
+
"id": {
|
|
288
|
+
"$ref": "#/definitions/id"
|
|
289
|
+
},
|
|
290
|
+
"if": {
|
|
291
|
+
"$ref": "#/definitions/if"
|
|
292
|
+
},
|
|
293
|
+
"question": {
|
|
294
|
+
"type": "string"
|
|
295
|
+
},
|
|
296
|
+
"header": {
|
|
297
|
+
"type": "string",
|
|
298
|
+
"maxLength": 12
|
|
299
|
+
},
|
|
300
|
+
"multiSelect": {
|
|
301
|
+
"type": "boolean"
|
|
302
|
+
},
|
|
303
|
+
"options": {
|
|
304
|
+
"type": "array",
|
|
305
|
+
"minItems": 1,
|
|
306
|
+
"items": {
|
|
307
|
+
"oneOf": [
|
|
308
|
+
{
|
|
309
|
+
"type": "object",
|
|
310
|
+
"required": [
|
|
311
|
+
"label",
|
|
312
|
+
"description"
|
|
313
|
+
],
|
|
314
|
+
"additionalProperties": false,
|
|
315
|
+
"properties": {
|
|
316
|
+
"label": {
|
|
317
|
+
"type": "string"
|
|
318
|
+
},
|
|
319
|
+
"description": {
|
|
320
|
+
"type": "string"
|
|
321
|
+
},
|
|
322
|
+
"preview": {
|
|
323
|
+
"type": "string",
|
|
324
|
+
"description": "Text that the question tool shows next to the option, for example a draft to approve."
|
|
325
|
+
}
|
|
326
|
+
}
|
|
327
|
+
},
|
|
328
|
+
{
|
|
329
|
+
"type": "string",
|
|
330
|
+
"pattern": "^\\s*\\$\\{\\{[\\s\\S]*\\}\\}\\s*$",
|
|
331
|
+
"description": "An expression that gives a list of { label, description } options."
|
|
332
|
+
}
|
|
333
|
+
]
|
|
334
|
+
}
|
|
335
|
+
},
|
|
336
|
+
"free": {
|
|
337
|
+
"type": "boolean",
|
|
338
|
+
"description": "The user answers with free text. Options are then optional suggestions."
|
|
339
|
+
}
|
|
340
|
+
},
|
|
341
|
+
"anyOf": [
|
|
342
|
+
{
|
|
343
|
+
"required": [
|
|
344
|
+
"options"
|
|
345
|
+
]
|
|
346
|
+
},
|
|
347
|
+
{
|
|
348
|
+
"required": [
|
|
349
|
+
"free"
|
|
350
|
+
],
|
|
351
|
+
"properties": {
|
|
352
|
+
"free": {
|
|
353
|
+
"const": true
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
}
|
|
357
|
+
]
|
|
358
|
+
},
|
|
359
|
+
"foreachStep": {
|
|
360
|
+
"type": "object",
|
|
361
|
+
"description": "Runs the steps once for each item of a list. Inside, item is the current item and loop.index its position.",
|
|
362
|
+
"required": [
|
|
363
|
+
"id",
|
|
364
|
+
"foreach",
|
|
365
|
+
"steps"
|
|
366
|
+
],
|
|
367
|
+
"additionalProperties": false,
|
|
368
|
+
"properties": {
|
|
369
|
+
"id": {
|
|
370
|
+
"$ref": "#/definitions/id"
|
|
371
|
+
},
|
|
372
|
+
"if": {
|
|
373
|
+
"$ref": "#/definitions/if"
|
|
374
|
+
},
|
|
375
|
+
"foreach": {
|
|
376
|
+
"type": [
|
|
377
|
+
"string",
|
|
378
|
+
"array"
|
|
379
|
+
],
|
|
380
|
+
"description": "A ${{ }} expression that gives a list, or a list."
|
|
381
|
+
},
|
|
382
|
+
"steps": {
|
|
383
|
+
"type": "array",
|
|
384
|
+
"minItems": 1,
|
|
385
|
+
"items": {
|
|
386
|
+
"$ref": "#/definitions/step"
|
|
387
|
+
}
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
},
|
|
391
|
+
"usesStep": {
|
|
392
|
+
"type": "object",
|
|
393
|
+
"description": "Runs another flow as one step. Its stop message and status become the outputs of this step.",
|
|
394
|
+
"required": [
|
|
395
|
+
"id",
|
|
396
|
+
"uses"
|
|
397
|
+
],
|
|
398
|
+
"additionalProperties": false,
|
|
399
|
+
"properties": {
|
|
400
|
+
"id": {
|
|
401
|
+
"$ref": "#/definitions/id"
|
|
402
|
+
},
|
|
403
|
+
"if": {
|
|
404
|
+
"$ref": "#/definitions/if"
|
|
405
|
+
},
|
|
406
|
+
"uses": {
|
|
407
|
+
"type": "string",
|
|
408
|
+
"description": "The flow file, relative to this flow file."
|
|
409
|
+
},
|
|
410
|
+
"with": {
|
|
411
|
+
"type": "object",
|
|
412
|
+
"description": "The inputs of the other flow. Values can be ${{ }} expressions."
|
|
413
|
+
},
|
|
414
|
+
"continue-on-error": {
|
|
415
|
+
"type": "boolean",
|
|
416
|
+
"description": "Go on when the other flow fails."
|
|
417
|
+
}
|
|
418
|
+
}
|
|
419
|
+
},
|
|
420
|
+
"breakStep": {
|
|
421
|
+
"type": "object",
|
|
422
|
+
"description": "Ends the innermost foreach. The flow goes on after it.",
|
|
423
|
+
"required": [
|
|
424
|
+
"break"
|
|
425
|
+
],
|
|
426
|
+
"additionalProperties": false,
|
|
427
|
+
"properties": {
|
|
428
|
+
"id": {
|
|
429
|
+
"$ref": "#/definitions/id"
|
|
430
|
+
},
|
|
431
|
+
"if": {
|
|
432
|
+
"$ref": "#/definitions/if"
|
|
433
|
+
},
|
|
434
|
+
"break": {
|
|
435
|
+
"const": true
|
|
436
|
+
}
|
|
437
|
+
}
|
|
438
|
+
}
|
|
439
|
+
}
|
|
440
|
+
}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: create-skill-rails
|
|
3
|
+
description: "Create a new agent skill as a skill-rails flow: flow.yaml, scripts and prompt files, with the deterministic parts in code and only the judgment in agent steps. Use when asked to create, write or design a new skill with skill-rails."
|
|
4
|
+
argument-hint: "<what the skill does>"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Create a skill with skill-rails
|
|
8
|
+
|
|
9
|
+
Writes a new skill folder: `SKILL.md`, `flow.yaml`, `scripts/` and `prompts/`.
|
|
10
|
+
Read `${CLAUDE_SKILL_DIR}/../../docs/format.md` first: it is the reference of the flow format.
|
|
11
|
+
|
|
12
|
+
## Step 1: Understand the skill
|
|
13
|
+
|
|
14
|
+
Get these answers from the request.
|
|
15
|
+
Ask the user only for the ones that it does not give:
|
|
16
|
+
|
|
17
|
+
- what the skill does, its inputs, and its result;
|
|
18
|
+
- whether it runs with a user (it can ask questions) or unattended (it never asks);
|
|
19
|
+
- the tools and other skills that it uses;
|
|
20
|
+
- where to write it (for example `.claude/skills/<name>/` or a plugin `skills/` folder).
|
|
21
|
+
|
|
22
|
+
## Step 2: Design the steps
|
|
23
|
+
|
|
24
|
+
List the steps of the work in order, then give each one a type:
|
|
25
|
+
|
|
26
|
+
| The step | Type |
|
|
27
|
+
|----------|------|
|
|
28
|
+
| Gives the same result each time: git, gh, file operations, checks, formatting, API calls | `run`, with a script in `scripts/` |
|
|
29
|
+
| Needs judgment: write, analyze, choose, fix | `prompt`, with an `output` schema for the values that later steps use |
|
|
30
|
+
| Needs a decision from the user | `ask`, only in an interactive skill |
|
|
31
|
+
| Calls another skill | `skill`; when that skill only runs a script, call the script in a `run` step |
|
|
32
|
+
| Ends the run on a condition (a gate) | `stop` with `if:` and `outcome: failure` |
|
|
33
|
+
|
|
34
|
+
Then make the agent work small, because each agent step costs 2 to 3 model turns:
|
|
35
|
+
|
|
36
|
+
- Merge agent steps that follow each other into one `prompt` step.
|
|
37
|
+
- Move the fixed rules that a prompt needs (a format, a checklist) into one Markdown file that the prompt names, so that the agent reads only what it needs.
|
|
38
|
+
- Prepare the inputs of an agent step in a `run` step before it: collect the context into outputs or into one file.
|
|
39
|
+
- Do the checks after an agent step in a `run` step (lint, length, format), with a short fix prompt that runs only when the check fails.
|
|
40
|
+
|
|
41
|
+
Show the design to the user as a table of steps (id, type, what it does) before you write files, unless the run is unattended.
|
|
42
|
+
|
|
43
|
+
## Step 3: Write the files
|
|
44
|
+
|
|
45
|
+
- `flow.yaml`: the order, the conditions and the inputs only.
|
|
46
|
+
Use `run: <script>.sh` and `prompt-file: prompts/<id>.md`.
|
|
47
|
+
- `scripts/<name>.sh`: start with `#!/usr/bin/env bash` and `set -eo pipefail`.
|
|
48
|
+
Write outputs to `$FLOW_OUTPUT` as `key=value`, or `key<<EOF` ... `EOF` for several lines.
|
|
49
|
+
Print `::warning::<text>` for a message to the user.
|
|
50
|
+
Make each script executable.
|
|
51
|
+
- `prompts/<id>.md`: the instructions, with `${{ }}` for the values of earlier steps.
|
|
52
|
+
- `SKILL.md`: copy `${CLAUDE_SKILL_DIR}/template/SKILL.md` and fill the name, the description and the inputs.
|
|
53
|
+
|
|
54
|
+
Rules:
|
|
55
|
+
|
|
56
|
+
- Never put `${{ }}` in a `run` command: pass the values with `env`. The check refuses it, because a value can hold shell code.
|
|
57
|
+
- Give every `ask` option a `label` and a `description`.
|
|
58
|
+
- Keep each `output` schema to the values that later steps or the final message use.
|
|
59
|
+
|
|
60
|
+
## Step 4: Check
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
npx -y skill-rails@0.2 check <skill folder>/flow.yaml
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Fix each error.
|
|
67
|
+
Then run the flow once in a safe place, for example a copy of the repository, before a real run.
|
|
68
|
+
Do not run a step that publishes something (push, PR, message) during a test.
|
|
69
|
+
|
|
70
|
+
## Step 5: Report
|
|
71
|
+
|
|
72
|
+
Give the user the file list, the table of steps, and how many steps run in code and how many the agent does.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: <skill-name>
|
|
3
|
+
description: "<What the skill does, and when to use it.>"
|
|
4
|
+
allowed-tools: Bash, Read, Edit, Write
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# <Skill title>
|
|
8
|
+
|
|
9
|
+
This skill runs `flow.yaml` with skill-rails.
|
|
10
|
+
Run the flow with the `run-skill-rails` skill, or follow these steps.
|
|
11
|
+
|
|
12
|
+
1. Start the flow:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npx -y skill-rails@0.2 start "${CLAUDE_SKILL_DIR}/flow.yaml" [--input <key>=<value> ...]
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
2. Act on the `status` of each result:
|
|
19
|
+
- `step` → do the step, then run `npx -y skill-rails@0.2 done <flow> <id> --output - <<'JSON' ... JSON` with an output that matches `output`.
|
|
20
|
+
For a `skill` step, invoke the skill with `args` first.
|
|
21
|
+
For an `ask` step, ask the `questions` as they are, and report one property per question id.
|
|
22
|
+
- `invalid` → correct the output and run `done` again.
|
|
23
|
+
- `done`, `failed` or `error` → tell the user `message` or `errors`, and stop.
|
|
24
|
+
3. Do only the step that the runner gives you, and never run the shell steps of the flow yourself.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: migrate-to-skill-rails
|
|
3
|
+
description: "Migrate an existing Markdown skill (SKILL.md) to a skill-rails flow: move the deterministic steps to scripts that the runner executes, keep only the judgment in agent steps, and compare the two versions. Use when asked to migrate, convert or port a skill to skill-rails."
|
|
4
|
+
argument-hint: "<path of the skill folder or SKILL.md>"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Migrate a skill to skill-rails
|
|
8
|
+
|
|
9
|
+
Turns a Markdown skill into a flow skill, next to the original: `<name>-flow/` with `SKILL.md`, `flow.yaml`, `scripts/` and `prompts/`.
|
|
10
|
+
Keep the original skill until the comparison in Step 6 shows that the flow gives the same result.
|
|
11
|
+
Read `${CLAUDE_SKILL_DIR}/../../docs/format.md` first: it is the reference of the flow format.
|
|
12
|
+
|
|
13
|
+
## Step 1: Read the skill
|
|
14
|
+
|
|
15
|
+
Read the `SKILL.md`, every file that it loads (mode files, templates, rule files), and every script that it runs.
|
|
16
|
+
Also read the skills that it invokes, because their steps may move into the flow.
|
|
17
|
+
|
|
18
|
+
## Step 2: List the steps
|
|
19
|
+
|
|
20
|
+
Make a table with one row for each step of the skill, in order, with:
|
|
21
|
+
|
|
22
|
+
- what it does;
|
|
23
|
+
- what it reads, and what later steps use from it;
|
|
24
|
+
- its conditions and its gates (the "stop when" and "skip when" rules);
|
|
25
|
+
- its type in the flow:
|
|
26
|
+
|
|
27
|
+
| The step | Type |
|
|
28
|
+
|----------|------|
|
|
29
|
+
| A shell command, an API call, a file copy, a check, a format rule that code can apply | `run` (script) |
|
|
30
|
+
| Judgment: write, analyze, select, fix | `prompt` |
|
|
31
|
+
| A question to the user | `ask` (an unattended skill has none) |
|
|
32
|
+
| A call to another skill | `skill`, or a `run` step that calls its script when that skill only runs a script |
|
|
33
|
+
| A gate | `stop` with `if:` |
|
|
34
|
+
|
|
35
|
+
A Markdown step often mixes types.
|
|
36
|
+
Split it: for example, "copy the template, then fill it" is a `run` step and a `prompt` step.
|
|
37
|
+
|
|
38
|
+
## Step 3: Make the agent work small
|
|
39
|
+
|
|
40
|
+
Each agent step costs 2 to 3 model turns, and the runner does `run` steps with no model.
|
|
41
|
+
These changes gave the largest gains in practice:
|
|
42
|
+
|
|
43
|
+
1. Call the scripts of other skills directly in `run` steps, in place of loading those skills.
|
|
44
|
+
2. Collect the inputs of the research in one `run` step (one file or a few outputs), so that the agent does not run many commands.
|
|
45
|
+
3. Merge agent steps that follow each other into one `prompt` step.
|
|
46
|
+
4. Move the long fixed rules into a separate Markdown file that the prompt names, and keep only the rules that the step needs.
|
|
47
|
+
Do not make the agent read the whole original skill.
|
|
48
|
+
5. Do the checks in a `run` step after the agent step, with a fix prompt that runs only when the check fails.
|
|
49
|
+
6. Write the final report or message in a `run` step from the step outputs, when it has a fixed format.
|
|
50
|
+
|
|
51
|
+
Keep the behavior: every gate, every condition and every rule of the original skill must be in the flow, in a script, or in a prompt file.
|
|
52
|
+
Make a list of each rule of the original skill and where it went.
|
|
53
|
+
|
|
54
|
+
## Step 4: Write the files
|
|
55
|
+
|
|
56
|
+
Follow Step 3 of the `create-skill-rails` skill for the file rules.
|
|
57
|
+
Never put `${{ }}` in a `run` command: pass the values with `env`.
|
|
58
|
+
|
|
59
|
+
## Step 5: Check
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npx -y skill-rails@0.2 check <name>-flow/flow.yaml
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Then run the flow once in a safe place, for example a copy of the repository with a local remote, before a real run.
|
|
66
|
+
Do not run a step that publishes something (push, PR, message) during a test.
|
|
67
|
+
|
|
68
|
+
## Step 6: Compare
|
|
69
|
+
|
|
70
|
+
Compare the two versions on the same input, when the user agrees to the cost.
|
|
71
|
+
A headless run gives the numbers:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
claude -p "/<plugin>:<skill> <args>" --output-format json --no-session-persistence --settings '{"disableAllHooks": true}' --strict-mcp-config
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Run each version at least 3 times, in a copy of the repository, and compare the result (the files or the PR), the duration, the turns, the tokens and the cost.
|
|
78
|
+
Give the user the table, the rule list from Step 3, and the differences in the result.
|