Keep bundled CommonJS converters working inside ESM projects. Show concise sync failures with expandable original diagnostics and clarify that the last-sync card covers skills and agents only.
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
└── package.json
The Codex and Gemini converters use CommonJS. Each includes a package.json
with "type": "commonjs" so both convert.js and md-toml.js work when installed
inside a project whose own package.json declares "type": "module". Keep this
file when copying an extension. OpenCode's converter uses no CommonJS APIs and
works in either module scope.
Dashboard installation downloads the complete extensions/<name>/ directory
from the runkids/skillshare repository via the GitHub contents API. Updating
the Skillshare binary does not update already installed extension files. To
repair an older Codex or Gemini installation, add package.json containing
{"type":"commonjs"} inside that extension's own directory, preserving any
existing package fields. The project's root package.json does not need to change.
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.