org2ai Creating Skills in ORG2
Skills are markdown files that teach the agent how to perform specific tasks. They appear in the / slash menu and are included in the agent's system prompt when relevant.
Before You Begin
Gather from the user:
- Purpose: What task or workflow should this skill help with?
- Location: Global (
~/.orgii/skills/) or Project (<repo>/.orgii/skills/)? - Trigger scenarios: When should the agent use this skill?
- Domain knowledge: What specialized context does the agent need?
If you have conversation context, infer the skill from what was discussed.
Storage Locations
| Type | Path | Scope |
|---|---|---|
| Global | ~/.orgii/skills/skill-name/ |
Available across all projects |
| Project | <repo>/.orgii/skills/skill-name/ |
Shared with the repository |
These two scopes match the SKILL_SCOPE constant in
src/types/extensions/types.ts and the picker labels in
SkillEditorPanel.tsx. Skills do not have a separate "Personal" scope the
way Rules do — there is only one per-user location, and it is called
Global.
Skill File Structure
skill-name/
├── SKILL.md # Required — main instructions
├── reference.md # Optional — detailed docs / reference tables
└── examples.md # Optional — usage examples
SKILL.md Format
---
name: your-skill-name
description: Brief description of what this skill does and when to use it.
---
# Skill Name
## Instructions
Clear, step-by-step guidance for the agent.
## Examples
Concrete examples.
Frontmatter Fields
| Field | Requirements |
|---|---|
name |
Max 64 chars, lowercase letters/numbers/hyphens only |
description |
Max 1024 chars. Include WHAT it does AND WHEN to trigger. |
Writing a Good Description
The description is critical — the agent uses it to decide when to apply the skill:
# Good — specific, includes trigger terms
description: Deploy Rust services to AWS Lambda. Use when building or deploying
Lambda functions, setting up SAM templates, or packaging Rust for serverless.
# Bad — too vague
description: Helps with deployment
Rules:
- Write in third person ("Use when..." not "I help with...")
- Include both WHAT and WHEN
- List concrete trigger terms (tool names, file types, workflows)
Authoring Principles
- Concise: Only include context the agent doesn't already have
- Under 500 lines: Keep SKILL.md focused; put details in
reference.md - Progressive disclosure: Link to reference files rather than inlining everything
- Actionable: Steps should be executable, not aspirational
Creation Workflow
- Clarify — gather purpose, location, triggers, constraints from user
- Design — draft name, description, section outline
- Implement — create the directory and write SKILL.md
- Verify — check description quality, line count, name format
Example Skill
---
name: code-review
description: Review code changes for quality, security, and maintainability.
Use when reviewing pull requests, diffs, or checking code before commit.
---
# Code Review
## Review Order
1. Correctness — does the code do what it claims?
2. Security — are there injection, auth, or data-leak risks?
3. Readability — would a new team member understand this?
4. Tests — are edge cases covered?
## Feedback Labels
- **Critical** — must fix before merge
- **Suggestion** — worth improving
- **Nit** — minor style preference
## Reference
See [review-checklist.md](review-checklist.md) for the full checklist.
Checklist
- Directory created at the correct location
-
nameis lowercase-hyphenated, max 64 chars -
descriptionincludes trigger terms and WHEN clause - SKILL.md is under 500 lines
- Heavy reference material moved to
reference.md