Agent Skills

Skills add domain expertise to an Agent. A Skill is a structured set of instructions and procedures that makes an Agent more capable and reliable on a specific kind of task.

If you use QoderWork or Qoder IDE, you can install the Cloud Agents skill from the skill marketplace to create and manage Cloud Agents directly from your local conversation — no manual API calls needed.

Endpoints

Method	Path	Description
`POST`	`/api/v1/cloud/skills`	Create a skill (with its first version)
`GET`	`/api/v1/cloud/skills`	List skills
`GET`	`/api/v1/cloud/skills/{skill_id}`	Get a skill
`PUT`	`/api/v1/cloud/skills/{skill_id}`	Update a skill ⚠️ Deprecated
`DELETE`	`/api/v1/cloud/skills/{skill_id}`	Delete a skill
`POST`	`/api/v1/cloud/skills/{skill_id}/versions`	Create a skill version
`GET`	`/api/v1/cloud/skills/{skill_id}/versions`	List skill versions
`GET`	`/api/v1/cloud/skills/{skill_id}/versions/{version}`	Get a skill version
`GET`	`/api/v1/cloud/skills/{skill_id}/versions/{version}/content`	Download skill version content
`DELETE`	`/api/v1/cloud/skills/{skill_id}/versions/{version}`	Delete a skill version

Versioning model

Skills use a two-layer model of "skill shell + immutable version snapshots":

Skill shell: carries content-independent attributes such as id, display_title, source, metadata, and a latest_version pointer.
Skill version: each version is an immutable, complete content snapshot. The version identifier is an epoch-microsecond string taken at creation time (e.g. "1759178010641129"), generated by the server and not user-assignable.
Updating content = appending a new version via POST /skills/{skill_id}/versions; older versions remain unchanged and can be fetched, downloaded, and deleted individually.
Deleting the latest version makes latest_version fall back to the next-newest version; it becomes null when all versions are deleted.
The skill name (from SKILL.md frontmatter) must be consistent across all versions and cannot change after creation.

PUT /api/v1/cloud/skills/{skill_id} is deprecated. Use Create a skill version to update content.

What Skills Do

Inject domain knowledge — give a generalist Agent specialized abilities (code review, document generation, etc.).
Standardize procedures — ensure the Agent follows consistent steps and produces consistent output.
Reusable — define once and share across multiple Agents.

Skill File Layout

A Skill is uploaded as a .zip archive (or a bare file tree via multipart) with a single top-level directory whose name equals the name in SKILL.md:

my-skill/
├── SKILL.md          # Required: Skill definition
├── templates/        # Optional: template files
│   └── report.md
└── examples/         # Optional: example files
    └── sample.json

SKILL.md is the core file, written as YAML frontmatter plus Markdown:

---
name: my-skill
description: Perform structured code reviews and produce improvement suggestions
---

# Code Review

## Steps
1. Analyze the structure and architecture of the code.
2. Check for common issues (security, performance, maintainability).
3. Output a structured review report.

## Pitfalls
- Don't fixate on formatting — prioritize logic errors.
- Provide concrete fixes rather than vague critiques.

Create a Skill

POST https://api.qoder.com/api/v1/cloud/skills
Content-Type: multipart/form-data

curl Example

# Package the skill directory (keep the top-level directory)
zip -r my-skill.zip my-skill/

# Upload
curl -X POST https://api.qoder.com/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "files=@my-skill.zip"

Response:

{
  "id": "skill_019e5d133c057536872f745e0b6dbd5d",
  "type": "skill",
  "display_title": "my-skill",
  "source": "custom",
  "latest_version": "1759178010641129",
  "created_at": "2026-05-01T10:00:00.123456Z",
  "updated_at": "2026-05-01T10:00:00.123456Z"
}

latest_version is generated by the server as an epoch-microsecond string taken at creation time. The version value in SKILL.md frontmatter (e.g. 1.0.0) is informational only and is not the server-side version.

Bind to an Agent

Use POST to update the Agent's skills field. Each binding element accepts an optional version field: omit it or pass "latest" to dynamically track the newest version; pass a numeric timestamp to pin that version (existence is validated at write time; unknown versions return 400).

curl -X POST https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "skills": [
      {"type": "custom", "skill_id": "skill_019e5d133c057536872f745e0b6dbd5d"},
      {"type": "custom", "skill_id": "skill_019e5cdc7a9278ba933d4c328096bac5", "version": "1759178010641129"}
    ]
  }'

Versioning

Append a new version to an existing skill:

curl -X POST https://api.qoder.com/api/v1/cloud/skills/skill_019e5d133c057536872f745e0b6dbd5d/versions \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "files=@my-skill-v2.zip"

Unpinned bindings always use the latest version; bindings pinned to a numeric version keep using that exact snapshot.

Get a Skill

curl https://api.qoder.com/api/v1/cloud/skills/skill_019e5d133c057536872f745e0b6dbd5d \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

List Skills

curl https://api.qoder.com/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Response:

{
  "data": [
    {
      "id": "skill_019e5d133c057536872f745e0b6dbd5d",
      "type": "skill",
      "display_title": "code-review",
      "source": "custom",
      "latest_version": "1759178010641129",
      "created_at": "2026-05-01T10:00:00.123456Z",
      "updated_at": "2026-05-01T10:00:00.123456Z"
    },
    {
      "id": "skill_019e5cdc7a9278ba933d4c328096bac5",
      "type": "skill",
      "display_title": "doc-generator",
      "source": "custom",
      "latest_version": "1759264410332875",
      "created_at": "2026-04-20T08:30:00.482910Z",
      "updated_at": "2026-04-25T09:15:00.104276Z"
    }
  ],
  "next_page": null,
  "has_more": false
}

Authoring Tips

State the trigger — write the description so it's clear when this Skill should be used.
Be concrete in steps — describe precise actions, not vague guidance.
Document pitfalls — help the Agent avoid common mistakes.
Provide validation — tell the Agent how to confirm the task is complete.

FAQ

Q: How are Skills different from the Agent system prompt? A: system is general guidance that applies to every task. A Skill is an on-demand expertise module the Agent activates based on the task at hand. Q: How many Skills can an Agent reference? A: There's no hard limit, but keep it under 10 to maintain predictable behavior. Q: When will Skills go GA? A: The feature is in M2. Reach out if you want early access; broader rollout is coming in a later release. Q: Is there a size limit on the zip? A: The archive must be 50 MB or less, and the uncompressed content must also be 50 MB or less.

Next steps

Agent Tools

Equip Agents with built-in, MCP, and custom tools.

Define an Agent

Review Agent configuration.

Sessions

Manage session lifecycle.

Quickstart

Get your first Cloud Agent running in 5 steps.

​Endpoints

​Versioning model

​What Skills Do

​Skill File Layout

​Create a Skill

​curl Example

​Bind to an Agent

​Versioning

​Get a Skill

​List Skills

​Authoring Tips

​FAQ

​Next steps

Agent Tools

Define an Agent

Sessions

Quickstart

Endpoints

Versioning model

What Skills Do

Skill File Layout

Create a Skill

curl Example

Bind to an Agent

Versioning

Get a Skill

List Skills

Authoring Tips

FAQ

Next steps