Skip to content

Commit d018297

Browse files
n0mahdclaude
andcommitted
docs: describe the Skills settings page
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
1 parent c05239b commit d018297

2 files changed

Lines changed: 44 additions & 0 deletions

File tree

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
- [Terminal history](./user/terminal.md)
1010
- [Source control](./user/source-control.md)
1111
- [Project settings](./user/project-settings.md)
12+
- [Skills](./user/skills.md)
1213
- [Appearance and themes](./user/appearance.md)
1314
- [Keyboard shortcuts](./user/keybindings.md)
1415
- [SnapShots](./user/snap-shot.md)

‎docs/user/skills.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Skills
2+
3+
Open **Settings → Skills** on web and desktop to see which skills your agents can use. The page
4+
reads the environment and project chosen at the top of Settings, so with a remote environment you
5+
see that machine's skills. It is read-only: edit skills in your editor, or ask an agent.
6+
7+
The agents are your enabled provider instances. Two Claude instances show as two agents, each
8+
with its own config folder.
9+
10+
## Where skills live
11+
12+
Keep a repo's skills in `.agents/skills` and your own in `~/.agents/skills`. Codex, Cursor,
13+
OpenCode and Pi read both folders, and Grok reads the global one. Other agents read their own
14+
folders instead, such as Claude's `.claude/skills` and `~/.claude/skills`. Antigravity reads the
15+
project's `.agents/skills`, but not the global `~/.agents/skills`; its global folder is
16+
`~/.gemini/config/skills`. A skill reaches an agent that doesn't read the shared folder through a
17+
link or a copy in the folder it does read. The page follows links to the real folder and shows
18+
where each agent reads a skill from.
19+
20+
Each instance's config folder follows its settings: a Claude instance's config directory (or
21+
`CLAUDE_CONFIG_DIR`), `CODEX_HOME` and `GROK_HOME`. A skill in a folder that none of your enabled
22+
agents reads isn't listed. If a folder exists but can't be read, the page says so above the list
23+
instead of showing it as empty.
24+
25+
## Needs attention
26+
27+
**Needs attention** filters the list to skills that need a look. A skill is on it when:
28+
29+
- an installed and enabled agent doesn't use it. Hover the icons to see which agent. An agent
30+
loads one skill per name, the first it finds in its folders (Codex and OpenCode list every
31+
copy), so a copy that another folder shadows is not used by that agent.
32+
- the same name exists more than once with different text, in **This project**, in **Global**, or
33+
across them. These rows have a **Conflict** badge.
34+
- Claude can't read the skill's header, the YAML between the `---` lines at the top of
35+
`SKILL.md`, so it skips the skill. Quote a value that contains a colon or brackets, for example
36+
a description.
37+
38+
## Limits
39+
40+
- Only a project's top folders are read, such as `<project>/.agents/skills`, not the folders
41+
above it that some agents also read.
42+
- A skill's file list stops at 500 files, and `SKILL.md` isn't shown past 1 MB.
43+
- A `SKILL.md` that is a link to a file outside the skill's folder isn't read.

0 commit comments

Comments
 (0)