Adding a Skill

Overview

Skills are reusable methodologies in plugins/onex/skills/. Each skill lives in its own directory and is defined by a SKILL.md file. Skills can include executable scripts, prompt templates, and supporting files.

Skills are invoked with /skill-name in Claude Code (after deploying the plugin). They can also be referenced by agents and commands.

Create the Skill Directory

mkdir -p plugins/onex/skills/my-skill

Each skill must have a directory under plugins/onex/skills/.

Create SKILL.md

Create plugins/onex/skills/my-skill/SKILL.md:

# My Skill

## Overview

One paragraph describing what this skill does and when to use it.

## Quick Start

\`\`\`bash
# Minimal invocation
/my-skill
\`\`\`

## Methodology

Step-by-step description of how the skill works:

1. First step — what happens and why
2. Second step — what happens and why
3. Third step — what happens and why

## Options

| Option | Description | Default |
|--------|-------------|---------|
| `--flag` | Description of flag | (none) |

## Examples

### Basic Usage

\`\`\`bash
/my-skill
\`\`\`

### With Options

\`\`\`bash
/my-skill --flag value
\`\`\`

## Output

Description of what the skill produces (files, annotations, reports, etc.).

## Notes

- Any important constraints or prerequisites
- Related skills or commands: `/related-skill`

Required sections in SKILL.md:

Optional sections (add as needed):

• Options — flags and parameters
• Examples — usage patterns
• Output — what the skill produces
• Notes — constraints, prerequisites, related skills

Add Supporting Files (Optional)

Skills can include:

prompt.md — Detailed orchestration logic or prompt template used internally by the skill:

plugins/onex/skills/my-skill/
├── SKILL.md         # User-facing documentation (required)
├── prompt.md        # Internal orchestration logic (optional)
└── scripts/         # Executable scripts (optional)
    └── run.sh

If your skill executes scripts, make them executable:

chmod +x plugins/onex/skills/my-skill/scripts/run.sh

Invoke the Skill

After deploying (/deploy-local-plugin), invoke the skill in Claude Code:

/my-skill

Claude Code discovers skills from plugins/onex/skills/ automatically.

If the skill does not appear after deploying:

1. Verify SKILL.md exists at plugins/onex/skills/my-skill/SKILL.md.
2. Restart Claude Code to pick up the new plugin state.
3. Check that the plugin cache was updated: ls ~/.claude/plugins/cache/.

Reference

• Skill definitions: plugins/onex/skills/*/SKILL.md
• Existing skills for reference patterns: plugins/onex/skills/
• Skill authoring guide: docs/reference/SKILL_AUTHORING_GUIDE.md
• Commands (related): plugins/onex/commands/*.md