@terra-symposium/skills 0.0.0-stage → 0.1.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.
@@ -0,0 +1,20 @@
1
+ #!/usr/bin/env node
2
+ import console from 'node:console';
3
+ import process from 'node:process';
4
+ import { resolve } from 'node:path';
5
+ import { prepareSkills, checkSkills } from '../src/index.mjs';
6
+
7
+ const [command, rootArg] = process.argv.slice(2);
8
+ if (!['prepare', 'check'].includes(command) || process.argv.length > 4) {
9
+ console.error('Usage: terra-skills <prepare|check> [repository-root]');
10
+ process.exitCode = 2;
11
+ } else {
12
+ try {
13
+ const root = resolve(rootArg ?? process.cwd());
14
+ const result = command === 'prepare' ? await prepareSkills(root) : await checkSkills(root);
15
+ console.log(`${command}: ${result.skills} skills, ${result.files} files`);
16
+ } catch (error) {
17
+ console.error(error.message);
18
+ process.exitCode = 1;
19
+ }
20
+ }
@@ -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 those files beside the page; the compiler copies them into the generated skill folder. `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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
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,146 @@
1
+ import { Buffer } from 'node:buffer';
2
+ import { readFile, readdir, mkdir, rm, writeFile, stat } from 'node:fs/promises';
3
+ import { basename, dirname, extname, join, normalize, relative, resolve, sep } from 'node:path';
4
+ import { parse, stringify } from 'yaml';
5
+
6
+ const marker = '.terra-skills-generated';
7
+ const slug = /^[a-z][a-z0-9-]*$/;
8
+
9
+ async function filesBelow(root) {
10
+ const found = [];
11
+ async function visit(dir) {
12
+ for (const entry of await readdir(dir, { withFileTypes: true })) {
13
+ const path = join(dir, entry.name);
14
+ if (entry.isDirectory()) await visit(path);
15
+ else if (entry.isFile()) found.push(path);
16
+ }
17
+ }
18
+ try {
19
+ await visit(root);
20
+ } catch (error) {
21
+ if (error.code !== 'ENOENT') throw error;
22
+ }
23
+ return found.sort();
24
+ }
25
+
26
+ function splitFrontmatter(source, path) {
27
+ const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(source);
28
+ if (!match) throw new Error(`Missing YAML frontmatter: ${path}`);
29
+ let fields;
30
+ try {
31
+ fields = parse(match[1], { uniqueKeys: true });
32
+ } catch (error) {
33
+ throw new Error(`Invalid YAML frontmatter in ${path}: ${error.message}`, { cause: error });
34
+ }
35
+ if (!fields || typeof fields !== 'object' || Array.isArray(fields))
36
+ throw new Error(`Invalid skill metadata: ${path}`);
37
+ return { fields, body: source.slice(match[0].length) };
38
+ }
39
+
40
+ function validateLinks(contents, file, expected) {
41
+ const withoutFences = contents.replace(/```[\s\S]*?```/g, '');
42
+ for (const match of withoutFences.matchAll(/!?\[[^\]]*\]\(([^)]+)\)/g)) {
43
+ const target = match[1].split('#', 1)[0];
44
+ if (!target || /^(?:[a-z][\w+.-]*:|\/)/i.test(target)) continue;
45
+ const destination = normalize(join(dirname(file), decodeURIComponent(target)));
46
+ if (destination === '..' || destination.startsWith(`..${sep}`))
47
+ throw new Error(`Skill link escapes generated skills: ${file} -> ${target}`);
48
+ if (!expected.has(destination)) throw new Error(`Broken skill link: ${file} -> ${target}`);
49
+ }
50
+ }
51
+
52
+ /** Compile all marked Docs skill pages into a portable in-memory file map. */
53
+ export async function compileSkills(root) {
54
+ const repo = resolve(root);
55
+ const docs = join(repo, 'docs');
56
+ const pages = (await filesBelow(docs)).filter((file) => basename(file) === 'SKILL.md');
57
+ const expected = new Map();
58
+ const names = new Set();
59
+ for (const page of pages) {
60
+ const { fields, body } = splitFrontmatter(await readFile(page, 'utf8'), page);
61
+ if (fields.skill !== true) continue;
62
+ const { name, description } = fields;
63
+ if (!slug.test(name ?? '') || typeof description !== 'string' || !description.trim()) {
64
+ throw new Error(`Skill needs a slug name and description: ${page}`);
65
+ }
66
+ if (names.has(name)) throw new Error(`Duplicate skill name: ${name}`);
67
+ names.add(name);
68
+ delete fields.skill;
69
+ delete fields.title;
70
+ if (!fields.metadata) fields.metadata = { 'related-files': [] };
71
+ const related = fields.metadata?.['related-files'];
72
+ if (!Array.isArray(related)) throw new Error(`Invalid related-files: ${page}`);
73
+ for (const path of related) {
74
+ if (typeof path !== 'string' || path.startsWith('/') || path.split('/').includes('..'))
75
+ throw new Error(`Invalid related file: ${page} -> ${path}`);
76
+ try {
77
+ if (!(await stat(join(repo, path))).isFile()) throw new Error();
78
+ } catch {
79
+ throw new Error(`Missing related file: ${page} -> ${path}`);
80
+ }
81
+ }
82
+ expected.set(join(name, 'SKILL.md'), `---\n${stringify(fields).trimEnd()}\n---\n${body}`);
83
+ for (const file of await filesBelow(dirname(page))) {
84
+ if (file === page) continue;
85
+ const local = relative(dirname(page), file);
86
+ const first = local.split(sep)[0];
87
+ if (
88
+ !['agents', 'assets', 'examples', 'references', 'scripts', 'README.template.md'].includes(
89
+ first,
90
+ )
91
+ )
92
+ continue;
93
+ expected.set(join(name, local), await readFile(file));
94
+ }
95
+ }
96
+ for (const [file, content] of expected) {
97
+ if (extname(file) === '.md') validateLinks(String(content), file, expected);
98
+ }
99
+ return { skills: names.size, files: expected };
100
+ }
101
+
102
+ /** Write compiled skills to the repository discovery directory. */
103
+ export async function prepareSkills(root) {
104
+ const repo = resolve(root);
105
+ const out = join(repo, '.agents', 'skills');
106
+ const compiled = await compileSkills(repo);
107
+ try {
108
+ const entries = await readdir(out);
109
+ if (entries.length && !entries.includes(marker))
110
+ throw new Error(`Refusing to replace non-generated skills: ${out}`);
111
+ } catch (error) {
112
+ if (error.code !== 'ENOENT') throw error;
113
+ }
114
+ await rm(out, { recursive: true, force: true });
115
+ await mkdir(out, { recursive: true });
116
+ for (const [file, content] of compiled.files) {
117
+ const target = join(out, file);
118
+ await mkdir(dirname(target), { recursive: true });
119
+ await writeFile(target, content);
120
+ }
121
+ await writeFile(join(out, marker), 'Generated from docs/ by @terra-symposium/skills.\n');
122
+ return { skills: compiled.skills, files: compiled.files.size };
123
+ }
124
+
125
+ /** Compare discovery files with Docs sources without changing the repository. */
126
+ export async function checkSkills(root) {
127
+ const repo = resolve(root);
128
+ const out = join(repo, '.agents', 'skills');
129
+ const compiled = await compileSkills(repo);
130
+ const actual = (await filesBelow(out))
131
+ .map((file) => relative(out, file))
132
+ .filter((file) => file !== marker);
133
+ const expected = [...compiled.files.keys()];
134
+ const differences = new Set([
135
+ ...actual.filter((file) => !compiled.files.has(file)),
136
+ ...expected.filter((file) => !actual.includes(file)),
137
+ ]);
138
+ for (const file of expected) {
139
+ if (!actual.includes(file)) continue;
140
+ const found = await readFile(join(out, file));
141
+ if (!found.equals(Buffer.from(compiled.files.get(file)))) differences.add(file);
142
+ }
143
+ if (differences.size)
144
+ throw new Error(`Generated skills differ from Docs: ${[...differences].sort().join(', ')}`);
145
+ return { skills: compiled.skills, files: compiled.files.size };
146
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.