Skills
A Skill is a reusable, named capability an AI agent can invoke — modeled on Anthropic's Agent Skills format (a SKILL.md file plus optional scripts/ and references/ directories). Skills let you package domain-specific instructions, helper scripts, and reference material that an agent loads only when it actually needs them ("progressive disclosure"), keeping the system prompt small until a skill is invoked.
Anatomy of a Skill
| Field | Description |
|---|---|
name | Slug — the tool name the agent calls. |
display_name / description | Shown to the LLM as the tool's description (≤1024 chars) — this is what the agent sees before invoking the skill. |
content | Full SKILL.md body (instructions/system prompt) — loaded only when the agent calls the skill. |
scripts | Map of scripts/*.py (etc.) file contents the skill can execute in the sandbox. |
file_refs | Map of references/*.md / assets/* file contents the skill can read. |
category | Free-form grouping for the skills library UI. |
status | draft or published. |
Creating skills
| Endpoint | Purpose |
|---|---|
POST /api/v1/skills | Create a skill manually (paste SKILL.md content). |
POST /api/v1/skills/parse | Upload a SKILL.md file or a .zip package (with scripts//references/) — parses and returns a preview without saving, so you can review before POST /api/v1/skills. |
GET /api/v1/skills | List your tenant's skills. |
GET /api/v1/skills/published | List published skills available to agents. |
PUT /api/v1/skills/{id} / DELETE /api/v1/skills/{id} | Edit/delete. |
POST /api/v1/skills/{id}/publish / .../unpublish | Toggle availability to agents. |
Installing from the community registry
OrcFlows can search and install skills from public GitHub repositories that follow the Agent Skills format:
GET /api/v1/skills/registry/search?q=<query>
POST /api/v1/skills/registry/install { "repo": "owner/repo", "branch": "main" }
handleRegistrySearch searches GitHub for matching skill repos (using GITHUB_TOKEN if configured for a higher rate limit); handleRegistryInstall fetches and parses the repo's SKILL.md/scripts/references and saves it as a new skill for your tenant.
Using skills in an agent
Reference skill IDs in an Agent node's skills array:
{
"type": "agent",
"config": {
"skills": ["skl_abc123", "skl_def456"],
"max_skill_rounds": 20
}
}
The agent initially only sees each skill's name + description as a lightweight tool. When it decides a skill is relevant, OrcFlows loads the full content, scripts, and file_refs from the database and runs the skill's instructions (with access to the sandbox for any scripts) for up to max_skill_rounds reasoning turns before returning control to the main agent loop.