# Skills Library

> A library of reusable procedures for your agents: each skill is a name, a "Use when..." description that tells the agent when it applies, and a markdown body with the steps (review checklist, migration pattern, accessibility audit, framework conventions).

- Area: Desktop, mobile and web
- Plans: All plans
- Last checked against the product: 2026-09-29
- Web page: https://agentsroom.dev/docs/skills-library

## What it does

A library of reusable procedures for your agents: each skill is a name, a "Use when..." description that tells the agent when it applies, and a markdown body with the steps (review checklist, migration pattern, accessibility audit, framework conventions). Unlike a prompt, a skill is loaded on demand when it is relevant, and it stacks in layers: a project baseline every agent of the project inherits, the default skills of a given agent, the zone skills of the folder the project sits in, and the selection pinned on a single backlog ticket. Skills use the Claude SKILL.md format natively and export to Cursor, Windsurf, Codex, Aider and plain markdown, so one library serves every runtime.

## Where to find it

- Inside a project: dock item **Skills library** (group **Knowledge**, "Attached skills"). Modal with **All skills**, folders, a **Community** tab, **Graph view** and **Import from disk**.
- Project settings > Agents > **Project skills** (the baseline).
- Agent editor: **Default skills**.
- Folder settings > Knowledge > **Zone skills**.
- Backlog ticket editor: the **Skills** field with **Merge** / **Replace** mode.
- Command palette (Cmd K / Ctrl K): the "Skills" group.

## How to use it

