Skip to main content
Build Agent

Agent Skills

Skills attach domain expertise to an Agent. A Skill is a set of structured instructions and workflows that make an Agent more professional and reliable on specific tasks.

The Role of Skills

  • Inject expertise — Give a general-purpose Agent capabilities in specific domains (such as code review or documentation generation)
  • Standardize workflows — Ensure the Agent follows uniform steps and produces consistent output
  • Reusable — Create once, share across multiple Agents

Skill File Structure

A Skill is uploaded as a .zip file containing the following: 
my-skill/
├── SKILL.md          # Required: Skill definition file
├── templates/        # Optional: template files
│   └── report.md
└── examples/         # Optional: example files
    └── sample.json
SKILL.md is the core file, using YAML frontmatter + Markdown format: 
name: code-review
description: Perform structured code review and output improvement suggestions
version: 1.0.0

# Code Review

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

## Pitfalls
- Do not focus solely on formatting issues; prioritize logic errors
- Provide concrete revision suggestions rather than vague criticism

Create a Skill

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

curl Example

# First, package the Skill directory
cd my-skill && zip -r ../my-skill.zip . && cd ..

# Upload
curl -X POST https://api.qoder.com.cn/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@my-skill.zip"
Response: 
{
  "id": "skill_019e5d133c057536872f745e0b6dbd5d",
  "type": "skill",
  "name": "code-review",
  "description": "Perform structured code review and output improvement suggestions",
  "skill_type": "custom",
  "status": "active",
  "version": 1,
  "content_sha256": "3f4b80bd74ef8aa801005a17f1843019ddcebd4ded36b5bd46bfffb3d39ff71a",
  "content_size": 191,
  "metadata": {},
  "created_at": "2026-05-01T10:00:00Z",
  "updated_at": "2026-05-01T10:00:00Z"
}
version is a server-maintained integer (starting from 1) that increments on each successful re-upload. The version in the SKILL.md frontmatter (such as 1.0.0) is used only as an informational marker and is not the server-side version number.

Associate with an Agent

Bind a Skill to an Agent through the Agent's skills field. Note: use PUT for full replacement and include the current version (PATCH returns 405): 
curl -X PUT https://api.qoder.com.cn/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "skills": [{"type": "custom", "skill_id": "skill_019e5d133c057536872f745e0b6dbd5d"}, {"type": "custom", "skill_id": "skill_019e5cdc7a9278ba933d4c328096bac5"}]
  }'

Version Management

Each upload of a Skill with the same name creates a new version: 
# After updating the version field in SKILL.md, re-upload
curl -X POST https://api.qoder.com.cn/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@my-skill-v2.zip"
The Skill associated with an Agent always uses the latest version.

Get Skill Details

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

List All Skills

curl https://api.qoder.com.cn/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_PAT"
Response: 
{
  "data": [
    {
      "id": "skill_019e5d133c057536872f745e0b6dbd5d",
      "name": "code-review",
      "description": "Perform structured code review and output improvement suggestions",
      "version": 1,
      "content_sha256": "3f4b80bd74ef...",
      "content_size": 191,
      "metadata": {},
      "skill_type": "custom",
      "status": "active",
      "type": "skill",
      "created_at": "2026-05-01T10:00:00Z",
      "updated_at": "2026-05-01T10:00:00Z"
    },
    {
      "id": "skill_019e5cdc7a9278ba933d4c328096bac5",
      "name": "doc-generator",
      "description": "Generate technical documentation",
      "version": 3,
      "content_sha256": "a1b2c3d4e5f6...",
      "content_size": 420,
      "metadata": {},
      "skill_type": "custom",
      "status": "active",
      "type": "skill",
      "created_at": "2026-04-20T08:30:00Z",
      "updated_at": "2026-04-25T09:15:00Z"
    }
  ]
}

Delete a Skill

curl -X DELETE https://api.qoder.com.cn/api/v1/cloud/skills/skill_019e5d133c057536872f745e0b6dbd5d \
  -H "Authorization: Bearer $QODER_PAT"
After deleting a Skill, Agents that were associated with the Skill will no longer load it the next time a Session is created.

Skill Authoring Recommendations

  1. Define clear trigger conditions — State in the description when this Skill should be used
  2. Be specific with steps — Write precise operations in Steps rather than vague descriptions
  3. Document pitfalls — Pitfalls help the Agent avoid common mistakes
  4. Provide verification — Tell the Agent how to confirm the task is complete

FAQ

Q: What is the difference between a Skill and instructions? A: instructions are the Agent's general directives, which apply to all tasks. A Skill is an on-demand specialized module; the Agent decides whether to use it based on the task content. Q: How many Skills can be associated with a single Agent? A: There is no hard limit, but we recommend keeping it under 10 to ensure the Agent's behavior remains predictable. Q: When will the Skills feature be fully available? A: It is currently in the M2 gating phase and is expected to be fully available in subsequent releases. Contact us to apply for early access. Q: Is there a size limit on zip files? A: A single Skill zip file may not exceed 10MB.
Guides
Tutorials
API Reference