# Skills

import Screenshot from "@docs/Screenshot.astro"
import SurfaceTabs from "@docs/SurfaceTabs.astro"
import AskRen from "@docs/AskRen.astro"

A skill is a reusable set of instructions for a type of task. Its folder contains `SKILL.md` and optional supporting files, like templates or scripts. Ren reads the description in every chat, but loads the full instructions only when the request needs them.

Example `SKILL.md` for release notes:

```md
---
name: release-notes
description: Write release notes from merged pull requests. Use when asked for release notes or a changelog.
---

Group changes under Features, Fixes, and Internal.
Link each item to its pull request.
Skip dependency bumps unless they fix a security issue.
```

## Skill or instructions?

- **Use project [instructions](/docs/concepts/projects/#instructions)** for rules that apply to every chat in a project, such as tone or which repository to work in. Ren reads them on every turn.
- **Use a skill** for a procedure that only some requests need, or one you want in several projects.
- **Use the chat prompt** for a one-off request. If you find yourself pasting the same steps again, make them a skill.

## Create a skill

`SKILL.md` needs these frontmatter fields:

- `name`: up to 64 characters, using lowercase letters, digits, and single hyphens.
- `description`: up to 1,024 characters explaining when to use the skill.

An uploaded skill can contain up to 10 MB of files.

<SurfaceTabs>
<Fragment slot="app">

1. Open **Marketplace → Skills** and select **Add skill**.
2. Choose where to add it: your organization, or a project. Choosing a project also adds the skill to it.
3. Drop a skill folder or a `SKILL.md` file into the box, or paste the `SKILL.md` content.
4. Select **Create skill**.

<Screenshot
  shot="skills/marketplace"
  alt="Marketplace Skills with the New skill dialog open, showing the destination and the drop area for a skill folder"
/>

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Create a skill called release-notes from the rules I just gave you, and add it to this project." />

Ren writes the `SKILL.md` for you.

</Fragment>
<Fragment slot="cli">

```sh
ren skills create ./release-notes
```

Add `--visibility private` to keep it to yourself. To use a git repository instead of a folder, see [Sources](#sources).

</Fragment>
</SurfaceTabs>

## Edit a skill

Edit uploaded skills through Ren or the CLI. Each edit creates a new version. The app can't edit skill files.

<SurfaceTabs>
<Fragment slot="ask-ren">

<AskRen prompt="Update the release-notes skill to also list breaking changes first." />

Projects pick up the new version in their next chat.

</Fragment>
<Fragment slot="cli">

```sh
ren skills pull release-notes ./release-notes
ren skills versions create <skill-id> ./release-notes --version minor
```

`--version` takes `major`, `minor`, `patch`, or an exact version such as `1.4.0`.

</Fragment>
</SurfaceTabs>

## Delete a skill

Deleting a skill archives it, so it stops loading in every project that uses it.

<SurfaceTabs>
<Fragment slot="ask-ren">

<AskRen prompt="Delete the release-notes skill." />

</Fragment>
<Fragment slot="cli">

```sh
ren skills archive <skill-id>
```

</Fragment>
</SurfaceTabs>

To take a skill out of one project without deleting it, see [Add a skill to a project](#add-a-skill-to-a-project).

## Sources

- **Uploaded files.** You upload a folder. Ren stores a copy, and each change is a new version. Use this for skills you write and edit with Ren. The app creates uploaded skills only.
- **A git repository.** You point Ren at an `https://` repository, with an optional branch, tag, or commit and a path to the skill's folder. Ren fetches the files itself, up to 50 MB. Use this for skills you maintain in git: when you track a branch, Ren picks up new commits without a new version.

Create a git skill with `ren skills create --source` followed by the source as JSON:

```sh
ren skills create --source '{"type":"git","url":"https://github.com/acme/skills","ref":"main","path":"release-notes"}'
```

Change its repository, branch, or path later with `ren skills sources update`.

## Versions

Uploaded skills start at `0.0.1`, and each edit creates a version. Git skills follow their repository. Projects use the latest version unless you pin one with `ren projects skills add --skill-version-id`. Archiving the latest version returns projects to the previous version.

## Visibility

| Visibility   | Who can see and use it             |
| ------------ | ---------------------------------- |
| Private      | Only you                           |
| Organization | Every member of your organization  |
| Published    | Anyone on Ren, in any organization |

Anyone who can see a skill can read its instructions and supporting files. A skill you add to a project in your personal space is private. A skill you add to your organization, or to a project in a shared space, is visible to the organization.

To share a private skill with your organization, run `ren skills promote <skill-id>`. Publishing (`ren skills publish`) lists it for everyone and can't be undone.

## Add a skill to a project

<SurfaceTabs>
<Fragment slot="app">

1. Open **Marketplace → Skills** and select the skill.
2. Select **Add**, choose a project, and select **Add**.

If the skill needs a credential, Ren asks you to connect it before adding.

<Screenshot
  shot="skills/add-to-project"
  frame="detail"
  alt="A skill's Add menu searched down to the Storefront project in the General team"
/>

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Add the release-notes skill to the Engineering project." />

</Fragment>
<Fragment slot="cli">

```sh
ren projects skills add <project-id> --skill-id <skill-id>
```

</Fragment>
</SurfaceTabs>

To remove a skill from a project, open the capabilities menu in the project's chat composer and select its trash icon, run `ren projects skills remove`, or ask Ren.

## FAQ

<details>
<summary>What happens when two skills have overlapping names or instructions?</summary>

If project skills share a `name`, Ren loads only the skill created first. Skills with different names but overlapping instructions both load, and Ren picks between them by their descriptions, so make each description say when to use that skill.

</details>

<details>
<summary>Can I bring my Claude Code or Codex skills?</summary>

Yes. Ask your coding agent, with the Ren plugin installed, to push them to Ren. See [Migrate from Claude Code](/docs/migrate/claude-code/) or [Codex](/docs/migrate/codex/).

</details>