| name | skill-creator |
| description | Create or update a skill. Use when the user asks to make a new skill, or when you recognize a repeatable multi-step workflow that should become one. |
You are the skill creator. Your job is to produce well-structured, provider-neutral skills that any LLM-based agent can execute. For deep reference on any topic below, see the references/ directory alongside this file.
Input
$ARGUMENTS — a description of the desired skill, possibly with examples, constraints, or edge cases.
Procedure
1. Clarify intent
If $ARGUMENTS is vague, ask one round of targeted questions: name, trigger condition, inputs, outputs, edge cases. If it's clear enough, skip straight to drafting.
Before writing from scratch, check whether the user has real source material — runbooks, incident reports, code review threads, API docs. Skills grounded in actual expertise outperform those generated from generic knowledge. See references/best-practice.md for sourcing strategies.
2. Choose a name
The name field has strict constraints:
- 1-64 characters
- Lowercase letters, numbers, and hyphens only
- Must not start or end with a hyphen
- No consecutive hyphens (
--)
- Must match the parent directory name
The name is the slash-command users type (/my-skill). Keep it short and descriptive.
3. Write the frontmatter
Two fields are required. Optional fields are available but should only be added when genuinely needed.
---
name: <skill-name>
description: <what the skill does and when to use it>
---
Required fields:
| Field | Constraint | Purpose |
|---|
name | 1-64 chars | Identifier, must match directory name |
description | 1-1024 chars | Agents read this to decide when to invoke the skill |
Optional fields (add only when needed):
| Field | Purpose |
|---|
license | License name or reference to a bundled license file |
compatibility | Environment requirements (packages, network access, etc.) |
metadata | Arbitrary key-value pairs (author, version, etc.) |
Do NOT add provider-specific fields (model, tools, thinking, allowed-tools, etc.). Those are runtime concerns, not skill concerns. A skill must be portable: any agent, any provider, any runtime. See references/specification.md for the full spec.
Writing good descriptions — the description carries the entire burden of triggering. Guidelines:
- Use imperative phrasing: "Use this skill when..." not "This skill does..."
- Focus on user intent, not implementation details
- Be specific about scope — list the contexts where the skill applies
- Include cases where the user might not name the domain directly
- Keep it under 1024 characters
See references/optimize-description.md for systematic testing.
4. Write the instructions
The markdown body after the frontmatter. This is what the agent follows when the skill activates.
Core principles:
- Be imperative. Write instructions the agent follows, not documentation about the skill.
- Use
$ARGUMENTS as the placeholder for user-provided input at invocation time.
- One job per skill. If the workflow has clearly separable phases, split into multiple skills.
- No provider assumptions. Describe what needs to happen, not how a particular provider does it. Don't reference specific tool names, SDK features, or model capabilities.
- Add what the agent lacks, omit what it knows. Don't explain common concepts. Focus on project-specific conventions, non-obvious edge cases, and the particular tools or APIs to use.
- Provide defaults, not menus. When multiple approaches could work, pick one default. Mention alternatives briefly only as escape hatches.
- Favor procedures over declarations. Teach how to approach a class of problems, not what to produce for a specific instance.
- Match specificity to fragility. Give freedom when multiple approaches work. Be prescriptive when operations are fragile or exact sequences matter.
Effective instruction patterns (use what fits, skip what doesn't):
- Gotchas section — environment-specific facts that defy assumptions. Highest-value content in many skills.
- Output templates — concrete structure the agent pattern-matches against. More reliable than prose descriptions. Short templates inline; longer ones in
assets/.
- Checklists — help the agent track progress in multi-step workflows, especially with dependencies.
- Validation loops — do work, run validator, fix issues, repeat until passing.
- Plan-validate-execute — for batch or destructive operations, create an intermediate plan, validate it, then execute.
See references/best-practice.md for detailed examples of each pattern.
Size targets:
- Keep
SKILL.md under 500 lines and ~5000 tokens
- Move detailed reference material to
references/ and tell the agent when to load each file
- This is progressive disclosure: metadata (~100 tokens) at startup, instructions on activation, resources on demand
5. Create supporting files if needed
Skill location. In an outclaw agent workspace, all skills live at <agent-workspace>/skills/<skill-name>/ — typically ~/.outclaw/agents/<agent-name>/skills/<skill-name>/. Always resolve to an absolute path before writing; do not rely on the current working directory matching the workspace root. Do not use .claude/skills/, .agents/skills/, or any other CLI-default location — outclaw does not read from those.
<agent-workspace>/skills/<skill-name>/
├── SKILL.md # Required: instructions + metadata
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
└── assets/ # Optional: templates, resources
Scripts — bundle reusable logic the agent would otherwise reinvent each run. Design for agentic use: no interactive prompts, --help for usage, structured output (JSON/CSV), helpful error messages, idempotent operations. Prefer self-contained scripts with inline dependencies. See references/using-scripts.md for language-specific patterns.
References — keep individual files focused. Use conditional loading: "Read references/api-errors.md if the API returns a non-200 status code."
Assets — templates, schemas, lookup tables. Reference with relative paths from the skill root.
Use relative paths from the skill directory root for all file references. Keep references one level deep from SKILL.md.
Most skills are just a SKILL.md. Only create supporting files when genuinely needed.
6. Write the skill
Create the directory and files under <agent-workspace>/skills/<skill-name>/ (absolute path). If the user did not specify which agent workspace, default to the current agent's workspace; ask only if ambiguous.
7. Verify
Read back the created SKILL.md and confirm:
- Valid YAML frontmatter with
name and description (plus optional fields only if justified)
name matches directory name and follows naming rulesdescription is imperative, specific, and under 1024 characters- Instructions are imperative and provider-neutral
- Uses
$ARGUMENTS if user input is expected
- Under 500 lines; reference material in separate files if needed
- No provider-specific tool names, SDK features, or model references
Report what you created and how to invoke it (/<skill-name>).
Updating existing skills
When updating rather than creating, follow the same principles but also:
- Read the existing SKILL.md first
- Preserve what works; fix what doesn't
- If the user has execution feedback (failed assertions, transcript issues), use it to guide changes — see references/evaluating-skills.md
- Generalize fixes rather than patching for specific cases
