# Skills

import ComparisonTable from "@docs/ComparisonTable.astro"

A **Ren skill** is a reusable, versioned capability an [agent](/docs/deep-dives/concepts/agents/agents/) can invoke: a discrete ability like "summarize a document," "query a CRM," or "run a security scan."

## Ren skills vs. agent commands

A coding agent like Claude Code or opencode may have its own slash commands or skills: local shortcuts defined in a config file, with no versioning, sharing, or credential management. A **Ren skill** is different: it lives on the server, is versioned independently, can be shared across agents and organizations, and declares the credentials it needs. In these docs, "skill" always means the Ren primitive.

## What a skill contains

Every skill bundles three things:

1. **Interface**: the inputs it accepts and outputs it produces, so an agent knows what to pass and what to expect.
2. **Instructions**: the prose or code that runs when the skill is invoked.
3. **Required credentials**: the secrets it needs at runtime, supplied from a [vault](/docs/deep-dives/concepts/stores/vault/) so the skill never handles raw secrets.

### The SKILL.md manifest

Every skill has a `SKILL.md` file at its root. Its frontmatter declares:

- **`name`**: a hyphen-case identifier, 1 to 64 characters (e.g. `search-crm`).
- **`description`**: a human-readable summary.
- **`license`** _(optional)_: the license the skill is published under.
- **`allowed-tools`** _(optional)_: tools the skill is permitted to use.

The body holds the skill's instructions: the guidance the agent follows while the skill runs.

## Versions

Skills use **semver**, starting at `0.0.1`. Each version carries its own source files, supplied either as an uploaded archive or as a reference into a Git repository (a repo URL, optional ref, and optional sub-path).

When an [agent](/docs/deep-dives/concepts/agents/agents/) attaches a skill, it can pin a specific version or track the latest. Pinning gives stability; tracking latest means updates apply automatically. Choose based on how sensitive the workflow is to changes.

## Required credentials

A skill declares the secrets it needs as named slots (for example `SALESFORCE_API_KEY`), each with an optional description. These are a contract, not the secret itself. When you attach the skill to an agent, Ren checks the agent's [vault](/docs/deep-dives/concepts/stores/vault/) for every declared credential and fails fast with a clear message if any are missing.

## Scopes and publishing

A skill has a [scope](/docs/deep-dives/concepts/sharing/scopes/): **private** (just you), **org** (your organization), or **public** (the [registry](/docs/deep-dives/concepts/sharing/registry/)). Publishing is one-way: a public skill can't be unpublished, only deprecated, because other agents may depend on it.

## Skills, agents, and MCPs

<ComparisonTable
  columns={[
    { id: "skill", label: "Skill", highlight: true },
    { id: "agent", label: "Agent" },
    { id: "mcp", label: "MCP" },
  ]}
  rows={[
    {
      feature: "Role",
      values: { skill: "What the agent does", agent: "Who reasons and orchestrates", mcp: "What the agent can access" },
    },
    { feature: "Reasoning loop", values: { skill: false, agent: true, mcp: false } },
    { feature: "System prompt", values: { skill: false, agent: true, mcp: false } },
    { feature: "Stateful", values: { skill: false, agent: true, mcp: false } },
    { feature: "Invoked by", values: { skill: "An agent", agent: "A user or trigger", mcp: "An agent (tool call)" } },
    { feature: "Schedulable", values: { skill: false, agent: true, mcp: false } },
  ]}
/>

An **agent** decides what to do. **Skills** are the actions it can take: self-contained procedures it carries and runs. **MCPs** are the external services it can reach. An agent might use a skill to "draft a pull request" and an MCP to "read from GitHub": the skill provides the procedure, the MCP provides the access.

## CLI commands

```bash
ren skills create ./my-skill --name "My skill"   # upload a folder containing SKILL.md
ren skills versions create <skillId> ./my-skill  # add a version from a folder
ren skills search                                # search the registry
ren skills list                                  # list skills visible to you
```

For the full reference, see the [CLI docs](/docs/developers/cli/). For a walkthrough, see [Create a skill](/docs/guides/build-and-run/create-a-skill/).