# Create a skill

import { Steps } from "@astrojs/starlight/components"
import Prereqs from "@docs/Prereqs.astro"
import UiWalkthrough from "@docs/UiWalkthrough.astro"
import ClientTabs from "@docs/ClientTabs.astro"

Create a [skill](/docs/deep-dives/concepts/agents/skills/), upload its archive, and attach it to an agent version so the agent can load it at runtime. A skill is a packaged capability (a `SKILL.md` with frontmatter, plus optional scripts and assets) that an agent loads on demand when a task makes it relevant.

<Prereqs>
  - A Ren account and organization - [The CLI installed](/docs/developers/cli/) and paired, or a personal access token
  for API calls - An [agent](/docs/deep-dives/concepts/agents/agents/) version to attach the skill to
</Prereqs>

## Author the SKILL.md

A skill starts with a `SKILL.md` file in the root of its archive. The frontmatter defines metadata; the body is the instruction text the agent reads.

```markdown
---
name: summarize-commits
description: Summarize recent git commits into a changelog entry.
requiredCredentials:
  - name: GITHUB_TOKEN
    description: Personal access token with repo read scope
---

You are a commit summarizer. When given a repository path and a date range:

1. Run `git log --oneline --since=<start> --until=<end>`.
2. Group related commits.
3. Write a changelog entry in Keep a Changelog format.
```

The `name` must be hyphen-case, 1 to 64 characters. The `description` is 1 to 1024 characters. `requiredCredentials` is an optional array of `{ name, description? }`. Credential names use `UPPER_SNAKE_CASE` and are resolved from the agent's vault at runtime, never stored inline.

The first version defaults to `0.0.1` if you don't specify one.

## In the UI

<UiWalkthrough>
  {/* TODO(demo): screen recording – creating a skill, uploading its archive, and attaching it to an agent version, ~12s loop */}
</UiWalkthrough>

<Steps>

1. Open **Skills** in the sidebar and click **New skill**.

2. Enter a name, then upload your skill folder (the one containing `SKILL.md`) to create the first version.

3. Open the agent you want to give the skill to, select a version, and add the skill under **Skills**.

4. Save. The next session on that agent version loads the skill on demand.

</Steps>

## Upload and attach programmatically

Skills are uploaded as archives (a `.tar.gz` or a set of files). After creating the skill and a version, attach it to an agent version so the agent can use it.

<ClientTabs clients={["cli", "api"]}>
  <Fragment slot="cli">
    <Steps>
      1. Create the skill:

         ```bash
         ren skills create --name "summarize-commits"
         ```

         The response includes the skill `id` (e.g. `skl_abc123`).

      2. Create a version with your archive:

         ```bash
         ren skills versions create skl_abc123 \
           --version 0.0.1 \
           --archive ./skill-folder/
         ```

         You can also point to a Git ref instead of uploading a local archive:

         ```bash
         ren skills versions create skl_abc123 \
           --version 0.0.1 \
           --source '{"type":"git","url":"https://github.com/example/skill.git","ref":"main"}'
         ```

      3. Attach the skill version to an agent version:

         ```bash
         ren agents versions skills add agt_abc123 1.2.0 \
           --skill-id skl_abc123 \
           --skill-version 0.0.1
         ```
    </Steps>

    Use `ren skills list` to see all your skills and `ren skills versions list <skillId>` to inspect versions.

  </Fragment>
  <Fragment slot="api">
    <Steps>
      1. Create the skill with `POST /api/skills`:

         ```bash
         curl -X POST https://api.renai.build/api/skills \
           -H "Authorization: Bearer $REN_PAT_TOKEN" \
           -F "name=summarize-commits" \
           -F "files=@./SKILL.md"
         ```

         The response includes the skill `id`.

      2. Create a version with `POST /api/skills/{id}/versions`:

         ```bash
         curl -X POST https://api.renai.build/api/skills/skl_abc123/versions \
           -H "Authorization: Bearer $REN_PAT_TOKEN" \
           -F "version=0.0.1" \
           -F "files=@./SKILL.md" \
           -F "files=@./scripts/summarize.sh"
         ```

      3. Attach the skill to an agent version with `POST /api/agents/{id}/versions/{version}/skills`:

         ```bash
         curl -X POST https://api.renai.build/api/agents/agt_abc123/versions/1.2.0/skills \
           -H "Authorization: Bearer $REN_PAT_TOKEN" \
           -H "Content-Type: application/json" \
           -d '{"skillId": "skl_abc123", "skillVersion": "0.0.1"}'
         ```
    </Steps>

  </Fragment>
</ClientTabs>

Skill scope determines visibility: **private** (default, only your org), **org** (all org members), or **public** (published to the registry). Publish with `ren skills publish skl_abc123` or `POST /api/skills/{id}/publish`.