@terra-symposium/skills 0.1.0 → 0.1.1
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/bin/terra-skills.mjs +14 -6
- package/dist/docs/authoring.md +1 -1
- package/package.json +1 -1
- package/src/index.mjs +66 -28
package/bin/terra-skills.mjs
CHANGED
|
@@ -1,20 +1,28 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* packages/skills/bin/terra-skills.mjs
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/*//////////////////////////////////////////////////
|
|
7
|
+
IMPORTS
|
|
8
|
+
//////////////////////////////////////////////////*/
|
|
9
|
+
|
|
2
10
|
import console from 'node:console';
|
|
3
11
|
import process from 'node:process';
|
|
4
12
|
import { resolve } from 'node:path';
|
|
5
13
|
import { prepareSkills, checkSkills } from '../src/index.mjs';
|
|
6
14
|
|
|
7
|
-
const [
|
|
8
|
-
if (!['prepare', 'check'].includes(
|
|
15
|
+
const [cmd, rootArg] = process.argv.slice(2);
|
|
16
|
+
if (!['prepare', 'check'].includes(cmd) || process.argv.length > 4) {
|
|
9
17
|
console.error('Usage: terra-skills <prepare|check> [repository-root]');
|
|
10
18
|
process.exitCode = 2;
|
|
11
19
|
} else {
|
|
12
20
|
try {
|
|
13
21
|
const root = resolve(rootArg ?? process.cwd());
|
|
14
|
-
const result =
|
|
15
|
-
console.log(`${
|
|
16
|
-
} catch (
|
|
17
|
-
console.error(
|
|
22
|
+
const result = cmd === 'prepare' ? await prepareSkills(root) : await checkSkills(root);
|
|
23
|
+
console.log(`${cmd}: ${result.skills} skills, ${result.files} files`);
|
|
24
|
+
} catch (err) {
|
|
25
|
+
console.error(err.message);
|
|
18
26
|
process.exitCode = 1;
|
|
19
27
|
}
|
|
20
28
|
}
|
package/dist/docs/authoring.md
CHANGED
|
@@ -18,7 +18,7 @@ metadata:
|
|
|
18
18
|
---
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
Keep links to detailed Markdown references and required assets relative to the skill page. Put
|
|
21
|
+
Keep links to detailed Markdown references and required assets relative to the skill page. Put them in sibling `references/`, `assets/`, `examples/`, `scripts/`, or `agents/` folders; the compiler copies those folders into the generated skill bundle. `metadata.related-files` names existing repository files that establish the workflow. Use `[]` when there is no such file. Keep the body readable as raw Markdown; generated skills must not depend on Docs-only rendering.
|
|
22
22
|
|
|
23
23
|
Install `@terra-symposium/skills` as a development dependency, then run `terra-skills prepare` from the repository root. The command writes `.agents/skills/` for agent discovery. Run `terra-skills check` to compare that output with the Docs source without rewriting files. Preparation refuses to replace a hand-authored skill directory. Add `.agents/skills/` to Git ignore rules and rerun preparation after changing a skill page. Start a new agent session or refresh discovery after preparation.
|
|
24
24
|
|
package/package.json
CHANGED
package/src/index.mjs
CHANGED
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* packages/skills/src/index.mjs
|
|
3
|
+
*/
|
|
4
|
+
|
|
5
|
+
/*//////////////////////////////////////////////////
|
|
6
|
+
IMPORTS
|
|
7
|
+
//////////////////////////////////////////////////*/
|
|
8
|
+
|
|
1
9
|
import { Buffer } from 'node:buffer';
|
|
2
10
|
import { readFile, readdir, mkdir, rm, writeFile, stat } from 'node:fs/promises';
|
|
3
11
|
import { basename, dirname, extname, join, normalize, relative, resolve, sep } from 'node:path';
|
|
@@ -6,6 +14,11 @@ import { parse, stringify } from 'yaml';
|
|
|
6
14
|
const marker = '.terra-skills-generated';
|
|
7
15
|
const slug = /^[a-z][a-z0-9-]*$/;
|
|
8
16
|
|
|
17
|
+
/**
|
|
18
|
+
* Collect files recursively under a directory.
|
|
19
|
+
* @param root Directory to walk.
|
|
20
|
+
* @return Sorted file paths, or an empty list when the directory is missing.
|
|
21
|
+
*/
|
|
9
22
|
async function filesBelow(root) {
|
|
10
23
|
const found = [];
|
|
11
24
|
async function visit(dir) {
|
|
@@ -17,50 +30,68 @@ async function filesBelow(root) {
|
|
|
17
30
|
}
|
|
18
31
|
try {
|
|
19
32
|
await visit(root);
|
|
20
|
-
} catch (
|
|
21
|
-
if (
|
|
33
|
+
} catch (err) {
|
|
34
|
+
if (err.code !== 'ENOENT') throw err;
|
|
22
35
|
}
|
|
23
36
|
return found.sort();
|
|
24
37
|
}
|
|
25
38
|
|
|
26
|
-
|
|
27
|
-
|
|
39
|
+
/**
|
|
40
|
+
* Parse a marked Markdown page's YAML frontmatter.
|
|
41
|
+
* @param src Complete Markdown source.
|
|
42
|
+
* @param path Source path for diagnostics.
|
|
43
|
+
* @return Parsed metadata and Markdown body.
|
|
44
|
+
*/
|
|
45
|
+
function splitFrontmatter(src, path) {
|
|
46
|
+
const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(src);
|
|
28
47
|
if (!match) throw new Error(`Missing YAML frontmatter: ${path}`);
|
|
29
48
|
let fields;
|
|
30
49
|
try {
|
|
31
50
|
fields = parse(match[1], { uniqueKeys: true });
|
|
32
|
-
} catch (
|
|
33
|
-
throw new Error(`Invalid YAML frontmatter in ${path}: ${
|
|
51
|
+
} catch (err) {
|
|
52
|
+
throw new Error(`Invalid YAML frontmatter in ${path}: ${err.message}`, { cause: err });
|
|
34
53
|
}
|
|
35
54
|
if (!fields || typeof fields !== 'object' || Array.isArray(fields))
|
|
36
55
|
throw new Error(`Invalid skill metadata: ${path}`);
|
|
37
|
-
return { fields, body:
|
|
56
|
+
return { fields, body: src.slice(match[0].length) };
|
|
38
57
|
}
|
|
39
58
|
|
|
40
|
-
|
|
59
|
+
/**
|
|
60
|
+
* Reject broken relative links in the portable skill bundle.
|
|
61
|
+
* @param contents Markdown content to inspect.
|
|
62
|
+
* @param file Generated relative path.
|
|
63
|
+
* @param expected Compiled file map.
|
|
64
|
+
* @return Nothing; throws when a link cannot resolve.
|
|
65
|
+
*/
|
|
66
|
+
function validLinks(contents, file, expected) {
|
|
41
67
|
const withoutFences = contents.replace(/```[\s\S]*?```/g, '');
|
|
42
68
|
for (const match of withoutFences.matchAll(/!?\[[^\]]*\]\(([^)]+)\)/g)) {
|
|
43
69
|
const target = match[1].split('#', 1)[0];
|
|
44
70
|
if (!target || /^(?:[a-z][\w+.-]*:|\/)/i.test(target)) continue;
|
|
45
|
-
const
|
|
46
|
-
if (
|
|
71
|
+
const dest = normalize(join(dirname(file), decodeURIComponent(target)));
|
|
72
|
+
if (dest === '..' || dest.startsWith(`..${sep}`))
|
|
47
73
|
throw new Error(`Skill link escapes generated skills: ${file} -> ${target}`);
|
|
48
|
-
if (!expected.has(
|
|
74
|
+
if (!expected.has(dest)) throw new Error(`Broken skill link: ${file} -> ${target}`);
|
|
49
75
|
}
|
|
50
76
|
}
|
|
51
77
|
|
|
52
|
-
/**
|
|
78
|
+
/**
|
|
79
|
+
* Compile marked Docs skill pages into a portable file map.
|
|
80
|
+
* @param root Repository root.
|
|
81
|
+
* @return Number of skills and their generated file map.
|
|
82
|
+
*/
|
|
53
83
|
export async function compileSkills(root) {
|
|
54
84
|
const repo = resolve(root);
|
|
55
|
-
const
|
|
56
|
-
|
|
85
|
+
const pages = (await filesBelow(join(repo, 'docs'))).filter(
|
|
86
|
+
(file) => basename(file) === 'SKILL.md',
|
|
87
|
+
);
|
|
57
88
|
const expected = new Map();
|
|
58
89
|
const names = new Set();
|
|
59
90
|
for (const page of pages) {
|
|
60
91
|
const { fields, body } = splitFrontmatter(await readFile(page, 'utf8'), page);
|
|
61
92
|
if (fields.skill !== true) continue;
|
|
62
|
-
const { name, description } = fields;
|
|
63
|
-
if (!slug.test(name ?? '') || typeof
|
|
93
|
+
const { name, description: desc } = fields;
|
|
94
|
+
if (!slug.test(name ?? '') || typeof desc !== 'string' || !desc.trim()) {
|
|
64
95
|
throw new Error(`Skill needs a slug name and description: ${page}`);
|
|
65
96
|
}
|
|
66
97
|
if (names.has(name)) throw new Error(`Duplicate skill name: ${name}`);
|
|
@@ -83,10 +114,9 @@ export async function compileSkills(root) {
|
|
|
83
114
|
for (const file of await filesBelow(dirname(page))) {
|
|
84
115
|
if (file === page) continue;
|
|
85
116
|
const local = relative(dirname(page), file);
|
|
86
|
-
const first = local.split(sep)[0];
|
|
87
117
|
if (
|
|
88
118
|
!['agents', 'assets', 'examples', 'references', 'scripts', 'README.template.md'].includes(
|
|
89
|
-
|
|
119
|
+
local.split(sep)[0],
|
|
90
120
|
)
|
|
91
121
|
)
|
|
92
122
|
continue;
|
|
@@ -94,12 +124,16 @@ export async function compileSkills(root) {
|
|
|
94
124
|
}
|
|
95
125
|
}
|
|
96
126
|
for (const [file, content] of expected) {
|
|
97
|
-
if (extname(file) === '.md')
|
|
127
|
+
if (extname(file) === '.md') validLinks(String(content), file, expected);
|
|
98
128
|
}
|
|
99
129
|
return { skills: names.size, files: expected };
|
|
100
130
|
}
|
|
101
131
|
|
|
102
|
-
/**
|
|
132
|
+
/**
|
|
133
|
+
* Write compiled skills to the repository discovery directory.
|
|
134
|
+
* @param root Repository root.
|
|
135
|
+
* @return Number of written skills and files.
|
|
136
|
+
*/
|
|
103
137
|
export async function prepareSkills(root) {
|
|
104
138
|
const repo = resolve(root);
|
|
105
139
|
const out = join(repo, '.agents', 'skills');
|
|
@@ -108,8 +142,8 @@ export async function prepareSkills(root) {
|
|
|
108
142
|
const entries = await readdir(out);
|
|
109
143
|
if (entries.length && !entries.includes(marker))
|
|
110
144
|
throw new Error(`Refusing to replace non-generated skills: ${out}`);
|
|
111
|
-
} catch (
|
|
112
|
-
if (
|
|
145
|
+
} catch (err) {
|
|
146
|
+
if (err.code !== 'ENOENT') throw err;
|
|
113
147
|
}
|
|
114
148
|
await rm(out, { recursive: true, force: true });
|
|
115
149
|
await mkdir(out, { recursive: true });
|
|
@@ -122,7 +156,11 @@ export async function prepareSkills(root) {
|
|
|
122
156
|
return { skills: compiled.skills, files: compiled.files.size };
|
|
123
157
|
}
|
|
124
158
|
|
|
125
|
-
/**
|
|
159
|
+
/**
|
|
160
|
+
* Compare generated discovery files with Docs without changing the repository.
|
|
161
|
+
* @param root Repository root.
|
|
162
|
+
* @return Number of checked skills and files.
|
|
163
|
+
*/
|
|
126
164
|
export async function checkSkills(root) {
|
|
127
165
|
const repo = resolve(root);
|
|
128
166
|
const out = join(repo, '.agents', 'skills');
|
|
@@ -131,16 +169,16 @@ export async function checkSkills(root) {
|
|
|
131
169
|
.map((file) => relative(out, file))
|
|
132
170
|
.filter((file) => file !== marker);
|
|
133
171
|
const expected = [...compiled.files.keys()];
|
|
134
|
-
const
|
|
172
|
+
const diffs = new Set([
|
|
135
173
|
...actual.filter((file) => !compiled.files.has(file)),
|
|
136
174
|
...expected.filter((file) => !actual.includes(file)),
|
|
137
175
|
]);
|
|
138
176
|
for (const file of expected) {
|
|
139
177
|
if (!actual.includes(file)) continue;
|
|
140
|
-
|
|
141
|
-
|
|
178
|
+
if (!(await readFile(join(out, file))).equals(Buffer.from(compiled.files.get(file))))
|
|
179
|
+
diffs.add(file);
|
|
142
180
|
}
|
|
143
|
-
if (
|
|
144
|
-
throw new Error(`Generated skills differ from Docs: ${[...
|
|
181
|
+
if (diffs.size)
|
|
182
|
+
throw new Error(`Generated skills differ from Docs: ${[...diffs].sort().join(', ')}`);
|
|
145
183
|
return { skills: compiled.skills, files: compiled.files.size };
|
|
146
184
|
}
|