| name | skill-creator |
| description | Create, structure, and validate new skills. Use when designing a skill, scaffolding a skill directory, or improving an existing skill. |
Skill Creator
You are creating or updating an OpenHermit skill. A skill is a directory containing a SKILL.md file (with YAML frontmatter) and optional supporting files (scripts, references, templates). Skills are prompt-based instructions — they tell you what to do, not code plugins.
Skill Format
<skill-id>/
SKILL.md # Required — frontmatter + instructions
scripts/ # Optional — deterministic code the agent runs
references/ # Optional — documentation loaded on demand
templates/ # Optional — output templates, config files
SKILL.md Structure
---
name: <lowercase-hyphen-case, max 64 chars>
description: <one-line summary, max 256 chars — this appears in the system prompt index>
---
<body: detailed instructions for the agent>
Frontmatter rules:
name — required. Lowercase, hyphens only ([a-z0-9-]+), no leading/trailing/consecutive hyphens, max 64 chars.description — required. One clear sentence. This is the only thing shown in the system prompt, so it must be specific enough to trigger skill activation. Max 256 chars.
Process
1. Clarify the skill's purpose
Ask the user:
- What task does this skill handle?
- When should it activate? (What kind of user request triggers it?)
- What does success look like?
Generate 2-3 concrete usage examples to confirm understanding.
2. Plan the skill contents
For each example, identify what reusable resources are needed:
| Directory | When to use | Loaded into context? |
|---|
scripts/ | Deterministic operations that must be exact (deploy, validate, transform) | No — executed via exec |
references/ | Documentation the agent reads on demand (cat references/api-spec.md) | On demand only |
templates/ | Output files, config templates, boilerplate | No — copied/rendered via exec |
Keep SKILL.md under 500 lines. If longer, split into reference files.
3. Write the skill
Create the directory and files. Key principles:
- Be specific. Vague instructions produce vague results. If there's a specific command, write the exact command.
- Be concise. The context window is a shared resource. Only include what the agent doesn't already know.
- Use imperative voice. "Run the tests" not "You should run the tests".
- Progressive disclosure. Put the trigger description in frontmatter (always loaded), core instructions in SKILL.md body (loaded when activated), details in reference files (loaded on demand).
- No fluff files. No README.md, CHANGELOG.md, or LICENSE unless the skill specifically needs them.
4. Validate
Check the skill against these rules:
5. Install the skill
As a workspace skill (self-install):
mkdir -p /workspace/.openhermit/skills/<skill-id>
As a platform skill (admin-managed):
The admin registers it via the gateway API and places files at ~/.openhermit/gateway/registry/skills/<skill-id>/.
Examples of Good Descriptions
- "Build, test, and deploy the current project to the staging environment"
- "Search GitHub issues and PRs by keyword, label, or assignee"
- "Generate a weekly analytics report from the PostgreSQL database"
- "Create, structure, and validate new skills"
Examples of Bad Descriptions
- "Deployment" (too vague — when does it trigger?)
- "A skill that helps with various coding tasks" (not specific)
- "This skill is used for searching things on the internet" (wordy, no clear trigger)
