Files
skillshare/extensions
Willie cb2bcec948 feat(agents): convert agents with a target extension
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
2026-09-21 13:31:38 +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

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.