Skills

A skill is a set of instructions the agent follows for a particular kind of task, such as building a Word document, writing release notes or following your team's deploy steps. Skills cost little context: the agent sees a one-line description of each and reads the full instructions only when a task needs them.

What a skill looks likeCopy Anchor Link

A skill is a folder containing a SKILL.md file. It can also hold scripts, templates or reference files that the instructions point to.

release-notes/
├── SKILL.md
└── template.md

SKILL.md starts with YAML frontmatter, followed by the instructions in Markdown:

---
description: Write release notes from merged changes since the last tag, using template.md.
tags: [release, changelog]
---
# Release notes

1. Run `git describe --tags --abbrev=0` to find the last tag.
2. List the changes since that tag with `git log <tag>..HEAD --oneline`.
3. Fill in `template.md` in this folder. Group changes as Added, Changed and Fixed.
4. Don't invent changes that aren't in the log.

Write the description for the agent: say what the skill does and when to use it, because that line decides whether the agent opens the skill.

Where Andromity looks for skillsCopy Anchor Link

If ANDROMITY_CONFIG_DIR is set, your skills folder is $ANDROMITY_CONFIG_DIR/skills and the two ~/.gemini folders are not used.

The folders are checked in the order above, and the first skill with a given folder name wins. A project skill therefore overrides one of yours with the same name.

Andromity does not look in ~/.claude/skills. Copy or link those skills into one of the folders above.

How the agent uses skillsCopy Anchor Link

Andromity adds a list of skills to the agent's system prompt:

## Installed Skills
- release-notes (file: /path/to/release-notes/SKILL.md): Write release notes from merged changes since the last tag, using template.md.

The skills above are available on request. When the user names a skill (or a task clearly matches one), read its SKILL.md directly and follow its instructions exactly.

When a skill applies, the agent opens its SKILL.md with read_file and follows it. There is no separate skill tool. read_file may read inside your skill folders even though they're outside the project.

To check how much context the skill list uses, open the context indicator under the prompt box in VS Code.

Using a skill in chatCopy Anchor Link

• Name it, for example "use the release-notes skill", or describe a task that clearly matches one.
• Mention it with @. In VS Code, type @ and choose from Skills & Tools; this inserts @release-notes. In the terminal app, @ opens a skill list (↑/↓ to select, Enter to insert), and sending the message attaches the skill's path with an instruction to follow it.
• Browse them with /skills. In VS Code this shows an Agent Skills card with a Use button for each skill; in the terminal app it opens the Skills screen.

Installing skills from the catalogCopy Anchor Link

Open Settings → Skills & Packs → Browse Online Registry (in the terminal app, /skills). The catalog includes two sources:

1. Search by name, description or tag, or filter by Category and Source.
2. Select a card to read its full SKILL.md, its repository and the commit it is pinned to.
3. Under Install to, choose All projects (your skills folder) or This project only (<project>/.andromity/skills/).
4. Select Install Skill.

VS Code installs the files from the commit the catalog pins, and records the source, commit and version in .andromity-skill.json inside the skill folder. When the catalog has a newer version, the skill shows Update available and an Update button.

The catalog list is cached for 6 hours. To use your own catalog, set ANDROMITY_SKILLS_CATALOG_URL; entries from repositories other than the two above are ignored.

Writing your own skillCopy Anchor Link

1. Create a folder in your skills folder (for all projects) or in <project>/.andromity/skills/ (to share it with your team through the repository).
2. Add SKILL.md with a description and the steps.
3. The skill appears in Settings → Skills & Packs → Installed. In VS Code the agent sees it from your next message; in the terminal app, from the next new session or model or profile switch.

Keep instructions concrete: name the commands to run, the files to read, and what "done" looks like.

Removing skillsCopy Anchor Link

Select Remove Skill on an installed skill and confirm. Built-in skills can't be removed. In the terminal app, select the skill on the Installed tab and press Uninstall twice; this removes it from both your skills folder and the project's .andromity/skills/.

Skills and folder trustCopy Anchor Link

• In a folder you haven't trusted, the agent can't read any SKILL.md, so skills don't work until you trust the folder.
• Skills that come with an untrusted project are left out of the agent's prompt until you trust it, so a repository can't put text in front of the model before you've agreed to work in it.
• In VS Code, installing a skill for one project, or removing any skill, needs a trusted workspace.

Skills and project instructionsCopy Anchor Link

Skills are opt-in instructions for particular tasks. For rules that apply to every task in a repository (build commands, code style, things to avoid), use a project instruction file instead. At the start of a task, the agent is told to look in the workspace root for AGENTS.md, CLAUDE.md, .cursorrules or andromity.md and follow it. These files are read with the agent's tools, so they also need a trusted folder.