Skills & Rules

Skills and rules are two ways to shape how agents work. Skills provide deep, task-specific knowledge that agents load on demand. Rules inject behavioral constraints into every agent interaction.

Skills

A skill is a directory containing a SKILL.md file — structured instructions that an agent reads when performing a specific type of work.

Skill structure

Directorymy-plugin/
- Directoryskills/
  - Directorybuilding-widgets/
    SKILL.md — the skill definition (required)
    Directorytemplates/ — optional reference files
    widget-template.ts
    Directoryexamples/ — optional examples
    basic-widget.ts

SKILL.md format

# Building Widgets

## When to use

Use this skill when the user asks to create, modify, or debug widgets.
Also use when the build step of the widget-pipeline workflow runs.

## Process

1. Read the widget configuration from `widget.config.json`
2. Check existing widgets in `src/widgets/`
3. Generate the widget using the standard template
4. Register the widget in the manifest
5. Run widget validation tests

## Key Files

- `src/widgets/` — widget implementations
- `widget.config.json` — global widget configuration
- `tests/widgets/` — widget test suite

## Conventions

- Widget IDs must be kebab-case
- Every widget must have a corresponding test file
- Use the `WidgetBase` class for all widgets

## Common Mistakes

- Forgetting to register the widget in the manifest
- Using camelCase for widget IDs (must be kebab-case)
- Not running validation after generation

How agents use skills

The agent sees the skill in its catalog via skill_catalog()
When the task matches the skill’s “When to use” description, the agent reads the SKILL.md
The agent follows the process steps and references the key files
Skills can reference other files in their directory (templates, examples)

Skill best practices

Be specific about triggers — the “When to use” section determines whether agents load the skill
Include file paths — agents need to know where to look in the codebase
List common mistakes — prevent agents from making known errors
Keep it focused — one skill per task type. Don’t create a 2000-line mega-skill
Include examples — put reference implementations in the skill directory

Rules

Rules are markdown files that get injected into agent system prompts. They apply to every interaction, unlike skills which are loaded on demand.

Rule file format

Rules are plain markdown files in the plugin’s rules/ directory:

# Widget Naming Conventions

All widget identifiers must follow these rules:

- Use kebab-case (e.g., `data-table`, not `dataTable`)
- Prefix with the module name (e.g., `charts-bar`, `charts-pie`)
- Maximum 30 characters
- No numbers at the start

When creating or renaming widgets, validate the name against these
rules before proceeding.

Rule scope

Rules declared in a plugin apply when that plugin is enabled. If the plugin is disabled, its rules are removed from agent contexts.

Always-apply rules
Conditional rules

Rules that should always be active (coding standards, safety constraints):

{
  "rules": "./rules/"
}

All files in the directory are loaded as rules.

Use the detect field to make the plugin (and its rules) auto-enable for matching projects:

{
  "detect": {
    "files": ["widget.config.json"],
    "strategy": "any"
  },
  "rules": "./rules/"
}

Rules vs. Skills

Aspect	Rules	Skills
Loading	Always injected (when plugin enabled)	Loaded on demand by the agent
Scope	All agent interactions	Specific task types
Size	Short (< 500 words)	Can be longer (process docs)
Purpose	Constraints and conventions	Task-specific knowledge
Format	Markdown file	Directory with SKILL.md