Skills

A skill is a markdown file that teaches an agent how to do one specific thing: run your team's release checklist, audit a Rust crate, write a migration the way your repo expects. Skills exist so a procedure can be written down once, versioned in a repo, and pulled into context only when it is relevant. ORG-2 scans a set of directories for skills, shows the agent a short list of names and descriptions each turn, and loads the full body only when a skill is selected.

What a skill is on disk

A skill is a directory containing a SKILL.md file, plus any optional files it wants to reference:

code-review/
├── SKILL.md          # required — the instructions the agent reads
├── review-checklist.md
└── scripts/validate.py

The directory name is the skill's name. SKILL.md starts with a YAML frontmatter block followed by a markdown body.

---
name: code-review
description: Review code changes for quality, security, and maintainability. Use when reviewing pull requests, diffs, or checking code before commit.
version: 1.0.0
---

# Code Review

## Review Order

1. Correctness — does the code do what it claims?
2. Security — injection, auth, or data-leak risks?
3. Tests — are edge cases covered?

See [review-checklist.md](review-checklist.md) for the full checklist.

Frontmatter fields

If description is missing, ORG-2 falls back to the first non-heading line of the body — but the editor will warn you, because a skill with no description is a skill the agent will never pick. If any entry in bins is not on PATH, or any variable in env is unset, the skill is marked unavailable and is excluded from what the agent sees.

Note: Keep SKILL.md focused. The editor flags anything over 5,000 estimated tokens and suggests splitting the detail into reference files that the agent reads only when it needs them.

Where skills are loaded from

ORG-2 scans several roots and merges them, first match wins on name collisions:

Scanning also probes other dotted directories at the repo root for a skills/ subfolder, so a skill set you already keep for another tool is picked up without copying it; noisy directories such as .git, .cache, .venv, .vscode and package manager caches are skipped. The embedded built-ins that ship with every build are create-skill, create-rule, create-orgii-agent, setup-repo, manage-skills, and manage-agents-and-orgs.

How an agent discovers and loads a skill

Three mechanisms run together.

1. Per-turn listing. Every enabled, available skill contributes one line — name, source, description — to a listing attached to the turn. The instructions tell the model to scan the descriptions, pick at most one clearly-applicable skill, read its SKILL.md, then follow it. Bodies are not inlined, so the prompt cache stays stable.
2. Always-on manifest. Skills with always: true get a separate # Active Skills section listing name, source, description, and the SKILL.md path. The body is still read on demand.
3. Prefetch. At turn start ORG-2 fires a side-query that shows the model only the skill names and descriptions plus your latest message, and asks which are relevant. Up to three selected skills have their full SKILL.md inlined under a # Prefetched Skills heading, tagged with source and path so the model does not go looking for the file again. The side-query runs in the background: the main loop starts immediately and picks up the result on whichever iteration it has settled. If it fails or returns NONE, the turn falls back to the plain listing.

You can also invoke a skill directly. Type / in the composer to open the slash menu, which groups skills by where they came from — ORGII Skills, Cursor Skills, Claude Skills, or the repo folder name for repo-scoped ones.

How skill loads look in the trajectory

A skill load is a read_file call on a SKILL.md path, so it appears in the trajectory as a file-read block — but ORG-2 recognises the path shape and relabels it. Instead of a filename you see the skill name with a briefcase icon, labelled Using skill while it runs, Use skill on success, Failed to use skill on error. Prefetched skills produce no read block, because their content was already injected into the prompt.

Browsing and installing skills

Open Integrations, then the Skills, MCPs & Plugins category, and the Skills tab. It has two views:

• Installed — everything the scanner found, with source, path, dependency status, token cost, and per-skill enable/disable and delete.
• Discover / Browse — search the public skills.sh directory. Results show downloads, stars, and version; Install downloads the skill snapshot and writes it into ~/.orgii/skills/<name>/. You can also paste a skills.sh id in the form owner/repo/skill.

Installed hub skills keep a .skills-sh-detail.json next to their SKILL.md recording the slug and snapshot hash, which is what lets ORG-2 report Update available and re-download in place. Import skills from other apps scans your local agent tool folders and copies detected skills in.

Writing your own skill

You can write the files by hand, or ask an agent to — /create-skill and /manage-skills are built in and cover the whole lifecycle. From the UI:

1. Go to Integrations → Skills, MCPs & Plugins → Skills and choose Create Skill.
2. Set Name (kebab-case, unique across all scanned scopes) and Description. Write the description in third person, include both what it does and when to use it, and name concrete trigger terms.
3. Pick a Scope: User writes to ~/.orgii/skills/, Repo-specific to <repo>/.orgii/skills/.
4. Write the Content — the SKILL.md body in markdown. The Preview tab shows the rendered result and a token estimate.
5. Declare Required binaries and Required env vars if the skill shells out. Add Bundled files for scripts, references, and assets; scripts are executed but never loaded into the context window.
6. Optionally set Always active to pin the skill into every prompt. Leave it off unless it applies to every turn.

Changing the scope of an existing skill moves the whole folder, so bundled files follow it.

Scoping skills to a project, an agent, or an org

Scope works at three levels, and they compose:

• Project. A skill in <repo>/.orgii/skills/ is only loaded when a session is working in that repo. This is the right place for conventions the whole team should share, because the skill is committed alongside the code.
• User. A skill in ~/.orgii/skills/ is available in every project on your machine.
• Agent. Each agent definition carries a skills config with an include whitelist, an exclude list, and extra source directories. When include is non-empty, only those skills are listed for that agent. Toggling a skill from an agent's Skills section writes to that agent's exclusion list; toggling from the Integrations hub disables it globally, for every agent. Disabled always wins over an include whitelist.

Two further switches: include-agent / exclude-agent in a skill's own frontmatter let the skill declare which agents may see it, and the per-agent Auto load workspace skills, MCPs, and plugins toggle turns off repo-sourced resources for an agent while leaving user-level ones in place. Because agents are grouped into orgs, setting the skills config on the parent of an org's template chain is how you give a whole org the same skill set — a child definition's skills config, if it supplies one, replaces the parent's rather than merging with it.

Next steps

• Agents — agent definitions, org structure, and where the skills config lives
• Memory — the sibling system for cross-session knowledge, which uses the same prefetch machinery
• Tools — the built-in tools a skill's instructions can call
• Projects — how a repo becomes a workspace with its own .orgii/ directory