Files
Willie 2ef704a77b fix(sync): isolate extension modules and condense diagnostics
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.
2026-10-06 21:36:04 +08:00
..

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:

  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.

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 stem from SS_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

  1. Copy one reference directory:

    cp -R extensions/gemini-commands ~/.config/skillshare/extensions/my-command-format
    
  2. Edit extension.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:

    extras:
      - name: commands
        targets:
          - path: ~/.my-tool/commands
            extension: my-command-format
    
  5. Run:

    skillshare sync extras
    

For the full extension contract, see Extension transforms.