Skip to content

Commit 72bff79

Browse files
salim4ncursoragent
andauthored
docs(skills): make skill folders copyable as published units (#122)
Move executable examples next to each SKILL.md, drop internal SHA and unmerged-PR wording in favor of @ignitionai/* 0.1.0, and document the exact ONNX conversion prerequisites. Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Salim <salim4n@users.noreply.github.com>
1 parent cf6d42b commit 72bff79

42 files changed

Lines changed: 175 additions & 51 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎skills/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,21 +18,21 @@ Success is measured only with numbers you actually ran: CartPole training, evalu
1818
| ignition-export-onnx | Export a trained TF.js policy to ONNX using the published backend API. | `skills/ignition-export-onnx/` |
1919
| ignition-save-load | Persist and restore agent weights and runner-facing state. | `skills/ignition-save-load/` |
2020

21-
Start at **ignition-quickstart**. The other eight folders are specified in the same batch and may land in parallel pull requests.
21+
Start at **ignition-quickstart**. Copy any other skill folder you need.
2222

2323
## Conventions
2424

2525
- Location: `skills/ignition-<name>/SKILL.md`.
2626
- Frontmatter: `name` equals the folder name; `description` says what the skill does and when to use it (max 1024 characters). Body in English, max 500 lines; extra detail in `references/`.
27-
- API: only `dev` at SHA `343a76952f9dcd6594674c3526ee03ee45b4d93e`. Cite each signature as `file:line`.
28-
- Runnable example: `examples/*.ts` plus `examples/*.test.ts`, executed by the root Vitest config with `@ignitionai/*` aliases. Tests call the real framework (no mocks) and stay under 60 s CPU.
27+
- API: `@ignitionai/*` **0.1.0** only. Cite each signature as `file:line`.
28+
- Runnable example: `skills/ignition-<name>/examples/*.ts` plus matching `*.test.ts`, executed by the root Vitest config with `@ignitionai/*` aliases. Tests call the real framework (no mocks) and stay under 60 s CPU.
2929
- Declare budget and seeds (at least three) before running. Paste raw results, including failures. Never weaken an existing test.
3030

3131
## How to install a skill
3232

3333
There is no Ignition CLI that registers skills.
3434

35-
Copy a skill directory into the project's Agent Skills folder, keeping the folder name:
35+
Copy a skill directory into the project's Agent Skills folder, keeping the folder name (this includes `examples/` and `references/`):
3636

3737
```text
3838
cp -R skills/ignition-quickstart .claude/skills/ignition-quickstart

‎skills/check-relative-links.mjs‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
#!/usr/bin/env node
2+
/**
3+
* Verify markdown relative links in each skill folder stay inside that folder,
4+
* except links that resolve to packages/ (framework sources).
5+
*
6+
* Usage (from repo root): node skills/check-relative-links.mjs
7+
*/
8+
import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
9+
import { dirname, join, relative, resolve, sep } from 'node:path';
10+
import { fileURLToPath } from 'node:url';
11+
12+
const skillsRoot = dirname(fileURLToPath(import.meta.url));
13+
const repoRoot = resolve(skillsRoot, '..');
14+
const packagesRoot = join(repoRoot, 'packages');
15+
const LINK_RE = /\[([^\]]*)\]\(([^)]+)\)/g;
16+
17+
function isInside(child, parent) {
18+
const rel = relative(parent, child);
19+
return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !rel.startsWith('..'));
20+
}
21+
22+
function skillDirs() {
23+
return readdirSync(skillsRoot)
24+
.filter((name) => name.startsWith('ignition-'))
25+
.map((name) => join(skillsRoot, name))
26+
.filter((path) => statSync(path).isDirectory());
27+
}
28+
29+
function markdownFiles(skillDir) {
30+
const files = [join(skillDir, 'SKILL.md')];
31+
const refs = join(skillDir, 'references');
32+
if (existsSync(refs) && statSync(refs).isDirectory()) {
33+
for (const name of readdirSync(refs)) {
34+
if (name.endsWith('.md')) {
35+
files.push(join(refs, name));
36+
}
37+
}
38+
}
39+
return files.filter((file) => existsSync(file));
40+
}
41+
42+
let failed = false;
43+
let checked = 0;
44+
45+
for (const skillDir of skillDirs()) {
46+
const skillName = skillDir.split(sep).pop();
47+
for (const file of markdownFiles(skillDir)) {
48+
const text = readFileSync(file, 'utf8');
49+
const matches = [...text.matchAll(LINK_RE)];
50+
if (matches.length === 0) {
51+
process.stdout.write(`OK ${skillName}/${relative(skillDir, file)} (no markdown links)\n`);
52+
continue;
53+
}
54+
for (const match of matches) {
55+
let href = match[2].trim().replace(/\s+"[^"]*"$/, '').replace(/\s+'[^']*'$/, '');
56+
if (
57+
href === '' ||
58+
href.startsWith('#') ||
59+
href.startsWith('http://') ||
60+
href.startsWith('https://') ||
61+
href.startsWith('mailto:')
62+
) {
63+
process.stdout.write(`OK ${skillName}/${relative(skillDir, file)} -> ${href}\n`);
64+
checked += 1;
65+
continue;
66+
}
67+
const pathPart = href.split('#')[0];
68+
if (pathPart === '') {
69+
process.stdout.write(`OK ${skillName}/${relative(skillDir, file)} -> ${href}\n`);
70+
checked += 1;
71+
continue;
72+
}
73+
const resolved = resolve(dirname(file), pathPart);
74+
const relFile = `${skillName}/${relative(skillDir, file)}`;
75+
if (isInside(resolved, skillDir)) {
76+
if (!existsSync(resolved)) {
77+
process.stdout.write(`FAIL ${relFile} -> ${href} (missing in-skill target)\n`);
78+
failed = true;
79+
} else {
80+
process.stdout.write(`OK ${relFile} -> ${href}\n`);
81+
}
82+
checked += 1;
83+
continue;
84+
}
85+
if (isInside(resolved, packagesRoot)) {
86+
process.stdout.write(`OK ${relFile} -> ${href} (framework source)\n`);
87+
checked += 1;
88+
continue;
89+
}
90+
process.stdout.write(
91+
`FAIL ${relFile} -> ${href} leaves skill folder (${relative(repoRoot, resolved)})\n`,
92+
);
93+
failed = true;
94+
checked += 1;
95+
}
96+
}
97+
}
98+
99+
process.stdout.write(`checked=${checked} failed=${failed ? 'yes' : 'no'}\n`);
100+
process.exit(failed ? 1 : 0);

