---

name: skill-creator description: Create, update, import, or validate Emperor Skills (SKILL.md folders with optional scripts, references, and assets). Use when the user wants a new Skill, wants to improve an existing one, or wants to install a Skill from a folder, a zip, or a GitHub link.

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

Scope	Folder	Notes
Personal	~/.emperor/skills/<name>/	Available in every session
Project	<project>/.emperor/skills/<name>/	Build sessions of that project only; overrides a personal Skill with the same name
Built-in / Plugin	shipped with Emperor or a Plugin	Read-only

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.

Creating a Skill

1. Understand concrete use cases

Ask the user for examples of requests that should trigger the Skill and what a good result looks like. Ask a few questions at a time. Skip this step only when the usage is already clear.

2. Plan the reusable contents

For each example, work out what you would otherwise rewrite or rediscover every time: a script, a reference document, or an asset. That list becomes the Skill's resources.

3. Write the Skill

Name it with a short, verb-led, hyphen-case name (for example "Plan Mode" → plan-mode). Then create it with one call, passing the full SKILL.md and any resource files:

{
  "action": "create",
  "scope": "user",
  "content": "---\nname: pdf-rotate\ndescription: Rotate, split, and merge PDF files. Use when the user asks to change page order or orientation of a PDF.\n---\n\n# PDF Rotate\n\nRun `scripts/rotate.py <file> <degrees>` ...\n",
  "files": {
    "scripts/rotate.py": "import sys\n..."
  }
}

Use "scope": "project" in a Build session when the Skill belongs to that project only.

Writing guidelines:

• Use the imperative voice.
• Put all "when to use" information in the description, not in the body.
• Keep frontmatter minimal; add metadata only when needed, for example metadata: { emperor: { requires: { bins: [git] } } } to declare required tools.

4. Validate

{ "action": "validate", "name": "pdf-rotate" }

Fix every reported error. Warnings (for example a missing referenced file) mean something is probably wrong; check them too. validate also accepts content to check SKILL.md text before writing it.

5. Iterate

Use the Skill on real tasks, note where the agent struggled, and update it:

{
  "action": "update",
  "name": "pdf-rotate",
  "content": "<full new SKILL.md>",
  "files": { "scripts/rotate.py": "..." }
}

update replaces SKILL.md and writes the given files; files you do not pass are kept. Use { "action": "delete", "name": "..." } to remove a Skill.

Importing existing Skills

skill_manage with action: "import" installs Skills from:

• a local folder: { "kind": "folder", "path": "/abs/path" }
• a local zip: { "kind": "zip", "path": "/abs/path/skill.zip" }
• an https link: { "kind": "url", "url": "https://github.com/<owner>/<repo>/tree/<branch>/<folder>" } or a direct .zip link
• pasted SKILL.md text: { "kind": "content", "content": "---\nname: ..." }

Every folder containing a SKILL.md is imported under its frontmatter name. An existing Skill with the same name is kept unless "overwrite": true is passed. Review imported scripts before running them.

Listing

{ "action": "list" } shows the Skills available in the current session with their source, and any invalid Skills with the reason they were rejected.