refactor(extensions): simplify reference converters

This commit is contained in:
Willie
2026-05-30 19:23:12 +08:00
parent bb0f3c2a0b
commit f59d5e905b
6 changed files with 349 additions and 120 deletions
+160
View File
@@ -0,0 +1,160 @@
# Extensions
This directory contains reference extensions for transforming Markdown extras into tool-specific files during `skillshare sync extras`.
The reference extensions use plain JavaScript with Node.js. Extensions are not limited to JavaScript, but plain JS is the most practical cross-platform default for directly editable examples:
- Windows, macOS, and Linux can run the same script with `node`.
- No TypeScript, npm install, bundling, or build step is required.
- Users can edit the script directly.
- Bash is fine for personal Unix-only scripts, but it is not a good default reference for Windows/macOS/Linux support.
## How Extensions Run
An extras target can set `extension: <name>`:
```yaml
extras:
- name: commands
targets:
- path: ~/.gemini/commands
extension: gemini-commands
```
During sync, Skillshare:
1. Reads each source Markdown file.
2. Sends the file content to the extension on `stdin`.
3. Writes the extension's `stdout` to the target file.
4. Uses `output_ext` from `extension.yaml` to choose the output extension, for example `.md` to `.toml`.
## Reference Layout
Each reference extension is self-contained. Copy the whole directory when you want to customize one.
```text
extensions/gemini-commands/
├── extension.yaml
├── convert.js
└── md-toml.js
```
`extension.yaml` tells Skillshare how to run the extension:
```yaml
run: ["node", "convert.js"]
output_ext: toml
description: "Markdown slash-command (Claude/Cursor style) → Gemini CLI TOML command"
```
`convert.js` is the file users are expected to edit. It only contains the field mapping:
```js
const { block, convert } = require("./md-toml");
convert(({ body, frontmatter }) => ({
description: frontmatter.description,
prompt: block(body.replace(/\$ARGUMENTS\b|\$\d+/g, "{{args}}")),
}));
```
`md-toml.js` is a helper for the repetitive parts that are easy to get wrong:
- reading `stdin`
- parsing simple Markdown frontmatter
- deriving `stem` from `SS_REL_PATH`
- escaping TOML strings
- writing TOML output
## Mapping API
`convert()` receives one object:
```js
{
body, // Markdown body after frontmatter
frontmatter, // simple key/value frontmatter
relPath, // SS_REL_PATH, relative to the extras source root
stem // filename without extension
}
```
Return an object whose keys become TOML fields:
```js
convert(({ body, frontmatter, stem }) => ({
name: frontmatter.name || stem,
description: frontmatter.description,
developer_instructions: block(body),
}));
```
Plain values become TOML strings:
```toml
name = "review"
```
Values wrapped with `block()` become TOML multiline strings:
```toml
developer_instructions = """
Review carefully.
"""
```
Empty values are skipped.
## Test A Converter Locally
From the repository root:
```bash
printf '%s\n' '---' 'description: Run things' '---' 'Use $ARGUMENTS' \
| SS_REL_PATH=run.md node extensions/gemini-commands/convert.js
```
Expected shape:
```toml
description = "Run things"
prompt = """
Use {{args}}
"""
```
## Create Your Own Extension
1. Copy one reference directory:
```bash
cp -R extensions/gemini-commands ~/.config/skillshare/extensions/my-command-format
```
2. Edit `extension.yaml`:
```yaml
run: ["node", "convert.js"]
output_ext: toml
description: "My Markdown command converter"
```
3. Edit `convert.js` to map Markdown into the target tool's format.
4. Use it from extras config:
```yaml
extras:
- name: commands
targets:
- path: ~/.my-tool/commands
extension: my-command-format
```
5. Run:
```bash
skillshare sync extras
```
For the full extension contract, see [Extension transforms](../website/docs/reference/commands/extras.md#extension-transforms).
+7 -64
View File
@@ -1,66 +1,9 @@
#!/usr/bin/env node
// Convert a markdown subagent (YAML frontmatter + body) to a Codex CLI TOML agent.
//
// Reads markdown from stdin, writes TOML to stdout.
// Mapping:
// frontmatter `name` -> TOML `name` (falls back to SS_REL_PATH filename)
// frontmatter `description` -> TOML `description`
// frontmatter `model` -> TOML `model` (omitted when absent)
// markdown body -> TOML `developer_instructions` (triple-quoted)
// Unknown frontmatter keys are dropped.
const { block, convert } = require("./md-toml");
const path = require("path");
function splitFrontmatter(text) {
if (text.startsWith("---")) {
const end = text.indexOf("\n---", 3);
if (end !== -1) {
const fm = text.slice(3, end).replace(/^\n+|\n+$/g, "");
const body = text.slice(end + 4).replace(/^\n+/, "");
return [fm, body];
}
}
return ["", text];
}
function getKey(fm, key) {
const re = new RegExp("^\\s*" + key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "\\s*:\\s*(.+?)\\s*$");
for (const line of fm.split("\n")) {
const m = line.match(re);
if (m) return m[1].trim().replace(/^["']|["']$/g, "");
}
return "";
}
function tomlEscapeBasic(s) {
return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
}
function readStdin() {
return new Promise((resolve) => {
let data = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => (data += chunk));
process.stdin.on("end", () => resolve(data));
});
}
(async () => {
const text = await readStdin();
const [fm, body] = splitFrontmatter(text);
let name = getKey(fm, "name");
if (!name) {
const rel = process.env.SS_REL_PATH || "agent.md";
name = path.basename(rel, path.extname(rel));
}
const description = getKey(fm, "description");
const model = getKey(fm, "model");
const out = [`name = "${tomlEscapeBasic(name)}"`];
if (description) out.push(`description = "${tomlEscapeBasic(description)}"`);
if (model) out.push(`model = "${tomlEscapeBasic(model)}"`);
let fence = '"""';
if (body.includes(fence)) fence = "'''";
out.push(`developer_instructions = ${fence}\n${body.replace(/\n+$/, "")}\n${fence}`);
process.stdout.write(out.join("\n") + "\n");
})();
convert(({ body, frontmatter, stem }) => ({
name: frontmatter.name || stem,
description: frontmatter.description,
model: frontmatter.model,
developer_instructions: block(body),
}));
+87
View File
@@ -0,0 +1,87 @@
const path = require("path");
function block(value) {
return { type: "block", value };
}
function convert(mapFields) {
readStdin().then((input) => {
const doc = parseMarkdown(input);
const fields = mapFields(doc) || {};
const lines = [];
for (const [key, value] of Object.entries(fields)) {
if (value == null || value === "") continue;
if (value.type === "block") {
lines.push(`${key} = ${tomlBlock(value.value)}`);
continue;
}
lines.push(`${key} = ${tomlString(value)}`);
}
process.stdout.write(lines.join("\n") + (lines.length ? "\n" : ""));
});
}
function parseMarkdown(input) {
const { frontmatterText, body } = splitFrontmatter(input);
const relPath = process.env.SS_REL_PATH || "input.md";
return {
body,
frontmatter: parseFrontmatter(frontmatterText),
relPath,
stem: path.basename(relPath, path.extname(relPath)),
};
}
function splitFrontmatter(input) {
const match = input.match(/^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/);
if (!match) return { frontmatterText: "", body: input };
return {
frontmatterText: match[1],
body: input.slice(match[0].length),
};
}
function parseFrontmatter(text) {
const frontmatter = {};
for (const line of text.split(/\r?\n/)) {
const match = line.match(/^\s*([A-Za-z0-9_-]+)\s*:\s*(.*?)\s*$/);
if (match) frontmatter[match[1]] = stripQuotes(match[2]);
}
return frontmatter;
}
function stripQuotes(value) {
if (value.length < 2) return value;
const first = value[0];
const last = value[value.length - 1];
if ((first === `"` && last === `"`) || (first === `'` && last === `'`)) {
return value.slice(1, -1);
}
return value;
}
function tomlString(value) {
return `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
}
function tomlBlock(value) {
const text = String(value).replace(/\n+$/, "");
if (!text.includes(`"""`)) return `"""\n${text}\n"""`;
if (!text.includes(`'''`)) return `'''\n${text}\n'''`;
return `"""\n${text.replace(/"""/g, `\\"""`)}\n"""`;
}
function readStdin() {
return new Promise((resolve) => {
let data = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => (data += chunk));
process.stdin.on("end", () => resolve(data));
});
}
module.exports = { block, convert };
+5 -54
View File
@@ -1,56 +1,7 @@
#!/usr/bin/env node
// Convert a markdown command (YAML frontmatter + body) to a Gemini CLI TOML command.
//
// Reads markdown from stdin, writes TOML to stdout.
// Mapping:
// frontmatter `description` -> TOML `description`
// markdown body -> TOML `prompt` (triple-quoted)
// Claude placeholders $ARGUMENTS / $1.. -> Gemini {{args}}
// Unknown frontmatter keys are dropped.
const { block, convert } = require("./md-toml");
function splitFrontmatter(text) {
if (text.startsWith("---")) {
const end = text.indexOf("\n---", 3);
if (end !== -1) {
const fm = text.slice(3, end).replace(/^\n+|\n+$/g, "");
const body = text.slice(end + 4).replace(/^\n+/, "");
return [fm, body];
}
}
return ["", text];
}
function getDescription(fm) {
for (const line of fm.split("\n")) {
const m = line.match(/^\s*description\s*:\s*(.+?)\s*$/);
if (m) return m[1].trim().replace(/^["']|["']$/g, "");
}
return "";
}
function tomlEscapeBasic(s) {
return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
}
function readStdin() {
return new Promise((resolve) => {
let data = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => (data += chunk));
process.stdin.on("end", () => resolve(data));
});
}
(async () => {
const text = await readStdin();
const [fm, body] = splitFrontmatter(text);
const description = getDescription(fm);
let prompt = body.replace(/\$ARGUMENTS\b/g, "{{args}}").replace(/\$\d+/g, "{{args}}");
const out = [];
if (description) out.push(`description = "${tomlEscapeBasic(description)}"`);
let fence = '"""';
if (prompt.includes(fence)) fence = "'''";
out.push(`prompt = ${fence}\n${prompt.replace(/\n+$/, "")}\n${fence}`);
process.stdout.write(out.join("\n") + "\n");
})();
convert(({ body, frontmatter }) => ({
description: frontmatter.description,
prompt: block(body.replace(/\$ARGUMENTS\b|\$\d+/g, "{{args}}")),
}));
+87
View File
@@ -0,0 +1,87 @@
const path = require("path");
function block(value) {
return { type: "block", value };
}
function convert(mapFields) {
readStdin().then((input) => {
const doc = parseMarkdown(input);
const fields = mapFields(doc) || {};
const lines = [];
for (const [key, value] of Object.entries(fields)) {
if (value == null || value === "") continue;
if (value.type === "block") {
lines.push(`${key} = ${tomlBlock(value.value)}`);
continue;
}
lines.push(`${key} = ${tomlString(value)}`);
}
process.stdout.write(lines.join("\n") + (lines.length ? "\n" : ""));
});
}
function parseMarkdown(input) {
const { frontmatterText, body } = splitFrontmatter(input);
const relPath = process.env.SS_REL_PATH || "input.md";
return {
body,
frontmatter: parseFrontmatter(frontmatterText),
relPath,
stem: path.basename(relPath, path.extname(relPath)),
};
}
function splitFrontmatter(input) {
const match = input.match(/^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/);
if (!match) return { frontmatterText: "", body: input };
return {
frontmatterText: match[1],
body: input.slice(match[0].length),
};
}
function parseFrontmatter(text) {
const frontmatter = {};
for (const line of text.split(/\r?\n/)) {
const match = line.match(/^\s*([A-Za-z0-9_-]+)\s*:\s*(.*?)\s*$/);
if (match) frontmatter[match[1]] = stripQuotes(match[2]);
}
return frontmatter;
}
function stripQuotes(value) {
if (value.length < 2) return value;
const first = value[0];
const last = value[value.length - 1];
if ((first === `"` && last === `"`) || (first === `'` && last === `'`)) {
return value.slice(1, -1);
}
return value;
}
function tomlString(value) {
return `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
}
function tomlBlock(value) {
const text = String(value).replace(/\n+$/, "");
if (!text.includes(`"""`)) return `"""\n${text}\n"""`;
if (!text.includes(`'''`)) return `'''\n${text}\n'''`;
return `"""\n${text.replace(/"""/g, `\\"""`)}\n"""`;
}
function readStdin() {
return new Promise((resolve) => {
let data = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => (data += chunk));
process.stdin.on("end", () => resolve(data));
});
}
module.exports = { block, convert };
+3 -2
View File
@@ -297,7 +297,8 @@ A single executable, or a directory with a manifest:
```
.skillshare/extensions/gemini-commands/
├── extension.yaml
└── convert.js
├── convert.js # mapping rules you edit
└── md-toml.js # helper for markdown/frontmatter/TOML
```
`extension.yaml`:
@@ -322,7 +323,7 @@ The mechanism is cross-platform; whether an extension runs depends on its interp
### Reference extensions
The skillshare repo ships example extensions under `extensions/` (`gemini-commands`, `codex-agents`). Copy one into your extensions directory and adapt it — they are references, not installed automatically.
The skillshare repo ships example extensions under `extensions/` (`gemini-commands`, `codex-agents`). Copy one into your extensions directory and adapt it — they are references, not installed automatically. Each reference extension keeps `convert.js` short so you edit only the field mapping; `md-toml.js` handles reading markdown, parsing simple frontmatter, and writing TOML.
### Recipe: Codex agents