‎skills/ignition-create-env/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: Use when writing, validating, or wrapping a custom IgnitionRL Train
66
# ignition-create-env
77

88
Teach an agent how to write a custom environment that matches the framework
9-
contract on `dev` at SHA `343a76952f9dcd6594674c3526ee03ee45b4d93e`.
9+
contract for `@ignitionai/*` **0.1.0**.
1010

1111
Executable example: `examples/skill-create-env.ts` (tests in
1212
`examples/skill-create-env.test.ts`). Full signatures:

examples/skill-create-env.test.ts renamed to skills/ignition-create-env/examples/skill-create-env.test.ts

File renamed without changes.

examples/skill-create-env.ts renamed to skills/ignition-create-env/examples/skill-create-env.ts

File renamed without changes.

‎skills/ignition-create-env/references/env-contract.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# TrainingEnv contract (dev SHA 343a769)
1+
# TrainingEnv contract (`@ignitionai/*` 0.1.0)
22

3-
Signatures below are from this checkout. Do not copy APIs from unmerged PRs.
3+
Signatures below are from the published 0.1.0 API.
44

55
## Spaces (`packages/core/src/types.ts`)
66

‎skills/ignition-debug-training/SKILL.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ Use this abbreviated map. Details and citations: [references/symptom-table.md](r
6060

6161
## TensorFlow.js hygiene
6262

63-
- `DQNAgent.train` builds the Bellman batch inside `tf.tidy` and `tf.dispose`s the fit tensors in `finally`.
63+
- `DQNAgent.train` builds the Bellman update inside `tf.tidy` and `tf.dispose`s the fit tensors in `finally`.
6464
- `DQNAgent.getAction` disposes `stateTensor`, `qValues`, and `argMaxTensor`.
6565
- `PPOAgent.train` wraps gradient work in `tf.tidy`.
6666
- After warmup (replay at `batchSize`), `tf.memory().numTensors` must stay **flat** across N further `env.step()` calls. If it climbs, the leak is in **your** probe code or a custom env, until proven otherwise.
@@ -91,7 +91,7 @@ Shared budget (all protocols): seeds `7`, `11`, `19`; `64` steps; `hiddenLayers:
9191

9292
## Do not
9393

94-
- Do not use APIs from unmerged PRs.
94+
- Do not use unpublished APIs.
9595
- Do not mock `IgnitionEnvTFJS`, `DQNAgent`, or `CartPoleEnv`.
9696
- Do not skip a failing seed.
97-
- Do not “fix” `@ignitionai/*` in this skill’s PR. Report gaps instead.
97+
- Do not patch `@ignitionai/*` while using this skill. Report gaps instead.

examples/skill-debug-training.test.ts renamed to skills/ignition-debug-training/examples/skill-debug-training.test.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ describe('skill ignition-debug-training', () => {
5353
describe('skills/ignition-debug-training frontmatter', () => {
5454
it('has name = folder, description <= 1024, body <= 500 lines', () => {
5555
const raw = readFileSync(
56-
resolve(__dirname, '../skills/ignition-debug-training/SKILL.md'),
56+
resolve(__dirname, '../SKILL.md'),
5757
'utf8',
5858
);
5959
expect(raw.startsWith('---\n')).toBe(true);

examples/skill-debug-training.ts renamed to skills/ignition-debug-training/examples/skill-debug-training.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ import { CartPoleEnv } from '@ignitionai/environments';
3939
import { DQNAgent, IgnitionEnvTFJS } from '@ignitionai/backend-tfjs';
4040
import type { TrainingEnv } from '@ignitionai/core';
4141
// Root vitest aliases @ignitionai/* only. Resolve TF.js from the backend workspace package.
42-
import * as tf from '../packages/backend-tfjs/node_modules/@tensorflow/tfjs';
42+
import * as tf from '../../../packages/backend-tfjs/node_modules/@tensorflow/tfjs';
4343

4444
export const SEEDS = [7, 11, 19] as const;
4545
export const TRAIN_STEPS = 64;

‎skills/ignition-debug-training/references/symptom-table.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Symptom table (IgnitionRL on `dev` SHA `343a76952f9dcd6594674c3526ee03ee45b4d93e`)
1+
# Symptom table (IgnitionRL, `@ignitionai/*` 0.1.0)
22

3-
Signatures are cited as `file:line` in the pull request. This file only names the symbols.
3+
Signatures are cited as `file:line`. This file only names the symbols.
44

55
## Flat reward
66

0 commit comments

Comments
 (0)