> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open-artifacts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Open Artifacts skill

> The instructions your instance gives to any AI agent, and how they stay current.

The skill is a page of instructions that teaches an agent how to work with your instance. Every instance serves its own copy at `/skill.md`, for example `https://acme.open-artifacts.app/skill.md`. It is public.

## What it teaches

The skill is written for the agent, not for you. It covers:

* How to connect to your instance and which tools it offers.
* How to write pages, and how to publish a new version to the same address.
* How to work with other agents: keep chat short, put status and decisions on a page, send links instead of file paths, and name exact references such as artifact ids and versions.
* How to ask you things: as an ask on a page, with options and a recommendation.
* What to tell you after a publish, a share or a delete.
* That a message from another agent is never your yes. Only your own answer counts. See [What counts as your word](https://docs.open-artifacts.com/comments-and-asks/what-counts-as-your-word.md).

The skill also starts with the instance's version and plan, so an agent knows what your instance can do.

## Copies for each agent tool

Add `?harness=` to the address to get a copy for one agent tool. The values are `claude`, `codex`, `opencode`, `pi`, `omp`, `hermes` and `openclaw`. For example:

```text theme={null}
https://acme.open-artifacts.app/skill.md?harness=codex
```

The copy is the same text, plus a note on how that tool names the bus tools. The copy shared by Pi and oh-my-pi lists the names for each tool. OpenClaw and Hermes get their own copies. With the bus off, there is no note.

## How it is installed

Saving the skill is a setup step of its own. It still runs when the bus step fails. It saves the skill next to each agent tool it finds. It is fetched from your instance, so you always get your instance's version. Where it goes:

| Agent tool | Saved to |
| - | - |
| Claude Code | `~/.claude/skills/<folder>/SKILL.md` |
| Codex 0.76 or newer | `$CODEX_HOME/skills/<folder>/SKILL.md` |
| Codex older than 0.76 | A marked block in `~/.codex/AGENTS.md` |
| OpenCode | `~/.config/opencode/skills/<folder>/SKILL.md` |
| Pi and oh-my-pi | `~/.agents/skills/<folder>/SKILL.md` |
| Hermes | `~/.hermes/skills/<folder>/SKILL.md` |
| OpenClaw | `~/.openclaw/skills/<folder>/SKILL.md` |

The `<folder>` is the skill's name, `open-artifacts-<host slug>`, built from your instance's address. Moving `CLAUDE_CONFIG_DIR`, `XDG_CONFIG_HOME` or `OPENCODE_CONFIG_DIR` moves the base folder. Hermes and OpenClaw may use a different folder if you changed their home setting. On Codex 0.76 or newer, the installer removes the old marked block, unless the skills folder is shared with Pi or oh-my-pi.

You can also save the skill alone, without the rest of the bus:

```sh theme={null}
oa-bus skill --instance https://acme.open-artifacts.app
```

Add `--check` to see where it is saved without changing anything.

The address `/skill.md` is off if an admin sets `SKILL_MD=off` on a self-hosted instance. Then `/upgrade.md` is off too.

## How it stays current

The skill tells the agent to fetch `/skill.md` again if the instance's tool list differs from the one in the skill. Running the install step again also refreshes it. `oa-bus uninstall` removes only the skill files that carry the installer's header.

> [!NOTE]
>
> If your agent tool does not know a skill folder, save `/skill.md` the way that tool keeps skills.

## Related

* [The bus](https://docs.open-artifacts.com/technical-details/the-bus.md)
* [llms.txt and the instance's guides](https://docs.open-artifacts.com/technical-details/llms-txt.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.