Creating Skills

If you are building a Robo.js plugin, you can ship skills alongside your code. When a user installs your plugin with npx robo add, your skills are offered for installation into their AI tool's skills directory.

Directory structure

Create a skills/ directory at the root of your plugin package. Each skill is a subdirectory containing a SKILL.md file:

The skill directory name (e.g., my-plugin-guide) becomes the skill identifier. Choose a name that is unique across the ecosystem — prefixing with your plugin name is a good convention.

SKILL.md frontmatter

Every SKILL.md starts with YAML frontmatter:

---
name: my-plugin-guide
description: "Reference guide for building with my-plugin — covers setup, API patterns, and common mistakes."
user-invocable: true
argument-hint: "<question, or 'create <type>'>"
---

Required fields

Optional fields

Writing effective content

The body of SKILL.md is the instruction set that AI tools read. Write it as if you are explaining your plugin to a knowledgeable developer who has never seen it before.

Start with a mental model

Explain how your plugin works at a high level. What are the core concepts? What does the file structure look like?

## Mental Model

Files in `src/widgets/` are auto-discovered at build time. Each file exports
a default handler and an optional `config` export for metadata.

src/widgets/
  counter.ts     -> widget named "counter"
  timer.ts       -> widget named "timer"
  dashboard/
    main.ts      -> widget named "dashboard/main"

Include code patterns

Show the exact code patterns a developer should use. Include imports, types, and complete examples:

## Creating a Widget

```typescript
import { createWidgetConfig } from 'my-plugin'
import type { WidgetContext } from 'my-plugin'

export const config = createWidgetConfig({
  description: 'A counter widget',
  refreshInterval: 5000
})

export default async function (context: WidgetContext) {
  const count = await context.state.get<number>('count') ?? 0
  return { count }
}
`` `

Document common mistakes

This is often the most valuable section. List the errors that users hit and how to fix them:

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Importing from `my-plugin/internal` | Use `my-plugin` (public API only) |
| Missing `type: 'plugin'` in config | Required for all plugins |
| Sync handler for async operations | Use `async function` and `await` |

Add a usage section

If the skill is user-invocable, document how to invoke it and what modes it supports:

## Usage

/my-plugin-guide                    # Inject this guide as context
/my-plugin-guide create widget      # Generate a widget file
/my-plugin-guide <question>         # Answer a question

Reference files

For large skills, split content into multiple files. Place additional Markdown files in a references/ subdirectory:

The SKILL.md can reference these files, and they are copied alongside it during installation.

Discovery mechanism

When a user runs npx robo skills install --all, the CLI:

1. Loads the project's configuration to find registered plugins
2. Resolves each plugin's package directory
3. Checks for a skills/ directory in each package
4. Scans for subdirectories containing a SKILL.md file
5. Parses the description from the YAML frontmatter
6. Presents the discovered skills for installation

For the core robo.js package, the CLI looks for skills/ relative to its own package directory. For all other plugins, it checks both sibling package paths and node_modules.

Auto-install on plugin add

When a user installs your plugin with npx robo add my-plugin, the CLI automatically discovers and offers your skills. No additional configuration is needed beyond placing the skills/ directory in your package.

Testing your skills

Before publishing, verify that your skills work correctly:

robo build plugin

npx robo add /path/to/my-plugin

Package.json checklist

Make sure your package.json includes the skills directory:

{
  "files": [".robo/", "src/", "skills/", "seed/", "LICENSE", "README.md"]
}

Next steps