Tools disagree on agent frontmatter and some need another format entirely, so an agent written for Claude is misread elsewhere. An `extension` on a target's agents block reuses the extras transform mechanism to convert each agent during sync. Converted targets hold transformed output, so collect never pulls them back into the source. Leftover symlinks from merge or symlink mode are removed rather than written through, and a failed conversion drops the old output so an unconverted agent never stays active. The bundled opencode-agents extension keeps only fields OpenCode documents and refuses agents that restrict their tools, since dropping those fields would widen the agent's access. Refs #267 Refs #241
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>:
extras:
- name: commands
targets:
- path: ~/.gemini/commands
extension: gemini-commands
During sync, Skillshare:
- Reads each source Markdown file.
- Sends the file content to the extension on
stdin. - Writes the extension's
stdoutto the target file. - Uses
output_extfromextension.yamlto choose the output extension, for example.mdto.toml.
Reference Layout
Each reference extension is self-contained. Copy the whole directory when you want to customize one.
extensions/gemini-commands/
├── extension.yaml
├── convert.js
└── md-toml.js
extension.yaml tells Skillshare how to run the extension:
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:
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
stemfromSS_REL_PATH - escaping TOML strings
- writing TOML output
Mapping API
convert() receives one object:
{
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:
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 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:
name = "review"
Values wrapped with block() become TOML multiline strings:
developer_instructions = """
Review carefully.
"""
Empty values are skipped.
Test A Converter Locally
From the repository root:
printf '%s\n' '---' 'description: Run things' '---' 'Use $ARGUMENTS' \
| SS_REL_PATH=run.md node extensions/gemini-commands/convert.js
Expected shape:
description = "Run things"
prompt = """
Use {{args}}
"""
Create Your Own Extension
-
Copy one reference directory:
cp -R extensions/gemini-commands ~/.config/skillshare/extensions/my-command-format -
Edit
extension.yaml:run: ["node", "convert.js"] output_ext: toml description: "My Markdown command converter" -
Edit
convert.jsto map Markdown into the target tool's format. -
Use it from extras config:
extras: - name: commands targets: - path: ~/.my-tool/commands extension: my-command-format -
Run:
skillshare sync extras
For the full extension contract, see Extension transforms.