| name | writing-skills |
| description | Use when creating or editing reusable agent skills, improving skill discovery metadata, organizing bundled resources, or validating a skill package |
Writing Skills
Overview
Write concise, discoverable instructions that give another agent reusable knowledge or a reliable workflow. Include only information that materially improves execution.
Org Plan Authority
When $org-plan is active, it controls L1/L2 order, scope, testing boundaries, commits, and continuation. Skill authoring remains inside the current L2 and adds no separate gate, pause, review, subagent, deployment, push, or commit workflow.
What Belongs in a Skill
Use a skill for reusable:
- techniques and workflows;
- domain knowledge and conventions;
- tool or format instructions;
- scripts, references, templates, or assets that prevent repeated work.
Keep one-off project decisions in project instructions. Automate mechanical constraints when a validator or script can enforce them.
Authoring Workflow
- Define the situations that should trigger the skill and the outcomes it should support.
- Identify only the non-obvious instructions and reusable resources an agent needs.
- Choose a short lowercase hyphenated name and create a matching directory.
- Write
SKILL.md with valid YAML frontmatter and concise imperative guidance.
- Add supporting scripts, references, or assets only when they are directly useful.
- Check links, examples, commands, metadata, and compatibility with governing project instructions.
- Run the available structural validator and any relevant usage checks after editing.
- Fix discovered problems until the skill and its relevant checks are valid.
No preliminary control run or prescribed test ordering is required.
Directory Structure
skill-name/
├── SKILL.md
├── agents/
│ └── openai.yaml
├── scripts/
├── references/
└── assets/
Only SKILL.md is required. Create optional directories only when they contain resources the skill actually uses.
Frontmatter
Use exactly the metadata supported by the target runtime. The portable minimum is:
---
name: skill-name
description: Use when [specific triggering situations, symptoms, or tasks]
---
- Make
name match the directory and use lowercase letters, digits, and hyphens.
- Make
description explain when the skill should load.
- Include concrete trigger vocabulary an agent or user is likely to search for.
- Avoid vague descriptions and process summaries that let an agent guess without reading the skill.
Body Structure
Prefer the smallest structure that makes the instructions easy to use:
# Skill Name
## Overview
[Purpose and core principle]
## Workflow
[Ordered instructions]
## Quick Reference
[Compact mappings or commands, when useful]
## Common Mistakes
[Likely failure and correction]
Do not add sections merely to fill a template. Put triggering information in frontmatter because the body is loaded only after discovery.
Writing Guidance
- Use direct imperative language.
- State observable conditions and expected outputs.
- Prefer positive output contracts for shape and structure.
- Use explicit prohibitions only for real safety or discipline constraints.
- Keep examples complete, realistic, and few.
- Avoid narratives about one past task.
- Do not repeat material already available in a linked reference or tool help.
- Keep project-specific policy subordinate to the project's governing instructions.
Discovery Optimization
Future agents discover skills from their name and description before reading the body.
- Use descriptive, action-oriented names such as
creating-diagrams or debugging-with-logs.
- Include symptoms, file types, tools, error terms, and common synonyms in the description when relevant.
- Describe triggering conditions rather than advertising capabilities in generic terms.
- Keep metadata concise enough to scan quickly.
Bundled Resources
Scripts
Include scripts for deterministic or frequently repeated operations. Run added or changed scripts with representative inputs and document required arguments in the main skill or script help.
References
Move long domain documentation or variant-specific details into focused references. Link each reference directly from SKILL.md and say when it is useful. Avoid deep reference chains.
Assets
Use assets for templates and files intended to be copied into outputs. Do not use assets as hidden instruction storage.
Flowcharts and Examples
Use a flowchart only for a non-obvious decision, branch, or loop. Use Markdown for linear procedures and tables for mappings. See graphviz-conventions.dot for diagram conventions and use render-graphs.js when rendered inspection is useful.
One strong example is usually better than several shallow variants. Examples should be internally consistent and ready to adapt.
Validation
When the runtime provides the standard skill validator, run:
python3 <skill-creator-root>/scripts/quick_validate.py path/to/skill
Also run package-specific integrity, discovery, syntax, and behavior checks required by the repository. Report the commands and current results before claiming completion.
Checklist