1. **Create first skill** or the new skill button: a slug **Name**, the **Description** trigger (the most important field, phrase it "Use when..." or "Use to..."), the **Body**, tags, a folder. Options: **Personal skill** (hidden from teammates), **Attached agents only** (hidden from the library agents browse over MCP, served only where attached), **Share with the community**, and bundled files next to the SKILL.md.
2. Attach it: to the project baseline (Project settings > Project skills), to an agent (**Default skills**), to a folder (**Zone skills**), or to one ticket. Bodies are injected into the agent's prompt when the task starts, from the widest layer to the narrowest. A ticket in **Replace** mode uses only its own list.
3. Reuse what you already wrote: **Import from disk** scans `.claude/skills`, `.cursor/rules`, `.windsurf/rules` in the project and your home, with badges per origin; re-imports update rather than duplicate. Nothing is ticked when the list opens (since 2026-09-29: a machine can hold hundreds of skills and an import cannot be undone), and **Select all** leaves out the ones already in your library unchanged.
4. Export to another runtime: **Save to Claude / Cursor / ...** on a card picks the **Target runtime** and **Scope** (project or user home) and writes the files where that tool reads them.
5. **Community**: the tab browses the skills other AgentsRoom users have published, searchable inside the app and filtered by category. **Add** asks where the copy should land (this project shared, this project personal, or global). To publish one of yours, fill its **Description** and **Category** and turn on **Share with the community** in the editor; a human reviews it before it appears. See [Community Catalog](https://agentsroom.dev/docs/community-catalog.md).
6. **History** (editor, existing skill): every save that changes a skill (body, description, tags, bundled files) keeps the previous version. The list shows each version's author and date, the selected one is compared line by line with the current body, and **Restore this version** loads it in the editor: save to keep it, the current state stays in the history.
7. **Git source** (editor): enter a repository URL (https://, ssh:// or git@host:owner/repo.git), an optional branch or tag, and the subfolder holding `SKILL.md` when one repository contains several skills. **Fetch** / **Update** clones it shallowly into a machine-local cache (`~/.agentsroom/skill-sources/`, never inside your project), reads `SKILL.md` and its sibling files, and shows the result in the editor; saving keeps the previous version in the history. **Unlink** removes the link. The commit hash and date of the last fetch are shown next to **Git source**.
8. Search spans project and global (**Search globally**, **Search scope**); **Copy to <scope>** moves a skill between libraries.

## Settings

- `defaultSkillIds` (project, Project settings > Agents > Project skills): the project baseline every agent inherits.
- `ignoredAgentDefinitions` (project): agent definition files of the repo to leave out.
- Per agent: **Default skills** in the agent editor. Per folder: **Zone skills** (global skills only, accumulating down the chain). Per ticket: the **Skills** field and its **Merge** / **Replace** mode.

## Agent tools (MCP)

- `skills_list`: project and account libraries, with the trigger description, scope, tags and folder; agents check it before starting a task.
- `skills_get`: the full body of one skill, looked up by id or by name, case, spaces and punctuation ignored ("PM Playbook" = "pm-playbook"; a team boot prompt lists required skills by name, so no `skills_list` round-trip is needed); a name that matches nothing answers with the closest names and their ids; an "attached agents only" skill is returned only to the agents it is attached to.
- `skills_save`: create or update a skill by name (upsert, same name matching as `skills_get`; an updated skill keeps its name); the agent must ask you first.

## Providers

All providers: skills are injected as text in the agent's prompt, so any CLI reads them. Storage is the Claude SKILL.md format; the export menu compiles for Cursor, Windsurf, Codex, Aider and plain markdown.

## Mobile

Version history: the skill editor has **Version history** (list, body of a version, **Restore this version**); the restore is applied by the connected desktop. The git source is desktop-only (the clone runs on the computer).

Present: the **Skill library** sheet lists project and global skills with search, **New skill**, edit (including **Attached agents only** and personal), **Send to terminal** and **Share with team**; skills can be attached to a task from the phone. Library content syncs through the end-to-end encrypted relay.

## Limits

- Whole skill bodies go into the prompt at launch: a large baseline is paid by every agent on every launch, so keep baselines short.
- Resumed sessions do not replay the system prompt, so a skill added afterwards applies at the next launch.
- Agents launched from the phone do not currently receive the project or folder baselines (known gap).
- Publishing to the community catalog needs a signed-in account and a description; submissions are scanned for credentials, moderated, then translated into every app language. Browsing and installing need no account and no plan.
- Project skills sync to teammates through your AgentsRoom account; personal skills stay on your machine.
- History keeps the last 50 versions of each skill, needs a signed-in account (versions are recorded by the server), and moving a skill between folders is not a new version. Team-shared skills have no history.
- Git source: a credential inside the URL is refused; access relies on the computer's own git setup (SSH key or credential helper). Updating is an explicit click, never a background sync. An existing skill keeps its library name when updated.

## Common questions

- **Skill or prompt?** A prompt is text you send once. A skill has a trigger and is loaded when relevant, following the agent across tasks.
- **Does it only work with Claude Code?** No: storage is SKILL.md, but export covers Cursor, Windsurf, Codex, Aider and markdown, and injection works with every CLI.
- **How are skills delivered?** Injected in the agent's initial prompt as native SKILL.md blocks when the task starts.
- **Can a skill apply to a whole project?** Yes, via **Project skills**; to a whole client, via a folder's **Zone skills**.
- **How do I keep a specialised skill away from other agents?** Tick **Attached agents only**.
- **I overwrote a skill by mistake.** Open it, click **History**, pick the version before your change and **Restore this version**, then save.
- **One git repository holds several skills.** Create one skill per folder, each with the same URL and its own **Subfolder**.
- **After an import from disk, some descriptions read `>-` instead of the real text.** Fixed on 2026-09-29: a description written on several lines in the file's front matter was read as that YAML marker. Re-import the skill (or the agent) to get its real description; nothing else was affected.
- **Import from disk used to arrive with everything pre-ticked.** Changed on 2026-09-29: it now opens with nothing selected, so an import is always a choice you made.
- **An agent saved a skill with `skills_save`, attached it in `agents_spawn` and got `skillIds=<id> (skills-missing)`, although `skills_get` finds it.** Fixed after 1.173.0: the skill was on the server but not yet in the desktop's in-memory libraries, which were only refreshed when a library modal opened or an agent launched. The libraries are now reloaded before the attached ids are checked, for `agents_spawn` and `agents_save` alike.
- **An agent got "not found" from `skills_get` with a skill's name, while its id worked.** Fixed after 1.191.0: a skill named from the phone keeps the name as typed ("PM Playbook"), and only that exact spelling matched, so an agent writing "pm-playbook" (as a team step instruction may) missed it. Names now match ignoring case, spaces and punctuation, and a name that still matches nothing gets the closest names with their ids.

## Related

- [Prompt Library](https://agentsroom.dev/docs/prompt-library.md): imperative one-shot inputs, versus procedures.
- [Scope Levels](https://agentsroom.dev/docs/scope-levels.md): folder, project, agent and ticket layers.
- [Project Memory](https://agentsroom.dev/docs/project-memory.md): knowledge the agents write, in the same modal family.
- [Backlog Task Board](https://agentsroom.dev/docs/backlog-task-board.md): pinning skills on a ticket.
- [Team Shared Library](https://agentsroom.dev/docs/team-shared-library.md): one library for a whole Team plan.
- [Community Catalog](https://agentsroom.dev/docs/community-catalog.md): publishing a skill and installing other people's.
- [Start on the ticket in the agent's name](https://agentsroom.dev/docs/ticket-name-autostart.md): an agent named after a ticket key starts on it with a first message, which is what triggers the intake skill that fetches the ticket.