mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-19 02:17:09 +00:00
163 lines
4.2 KiB
Markdown
163 lines
4.2 KiB
Markdown
# 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),
|
|
}));
|
|
```
|
|
|
|
For targets with required fields, validate them in `convert.js` and exit non-zero with a clear message. For example, the [Codex custom agent schema](https://developers.openai.com/codex/subagents#custom-agent-file-schema) requires `name`, `description`, and `developer_instructions`, so `extensions/codex-agents` rejects inputs with blank names, blank descriptions, or empty Markdown bodies instead of generating a TOML file that Codex cannot load.
|
|
|
|
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](https://skillshare.runkids.cc/docs/reference/commands/extras#extension-transforms).
|