Slash Commands — Reference Implementations Snapshot#

A snapshot of how five other projects implement slash commands. Each entry records: source directories, frontmatter fields, template syntax, execution modes, argument parsing, UI, and security.

These projects keep evolving upstream. When OpenProgram wants to sync again, come back here, diff each entry item by item, and lift any new design into the field table in slash-commands.md.

Reference checkout path: /Users/fzkuji/Documents/LLM Agent Harness/OpenProgram/references/

1. claude-code-leaked#

Location: references/claude-code-leaked/src/skills/, src/utils/argumentSubstitution.ts, src/types/command.ts

Sources / load order#

loadSkillsDir.ts:638-714:

managed (policy-delivered)
  ↓ later overrides earlier
user      ~/.claude/skills/
  ↓
project   .claude/skills/  (recursed upward from cwd)
  ↓
legacy commands

• Loaded in parallel.
• realpath deduplication so a symlink cannot load the same file twice.
• conditionalSkills: Map<sessionId, Skill[]> holds conditionally activated entries (the paths field).
• lodash memoize caching, cleared by clearSkillCaches(); no watch.

Frontmatter fields (src/utils/frontmatterParser.ts:10-59)#

Command body syntax (loadSkillsDir.ts:344-399, argumentSubstitution.ts)#

• $ARGUMENTS
• $0-$9 (positional)
• $name (named arguments)
• ${CLAUDE_SKILL_DIR}
• ${CLAUDE_SESSION_ID}
• !`cmd` runs a shell command; skipped in the MCP context
• ```! ` ` code block, same as !... ``
• No @file references and no calling other commands

Argument parsing (argumentSubstitution.ts:24-68)#

• tryParseShellCommand first (supports quoting and escapes).
• On failure, falls back to whitespace split.
• Empty arguments return []; $0..$9 in the template become empty strings.
• Numeric named arguments are rejected (they conflict with $0).

Execution modes (src/types/command.ts:25-57)#

type: prompt        → ContentBlockParam, generated dynamically by getPromptForCommand
type: local         → Promise<LocalCommandResult>; supports skip (shows no message)
type: local-jsx     → React (ink) component with an onDone callback
context: inline     → expanded into the current session
context: fork       → runs in a sub-agent (the agent field sets subagent_type)

MCP integration (src/skills/mcpSkillBuilders.ts)#

MCP tools automatically become slash commands with source "mcp", named mcp:tool-name and displayed as /mcp:tool-name (MCP) ....

Conflicts#

The later load wins (managed < user < project). Files with the same realpath are deduplicated, keeping the first.

Security#

• realpath plus a trusted_roots allowlist.
• YAML special-character preprocessing: glob patterns are auto-quoted (quoteProblematicValues).
• Shell selection is per file (it does not read settings.defaultShell).

Distinctive#

• paths conditional activation
• context: fork sub-agents
• effort reasoning strength
• hooks embedded in the command file
• hide-from-slash-command-tool (hidden)
• automatic MCP slash exposure

2. opencode#

Location: references/opencode/packages/opencode/src/config/command.ts

Sources#

Glob: {command,commands}/**/*.md  (absolute paths)

Effect Schema validates the frontmatter and merges it with the content. No deduplication, no watch, no conditional activation.

Frontmatter (minimal, four fields)#

Templates#

Plain text expansion; $ARGUMENTS plus $0-9 positional arguments; the frontmatter arguments: field declares the list.

Distinctive#

• The strongest type safety of the five (Effect).
• subtask: true — a simplified version of claude-code's fork.
• MCP skills return a lazy Promise.

3. openclaw#

Location: references/openclaw/src/auto-reply/commands-registry.*

Sources#

A data-driven hardcoded registry with no filesystem scan, plus provider-specific mapping (Slack vs Mattermost).

Fields (commands-registry.types.ts)#

ChatCommandDefinition:
  key | string               # internal ID
  nativeName | string        # Slack/Mattermost name
  nativeAliases? | string[]
  description | string
  descriptionLocalizations? | Map<lang, desc>
  scope | "text" | "native"
  args? | CommandArgDefinition[]
  acceptsArgs | boolean

Distinctive#

• Multi-provider routing (resolveNativeName, the pluginProvider hook).
• i18n (descriptionLocalizations).
• Argument choice menus (CommandArgChoiceContext), similar to a Discord slash choice dropdown.

SKILL system#

SKILL.md plus frontmatter carrying emoji, requires.anyBins, requires.config, and install[] (dependency checks plus install guidance).

4. hermes-agent#

Location: references/hermes-agent/tools/skills_tool.py, agent/skill_commands.py, agent/skill_preprocessing.py

Sources#

~/.hermes/skills/   a single directory
  ↓ bundled / hub-installed / edited entries coexist
get_external_skills_dirs()   extension point

trusted_roots validation with path-traversal protection.

Frontmatter#

• metadata.hermes.config: configuration variable declarations.
• platforms: ["darwin", "linux", "win32"].
• metadata.hermes.* takes priority over top-level fields.

Command body (skill_preprocessing.py)#

• _substitute_template_vars
• _expand_inline_shell (with a timeout)
• Skill config injection: a [Skill config: ...] block

Distinctive#

• Platform filtering.
• 134 prompt-injection pattern checks.
• A secret-capture callback (_secret_capture_callback).
• Single-directory design.

5. pi-mono#

Location: references/pi-ai/packages/coding-agent/src/core/slash-commands.ts

Sources#

A hardcoded builtin list (settings / model / export / import / fork / clone) with no filesystem scan for extensions.

Distinctive#

The SlashCommandSource enum has extension | prompt | skill, but only builtin is actually used.

It serves as the counterexample — the alternative trade-off of having no extension mechanism at all.

6. Feature matrix#

Common to all five: a description field.

Common to three or more: name + description + body template, frontmatter parsing, and a distinction between execution modes.

Distinctive and worth borrowing:

claude-code  →  context:fork + paths + hooks + effort + realpath dedup + MCP auto-slash
opencode     →  positional args $0-9 + explicit arguments[] declarations
openclaw     →  requires.anyBins + install hints + i18n descriptions
hermes       →  inline shell with a timeout + platform filter
pi-mono      →  counterexample only

OpenProgram's choices: take claude-code's design wholesale, merge in opencode's $0-9 and arguments[], keep openclaw's requires as its own field, apply hermes's timeout idea to ! shell blocks, and use pi-mono's hardcoded-builtin approach only for type: local builtin commands.

7. Sync procedure#

Run periodically (for example each quarter):

1. cd references && git pull to update all reference projects.
2. Diff each project's field table above against upstream:
   • new fields → decide whether they belong in the authoritative field table in slash-commands.md §7
   • new template syntax → decide whether it belongs in §3
   • new execution modes → decide whether it belongs in §4
   • new security constraints → §9
3. Update this file with what changed.

If upstream makes a breaking change (for example claude-code renaming a frontmatter field), do not follow it. OpenProgram's frontmatter is a stable contract and backward compatibility comes first; put the alias mapping in _ALIAS_MAP in frontmatter.py so both the old and new spellings parse.