# Skills

- **Status:** current on 2026-11-06, for version 0.
- **Related documents:** [Surface for agents](https://surface.solenovis.com/docs/ai.md), [plugins](https://surface.solenovis.com/docs/plugins.md), [MCP server](https://surface.solenovis.com/docs/mcp-server.md)

A skill is a Markdown file with a name, a description and instructions. An agent reads the description first. It reads the instructions only when a task needs them, so a skill costs little context.

---

## 1. The skills of Surface

| Skill | When the agent uses it | What it gives |
|---|---|---|
| `surface-code-writer` | It creates, edits or analyzes a `.surf` or `.surfs` file | The tools of the MCP server, the order in which to call them, and the commands without the server |
| `surface-best-practices` | It writes Surf code | The rules of the files, the declarations, the traits, the formats of `Locale`, the markup and the styles that differ from TypeScript, Rust, Svelte and Tailwind CSS |

The files are in `plugins/surface/skills` of the repository. This website serves each one:

- [`/SKILLS.md`](https://surface.solenovis.com/SKILLS.md) lists the skills, with a link to each file.
- `/skills/<name>/SKILL.md` is one skill, for example [`/skills/surface-best-practices/SKILL.md`](https://surface.solenovis.com/skills/surface-best-practices/SKILL.md).

---

## 2. Install a skill

The [plugin](https://surface.solenovis.com/docs/plugins.md) installs both skills. To install a skill without the plugin:

1. Make a folder with the name of the skill in the folder of skills of your agent. For Claude Code, the folder is `~/.claude/skills` for each project, or `.claude/skills` for one project.
2. Download the file into that folder:

   ```bash
   mkdir -p ~/.claude/skills/surface-best-practices
   curl -fsSL https://surface.solenovis.com/skills/surface-best-practices/SKILL.md -o ~/.claude/skills/surface-best-practices/SKILL.md
   ```

3. Do the same steps for `surface-code-writer`.

An agent with no support for skills can read the same file as an instruction file.

---

## 3. A skill and the MCP server

A skill gives rules. It cannot know each name of the language. The MCP server checks each name with the compiler. So use both: the skill tells the agent to call `check_code`, and `check_code` finds what the rules miss.