# 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: `: ```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).