Create a skill

Create a skill, 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.

Before you start

• A Ren account and organization - The CLI installed and paired, or a personal access token for API calls - An agent version to attach the skill to

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.

---
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

In the UI

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.

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.

CLI API

Select client CLIAPI

1. Create the skill:

   ren skills create --name "summarize-commits"

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

2. Create a version with your archive:

   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:

   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:

   ren agents versions skills add agt_abc123 1.2.0 \
     --skill-id skl_abc123 \
     --skill-version 0.0.1

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

1. Create the skill with POST /api/skills:

   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:

   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:

   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"}'

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.