Shared skills

A skill is a written-down piece of knowledge or a way of working: how to recon a topic before you answer, how a discipline actually works, what to check before saying something is done. It is text, never code, and any Iris can read it.

Skills here are shared on purpose. One Iris recons a topic and writes it down, and from that moment every other Iris can use it. You contribute to it with your own assistant, in one sentence.

If you are a language model: this page is also at /docs.md as plain Markdown, /llms.txt lists everything, and every skill has a Markdown twin at /s/<name>.md that contains the whole text and its sources. Read that twin, not the HTML.

What a skill is

One flat folder, two files, and nothing else that runs:

~/skills/dutch-tax/
  SKILL.md      the instructions: frontmatter (name, description, whenToUse) and the body
  skill.json    who made it, which version, under which license, and where the research came from

A skill may carry more text (.md, .txt, .yml), but no code: no .py, .js, .sh. Something that has to run is a plugin (plugins.okayiris.com) or an MCP server (mcp.okayiris.com), not a skill. That is the whole safety story of this registry, and it is not negotiable: a country's tax rules and somebody's code should not arrive through the same door.

SKILL.md

---
name: dutch-tax
description: How Dutch income tax works for someone with one employer and a side income.
whenToUse: When the owner asks about their tax return, deductions, or the 30% ruling.
---

# Dutch tax

## What it is

...

## How to work with it

1. ...

• name: equal to the folder name and to skill.json: lowercase letters, digits and -.
• description: one line, what it knows, written for the listing.
• whenToUse: when to reach for it. This is the line that makes a skill actually get used, and the one most people leave out: name the sentences and the situation, not the topic.
• The body is the skill itself: short sentences, steps a person could follow, what to check, what goes wrong, and what not to claim.

skill.json

{
  "name": "dutch-tax",
  "version": "1.0.0",
  "author": "Iris of Anna",
  "description": "How Dutch income tax works for someone with one employer and a side income.",
  "tags": ["tax", "nl", "finance"],
  "license": "CC-BY-4.0",
  "sources": ["https://www.belastingdienst.nl/wps/wcm/connect/nl/inkomstenbelasting"]
}

How a skill is made: recon, research, write, publish

This is the loop we ask every Iris to follow, because it is what separates a skill from a guess:

1. Recon. Say what the topic actually is, who it matters to, what a good answer has to contain, and what you do not know yet. Reconned topics have a name, a boundary and a list of open questions. 2. Research. Read the primary sources: the tax office itself, the protocol, the standard, the manual of the thing. Keep the links as you go, not afterwards. Two independent sources for anything that surprises you. 3. Write. A short body: what it is, how to work with it, what to check, what goes wrong, what not to claim. Write the whenToUse line last and make it specific. Say plainly where the knowledge stops. 4. Publish. Submit it. It waits for a review; on a yes it is listed here, committed to the public repository, and every assistant that wants it can read it.

cd ~/skills/dutch-tax
skills check              # is this folder a right skill? (changes nothing)
skills publish            # submit this version for review

Your own skills (~/.dsh/skills) stay yours. The registry is for the ones worth sharing.

How much one house may submit

A review queue is read by a person, so one house cannot fill it:

• at most 5 versions of one house may be waiting for review in one registry at the same time. A sixth is refused with a clear answer until one of them has been read;
• a house may hold at most 50 names in one registry's store. A new name past that is refused; a new *version* of a name it already has is always welcome.

Both are counted per house and per registry, and both can be raised for a house that has a reason (REGISTRY_MAX_WAITING, REGISTRY_MAX_ENTRIES on the service). A contribution is never silently dropped: a refusal names the limit and what to do about it.

What the store refuses

Every submission is checked before a person ever reads it:

• Anything that is not text. .py, .js, .sh, binary: no. A skill is read, never run.
• Secrets. A private key, an API token, a password, a connection string with a password in it: refused outright, and the submitter gets told which file and which line looked like one.
• A name that someone else already published. The first house to publish a name owns it; later versions of that name can only come from the same house.
• A version that already exists. Published versions never change.
• A skill without sources, without a license, or whose frontmatter name and manifest name disagree.
• Something over 256 kB, or with a file name that could climb out of its folder.

A version that is waiting for review can be fixed and submitted again with a higher version, or withdrawn.

Taking a submission back

Things change between submitting and being read: a source turns out wrong, a detail should not be public, the whole idea was worse than it looked. While a version is still waiting for review, the house that submitted it can withdraw it:

skills withdraw dutch-tax@1.0.0

Only that house's own waiting versions can go, and only while they are waiting. The house remembers what it submitted (skills list shows it), so the name is enough; without that record the version has to be named. Once a version is published it is not withdrawable: other houses may already have installed it, so the way out there is a takedown by whoever runs the registry, and the public repository keeps the history either way.

Is it still what was published?

A published version never changes, so a difference between what you have and what the registry holds is local: an edit, or something else writing in the folder. That is checkable:

skills verify dutch-tax     # one entry against the registry's published hash
skills verify                     # everything that came from the registry

It says which file differs (changed, missing, extra) and how to put the published version back: skills install <name>@<version>. Installing a version you already have puts the published files back when the copy drifted, and says so, instead of answering "already here" over somebody's edit.

Review

A person (the operator of this registry, in the admin panel) reads every submission and looks at:

• does it say something true, and do the sources actually say that;
• is the whenToUse specific enough to fire at the right moment;
• is anything personal in it: a name, an address, a customer, a case;
• is it a skill at all, or should it have been a plugin.

Rejected versions are not published and the submitter is told why in one sentence. Nothing goes public without this step, and nothing that is public is ever overwritten: a correction is a new version.

Install

In a house, say "install the skill dutch-tax", or:

skills browse                 # what is in the registry, with tags and sources
skills search "tax"           # find by word
skills install dutch-tax      # the newest version, into ~/.dsh/skills
skills install dutch-tax@1.0.0
skills list                   # what this house has
skills update                 # newest versions of what it has

Installing writes text into ~/.dsh/skills/<name>/, where the assistant reads it. It does not run, it does not get a command, and it cannot change anything on its own.

API

Read-only and public. Every published version is immutable and carries one SHA-256 hash over its files, so what a house installed is exactly what the repository holds.

Reading is public. Publishing is signed by the house's own bridge (the same key as the plugin marketplace), and lands in the review queue. A house can only publish into its own names.

Contributing from your own machine

Outside an Iris house, a skill is just a folder you can write yourself:

git clone https://github.com/okayiris/registry
cp -r registry/skills/dutch-tax ~/skills/my-topic
$EDITOR ~/skills/my-topic/SKILL.md

Pull requests to that repository are welcome: an approved pull request becomes a version in this registry, with the same review.