Skip to main content
Define your agent

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 CN or Qoder CN 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

MethodPathDescription
POST/api/v1/cloud/skillsCreate a skill (with its first version)
GET/api/v1/cloud/skillsList 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}/versionsCreate a skill version
GET/api/v1/cloud/skills/{skill_id}/versionsList skill versions
GET/api/v1/cloud/skills/{skill_id}/versions/{version}Get a skill version
GET/api/v1/cloud/skills/{skill_id}/versions/{version}/contentDownload 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.cn/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.cn/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.cn/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.cn/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. To advance a pinned binding or change the Skill list for an existing Session, submit agent.skills through Update a session; updating the source Agent's bindings alone does not rewrite an existing Session snapshot.

Get a Skill

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

List Skills

curl https://api.qoder.com.cn/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

  1. State the trigger — write the description so it's clear when this Skill should be used.
  2. Be concrete in steps — describe precise actions, not vague guidance.
  3. Document pitfalls — help the Agent avoid common mistakes.
  4. 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.
First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference