Build your own skill. An open-source skill author guide.

The fastest way to learn how Skill OS works is to write a skill. The v2 manifest is small, the rules are short, and the testing loop is local. You can ship one in an afternoon.

Here is the full path.

What a skill is

A skill is a markdown file with frontmatter. Nothing more. The body is the prompt + the reasoning frame. The frontmatter is the metadata the router uses to decide when to fire it.

A minimal skill file looks like:

---
slug: hello-skill
display_name: Hello Skill
kind: tool-skill
source: vladan-authored
source_creator: Your Name
license: MIT
tier_required: free
cost_class: light
latency_class: fast
badge_emoji: 👋
one_liner: A skill that says hello in three different tones.
intents: [greeting, small-talk]
---

You are a skill that produces a friendly greeting. The user has asked for a greeting. Produce three: formal, casual, playful. Keep each under 30 words.

That is the whole thing. Save it to fino-skills/hello-skill/skill.md (or contribute it to the open catalog), and the registry seed picks it up at the next build.

The frontmatter, fully

The required fields are:

slug: lower-kebab-case, matches the directory name
display_name: title-cased, shown on the catalog
kind: one of system, market-advisor, agent, employee, tool-skill, mcp-skill, external-workflow
source: one of vladan-authored, curated-github, curated-mcp, curated-anthropic, community
source_creator: the author name, shown on the catalog
license: one of MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, CC0-1.0, CC-BY-4.0, ISC, Unlicense, proprietary
tier_required: one of free, pro, max, ultra
cost_class: one of light, medium, heavy, premium
latency_class: one of fast, medium, slow
badge_emoji: a single emoji shown on the reply when the skill fires
one_liner: a one-sentence description shown on the catalog
intents: an array of closed-set intent strings the router uses to match

Optional fields:

notice: for derivatives of upstream open-source work. The NOTICE text from the upstream repo, preserved verbatim. Required for non-MIT derivatives.
educational_framing: true when the skill produces advice-shaped output (Stoic, Coach). Triggers an "educational reflection" banner.
disclaimer_at: an ISO date for when the skill's disclaimers need re-audit.

The body

The body is the prompt + the reasoning frame the skill uses. It is written as instruction prose, in second person, to the AI. The router does not parse it. It is loaded verbatim into the runtime context when the skill fires.

A good skill body is short, structured, and ends with an output schema. The Code Reviewer Pattern body is roughly 200 lines: 30 lines of intent framing, 80 lines of review-lens definitions, 60 lines of output structure, and 30 lines of edge-case handling. It is one of the longer bodies in the catalog.

A short skill body (Pricing Surgeon's first version) was 60 lines. It produced excellent output. Length is not quality. Structure is.

How the router picks it up

When you commit a new skill to the repository (or contribute to the open catalog), three things happen:

The build script (bun run scripts/skill-registry-seed.ts) reads the file, validates the frontmatter against the v2 schema, and writes it to the registry.
The router picks up the new intent declarations at next deploy.
The catalog page updates. The changelog page lists it.

No manual integration. No per-skill TypeScript. The skill is a markdown file the system can read and use.

Testing locally

Two paths.

Path 1: the registry seed test.

bun run scripts/skill-registry-seed.ts

This dry-runs the seed, validates every skill file, and tells you which one (if any) failed schema validation. It catches missing fields, wrong enum values, and dangling NOTICE blocks.

Path 2: the skill fire test.

Start the bot locally (bun run dev), open a Telegram channel pointed at it, and message the bot with a prompt that matches the new skill's intents. The router will fire the skill if everything is wired up. The reply will badge with the new skill's emoji.

Most skill authors test both paths before opening a PR.

Contribution rules

For the open catalog (we accept community contributions for permissively-licensed skills):

License must be one of the permissive set above. GPL is not accepted (it would force the entire catalog to be GPL-licensed).
Skills that brush against advice (medical, legal, financial, mental health) must use educational_framing: true and frame outputs as educational, not predictive.
No personally identifiable content in skill bodies (no real names of private individuals, no specific addresses, no API keys).
No competitor-product naming in skill bodies. The catalog is positive-positioning by default.
A test fixture goes in src/__tests__/skill-fire-fixtures/ showing a representative input and the expected output shape.

PRs go through the same /ship 3-lens review the first-party skills go through. Critical and High findings get fixed before merge.

What you cannot do (yet)

A skill cannot call arbitrary code. The body is a prompt; it does not execute logic. If your skill needs to call an API, you need to write an MCP wrapper for the API first (the MCP Wrapper Builder skill helps), then the skill body can call the wrapper.

A skill cannot persist state across fires. State lives in the bot's long-term memory, which is the user's domain, not the skill's. If your skill needs state, surface it through the memory layer (which has its own safety rules).

A skill cannot bypass Trust-3 or Shield-2. Even a custom skill goes through the safety gates. The gates are not opt-in for new skills; they are infrastructure.

Where to ship

The open catalog repository launches publicly soon. When it does, the URL will appear on the Skill OS overview page and in the skills changelog. Fork. Add your skill. Open a PR. We review weekly.

The fastest skills to write are the ones you needed last week and ended up doing manually. If you wrote out a list of pricing-elasticity questions yourself, that is a skill. If you templated a customer support reply for the fifth time, that is a skill. Skill OS does not need brand new ideas. It needs the work you already do made structural.

That is the bet behind shipping the schema in public.