Skill Creator

Skill Creator

Guidance for creating effective Skills and managing them with the skill_manage tool.

About Skills

A Skill is a self-contained folder that gives the agent specialized knowledge, a workflow, or tools for one kind of task. Think of it as an onboarding guide: it turns a general-purpose agent into one equipped with procedural knowledge no model has on its own.

Skills provide:

1. Workflows: multi-step procedures for a specific domain
2. Tool integrations: how to work with specific file formats or APIs
3. Domain expertise: schemas, conventions, business rules
4. Bundled resources: scripts, references, and assets for repetitive work

Where Skills live

Create, update, delete, and import Skills only with skill_manage. These folders are outside the writable workspace, so file and shell tools cannot write them; skill_manage asks the user for approval unless the session runs with full access. To change a built-in or Plugin Skill, create a personal Skill with the same name; it takes precedence.

Anatomy of a Skill

skill-name/
├── SKILL.md          (required: YAML frontmatter + Markdown instructions)
├── scripts/          (optional: executable code)
├── references/       (optional: documents loaded into context when needed)
└── assets/           (optional: files used in the output, e.g. templates)

SKILL.md

• Frontmatter (YAML, required): name and description. They are the only fields the agent sees before the Skill is loaded, so the description must say what the Skill does and when to use it.
• Body (Markdown): instructions, loaded only after the Skill triggers.

Rules Emperor enforces:

• name: lowercase letters, digits, ., _, -; starts with a letter or digit; at most 64 characters. The frontmatter name is the Skill's name; keep the folder name identical.
• description: required; keep it under 1024 characters.
• Links in SKILL.md should be relative paths inside the Skill folder (for example references/api.md). Missing referenced files are reported as warnings.
• Symbolic links must stay inside the Skill folder. node_modules, .venv, venv, .git, and __pycache__ are ignored and are not copied on import.
• Use {{skill_dir}} for absolute paths to bundled files; Emperor expands it when the Skill is loaded.

Bundled resources

• scripts/: code for tasks that need deterministic reliability or are rewritten repeatedly (for example scripts/rotate_pdf.py). Test every script you add by running it.
• references/: documentation to read while working: schemas, API docs, policies. For large files, tell the agent which grep or glob patterns find the relevant part.
• assets/: files used in the output but not read into context: templates, images, fonts, boilerplate projects.

Do not add README, CHANGELOG, installation guides, or other auxiliary documentation. A Skill contains only what an agent needs to do the job.

Core principles

Be concise

The context window is shared with the system prompt, the conversation, and every other Skill's description. Assume the agent is already capable; add only what it would not know. Prefer short examples over long explanations.

Match freedom to fragility

• High freedom (prose guidance): several approaches are valid and the choice depends on context.
• Medium freedom (pseudocode or parameterized scripts): a preferred pattern exists but variation is fine.
• Low freedom (exact scripts, few parameters): the operation is fragile or must happen in a fixed order.

Progressive disclosure

1. Name and description: always in context.
2. SKILL.md body: loaded when the Skill triggers; keep it under about 500 lines.
3. Bundled resources: read or executed only when needed.

When a Skill covers several variants (frameworks, providers, domains), keep the selection logic in SKILL.md and move each variant's details into its own reference file, linked directly from SKILL.md. Keep references one level deep, and add a table of contents to reference files longer than about 100 lines.