@terra-symposium/skills 0.0.0-stage → 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 +28 -0
- package/dist/docs/authoring.md +25 -0
- package/package.json +30 -4
- package/src/index.mjs +184 -0
- package/README.md +0 -3
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* packages/skills/bin/terra-skills.mjs
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/*//////////////////////////////////////////////////
|
|
7
|
+
IMPORTS
|
|
8
|
+
//////////////////////////////////////////////////*/
|
|
9
|
+
|
|
10
|
+
import console from 'node:console';
|
|
11
|
+
import process from 'node:process';
|
|
12
|
+
import { resolve } from 'node:path';
|
|
13
|
+
import { prepareSkills, checkSkills } from '../src/index.mjs';
|
|
14
|
+
|
|
15
|
+
const [cmd, rootArg] = process.argv.slice(2);
|
|
16
|
+
if (!['prepare', 'check'].includes(cmd) || process.argv.length > 4) {
|
|
17
|
+
console.error('Usage: terra-skills <prepare|check> [repository-root]');
|
|
18
|
+
process.exitCode = 2;
|
|
19
|
+
} else {
|
|
20
|
+
try {
|
|
21
|
+
const root = resolve(rootArg ?? process.cwd());
|
|
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);
|
|
26
|
+
process.exitCode = 1;
|
|
27
|
+
}
|
|
28
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Agent skill authoring
|
|
3
|
+
description: Author repository skills as Docs pages and compile them for agent discovery.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Agent skill authoring
|
|
7
|
+
|
|
8
|
+
Write each skill as one dedicated `docs/**/SKILL.md` page. Its Markdown body is the instruction source for agents and also appears on the Docs site. Add this frontmatter:
|
|
9
|
+
|
|
10
|
+
```yaml
|
|
11
|
+
---
|
|
12
|
+
name: example-skill
|
|
13
|
+
description: Use this skill for a specific repeatable task.
|
|
14
|
+
skill: true
|
|
15
|
+
metadata:
|
|
16
|
+
related-files:
|
|
17
|
+
- path/to/current/source.ts
|
|
18
|
+
---
|
|
19
|
+
```
|
|
20
|
+
|
|
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
|
+
|
|
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
|
+
|
|
25
|
+
The package also exports `compileSkills(root)`, `prepareSkills(root)`, and `checkSkills(root)` for build tooling. `@terra-symposium/skills/authoring.md` exports this guide for tools that need it without a running Docs site.
|
package/package.json
CHANGED
|
@@ -1,6 +1,32 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@terra-symposium/skills",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "Compile Docs-authored agent skills for repository and plugin discovery.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "Apache-2.0",
|
|
7
|
+
"engines": {
|
|
8
|
+
"node": ">=24.12.0"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"bin",
|
|
12
|
+
"src",
|
|
13
|
+
"dist/docs"
|
|
14
|
+
],
|
|
15
|
+
"bin": {
|
|
16
|
+
"terra-skills": "bin/terra-skills.mjs"
|
|
17
|
+
},
|
|
18
|
+
"exports": {
|
|
19
|
+
".": "./src/index.mjs",
|
|
20
|
+
"./authoring.md": "./dist/docs/authoring.md"
|
|
21
|
+
},
|
|
22
|
+
"scripts": {
|
|
23
|
+
"build": "node scripts/copy-docs.mjs",
|
|
24
|
+
"test": "node --test tests/*.test.mjs"
|
|
25
|
+
},
|
|
26
|
+
"dependencies": {
|
|
27
|
+
"yaml": "^2.7.0"
|
|
28
|
+
},
|
|
29
|
+
"publishConfig": {
|
|
30
|
+
"access": "public"
|
|
31
|
+
}
|
|
32
|
+
}
|
package/src/index.mjs
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* packages/skills/src/index.mjs
|
|
3
|
+
*/
|
|
4
|
+
|
|
5
|
+
/*//////////////////////////////////////////////////
|
|
6
|
+
IMPORTS
|
|
7
|
+
//////////////////////////////////////////////////*/
|
|
8
|
+
|
|
9
|
+
import { Buffer } from 'node:buffer';
|
|
10
|
+
import { readFile, readdir, mkdir, rm, writeFile, stat } from 'node:fs/promises';
|
|
11
|
+
import { basename, dirname, extname, join, normalize, relative, resolve, sep } from 'node:path';
|
|
12
|
+
import { parse, stringify } from 'yaml';
|
|
13
|
+
|
|
14
|
+
const marker = '.terra-skills-generated';
|
|
15
|
+
const slug = /^[a-z][a-z0-9-]*$/;
|
|
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
|
+
*/
|
|
22
|
+
async function filesBelow(root) {
|
|
23
|
+
const found = [];
|
|
24
|
+
async function visit(dir) {
|
|
25
|
+
for (const entry of await readdir(dir, { withFileTypes: true })) {
|
|
26
|
+
const path = join(dir, entry.name);
|
|
27
|
+
if (entry.isDirectory()) await visit(path);
|
|
28
|
+
else if (entry.isFile()) found.push(path);
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
try {
|
|
32
|
+
await visit(root);
|
|
33
|
+
} catch (err) {
|
|
34
|
+
if (err.code !== 'ENOENT') throw err;
|
|
35
|
+
}
|
|
36
|
+
return found.sort();
|
|
37
|
+
}
|
|
38
|
+
|
|
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);
|
|
47
|
+
if (!match) throw new Error(`Missing YAML frontmatter: ${path}`);
|
|
48
|
+
let fields;
|
|
49
|
+
try {
|
|
50
|
+
fields = parse(match[1], { uniqueKeys: true });
|
|
51
|
+
} catch (err) {
|
|
52
|
+
throw new Error(`Invalid YAML frontmatter in ${path}: ${err.message}`, { cause: err });
|
|
53
|
+
}
|
|
54
|
+
if (!fields || typeof fields !== 'object' || Array.isArray(fields))
|
|
55
|
+
throw new Error(`Invalid skill metadata: ${path}`);
|
|
56
|
+
return { fields, body: src.slice(match[0].length) };
|
|
57
|
+
}
|
|
58
|
+
|
|
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) {
|
|
67
|
+
const withoutFences = contents.replace(/```[\s\S]*?```/g, '');
|
|
68
|
+
for (const match of withoutFences.matchAll(/!?\[[^\]]*\]\(([^)]+)\)/g)) {
|
|
69
|
+
const target = match[1].split('#', 1)[0];
|
|
70
|
+
if (!target || /^(?:[a-z][\w+.-]*:|\/)/i.test(target)) continue;
|
|
71
|
+
const dest = normalize(join(dirname(file), decodeURIComponent(target)));
|
|
72
|
+
if (dest === '..' || dest.startsWith(`..${sep}`))
|
|
73
|
+
throw new Error(`Skill link escapes generated skills: ${file} -> ${target}`);
|
|
74
|
+
if (!expected.has(dest)) throw new Error(`Broken skill link: ${file} -> ${target}`);
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
|
|
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
|
+
*/
|
|
83
|
+
export async function compileSkills(root) {
|
|
84
|
+
const repo = resolve(root);
|
|
85
|
+
const pages = (await filesBelow(join(repo, 'docs'))).filter(
|
|
86
|
+
(file) => basename(file) === 'SKILL.md',
|
|
87
|
+
);
|
|
88
|
+
const expected = new Map();
|
|
89
|
+
const names = new Set();
|
|
90
|
+
for (const page of pages) {
|
|
91
|
+
const { fields, body } = splitFrontmatter(await readFile(page, 'utf8'), page);
|
|
92
|
+
if (fields.skill !== true) continue;
|
|
93
|
+
const { name, description: desc } = fields;
|
|
94
|
+
if (!slug.test(name ?? '') || typeof desc !== 'string' || !desc.trim()) {
|
|
95
|
+
throw new Error(`Skill needs a slug name and description: ${page}`);
|
|
96
|
+
}
|
|
97
|
+
if (names.has(name)) throw new Error(`Duplicate skill name: ${name}`);
|
|
98
|
+
names.add(name);
|
|
99
|
+
delete fields.skill;
|
|
100
|
+
delete fields.title;
|
|
101
|
+
if (!fields.metadata) fields.metadata = { 'related-files': [] };
|
|
102
|
+
const related = fields.metadata?.['related-files'];
|
|
103
|
+
if (!Array.isArray(related)) throw new Error(`Invalid related-files: ${page}`);
|
|
104
|
+
for (const path of related) {
|
|
105
|
+
if (typeof path !== 'string' || path.startsWith('/') || path.split('/').includes('..'))
|
|
106
|
+
throw new Error(`Invalid related file: ${page} -> ${path}`);
|
|
107
|
+
try {
|
|
108
|
+
if (!(await stat(join(repo, path))).isFile()) throw new Error();
|
|
109
|
+
} catch {
|
|
110
|
+
throw new Error(`Missing related file: ${page} -> ${path}`);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
expected.set(join(name, 'SKILL.md'), `---\n${stringify(fields).trimEnd()}\n---\n${body}`);
|
|
114
|
+
for (const file of await filesBelow(dirname(page))) {
|
|
115
|
+
if (file === page) continue;
|
|
116
|
+
const local = relative(dirname(page), file);
|
|
117
|
+
if (
|
|
118
|
+
!['agents', 'assets', 'examples', 'references', 'scripts', 'README.template.md'].includes(
|
|
119
|
+
local.split(sep)[0],
|
|
120
|
+
)
|
|
121
|
+
)
|
|
122
|
+
continue;
|
|
123
|
+
expected.set(join(name, local), await readFile(file));
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
for (const [file, content] of expected) {
|
|
127
|
+
if (extname(file) === '.md') validLinks(String(content), file, expected);
|
|
128
|
+
}
|
|
129
|
+
return { skills: names.size, files: expected };
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* Write compiled skills to the repository discovery directory.
|
|
134
|
+
* @param root Repository root.
|
|
135
|
+
* @return Number of written skills and files.
|
|
136
|
+
*/
|
|
137
|
+
export async function prepareSkills(root) {
|
|
138
|
+
const repo = resolve(root);
|
|
139
|
+
const out = join(repo, '.agents', 'skills');
|
|
140
|
+
const compiled = await compileSkills(repo);
|
|
141
|
+
try {
|
|
142
|
+
const entries = await readdir(out);
|
|
143
|
+
if (entries.length && !entries.includes(marker))
|
|
144
|
+
throw new Error(`Refusing to replace non-generated skills: ${out}`);
|
|
145
|
+
} catch (err) {
|
|
146
|
+
if (err.code !== 'ENOENT') throw err;
|
|
147
|
+
}
|
|
148
|
+
await rm(out, { recursive: true, force: true });
|
|
149
|
+
await mkdir(out, { recursive: true });
|
|
150
|
+
for (const [file, content] of compiled.files) {
|
|
151
|
+
const target = join(out, file);
|
|
152
|
+
await mkdir(dirname(target), { recursive: true });
|
|
153
|
+
await writeFile(target, content);
|
|
154
|
+
}
|
|
155
|
+
await writeFile(join(out, marker), 'Generated from docs/ by @terra-symposium/skills.\n');
|
|
156
|
+
return { skills: compiled.skills, files: compiled.files.size };
|
|
157
|
+
}
|
|
158
|
+
|
|
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
|
+
*/
|
|
164
|
+
export async function checkSkills(root) {
|
|
165
|
+
const repo = resolve(root);
|
|
166
|
+
const out = join(repo, '.agents', 'skills');
|
|
167
|
+
const compiled = await compileSkills(repo);
|
|
168
|
+
const actual = (await filesBelow(out))
|
|
169
|
+
.map((file) => relative(out, file))
|
|
170
|
+
.filter((file) => file !== marker);
|
|
171
|
+
const expected = [...compiled.files.keys()];
|
|
172
|
+
const diffs = new Set([
|
|
173
|
+
...actual.filter((file) => !compiled.files.has(file)),
|
|
174
|
+
...expected.filter((file) => !actual.includes(file)),
|
|
175
|
+
]);
|
|
176
|
+
for (const file of expected) {
|
|
177
|
+
if (!actual.includes(file)) continue;
|
|
178
|
+
if (!(await readFile(join(out, file))).equals(Buffer.from(compiled.files.get(file))))
|
|
179
|
+
diffs.add(file);
|
|
180
|
+
}
|
|
181
|
+
if (diffs.size)
|
|
182
|
+
throw new Error(`Generated skills differ from Docs: ${[...diffs].sort().join(', ')}`);
|
|
183
|
+
return { skills: compiled.skills, files: compiled.files.size };
|
|
184
|
+
}
|
package/README.md
DELETED