Skills
Create, share, and reuse composable agent capabilities.
What are Skills?
Skills are reusable, composable agent capabilities that can be shared across projects and teams. Think of them as npm packages for AI agent behaviors — encapsulating tools, prompts, iteration logic, and error handling into a single portable unit.
Each skill defines a repeatable pattern that an agent can execute. By composing skills together, you build complex agent workflows from well-tested building blocks without rewriting logic across projects.
Creating a Skill
curl -X POST https://api.retrace.yashbogam.me/api/v1/skills \
-H "x-retrace-key: rt_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Web Research",
"description": "Search the web and summarize findings into a structured report",
"definition": {
"tools": ["web_search", "summarize"],
"prompt_template": "Research {topic} and provide a structured summary",
"max_iterations": 5,
"error_handling": "retry"
},
"is_public": true,
"tags": ["research", "web", "summarization"]
}'The response includes the skill id and an auto-assigned version starting at 1.
Skill Definition Schema
| Field | Type | Description |
|---|---|---|
tools | string[] | Tools the skill is permitted to invoke |
prompt_template | string | Template with {variables} interpolated at runtime |
max_iterations | number | Maximum loop iterations before the skill halts |
error_handling | string | Strategy: "retry", "fail", or "fallback" |
memory_scope | string | Memory namespace the skill can read/write |
Error Handling Strategies
| Strategy | Behavior |
|---|---|
retry | Retries the failed step up to 3 times with exponential backoff |
fail | Immediately terminates the skill and marks the trace as failed |
fallback | Skips the failed step and continues with the next iteration |
Managing Skills
| Action | Endpoint | Method |
|---|---|---|
| Create | /api/v1/skills | POST |
| List | /api/v1/skills | GET |
| Get | /api/v1/skills/:id | GET |
| Update | /api/v1/skills/:id | PATCH |
| Delete | /api/v1/skills/:id | DELETE |
Use query parameters to filter the list endpoint:
curl "https://api.retrace.yashbogam.me/api/v1/skills?tags=research&limit=20" \
-H "x-retrace-key: rt_live_..."Versioning
Skills are versioned automatically. Each PATCH request increments the version number. Consumers can pin to a specific version to avoid breaking changes:
{ "skill_id": "sk_abc123", "version": 2 }When no version is specified, the latest version is used.
Community Skills
Set is_public: true to publish your skill to the community marketplace. Other users can discover, fork, and use your skill in their own agents.
Browse community skills:
curl https://api.retrace.yashbogam.me/api/v1/skills?scope=publicFilter by tags, sort by popularity, or search by name:
curl "https://api.retrace.yashbogam.me/api/v1/skills?scope=public&tags=code-review&sort=popular"[!TIP] Pin skills to a specific version in production workflows. Use
latestonly during development to pick up improvements automatically.