MetorialDocs

Skill Agents

Manage sub-agents attached to a skill.

The Skill Agent object

skill_agent.json
{
  "object": "skill.agent",
  "id": "example_id",
  "skill_id": "example_skill_id",
  "name": "example_name",
  "description": "example_description",
  "slug": "example_slug",
  "status": "active",
  "store_id": "example_store_id",
  "store_item_id": "example_store_item_id",
  "path": "example_path",
  "document_id": "example_document_id",
  "archived_at": "2026-10-17T09:50:02.665Z",
  "created_at": "2026-10-17T09:50:02.665Z",
  "updated_at": "2026-10-17T09:50:02.665Z"
}
object"skill.agent"required
idstringrequired
skill_idstringrequired
namestringrequired
descriptionstringrequirednullable
slugstringrequired
status"active" | "archived"required
store_idstringrequired
store_item_idstringrequirednullable
pathstringrequirednullable
document_idstringrequired
archived_atdaterequirednullable
created_atdaterequired
updated_atdaterequired

Endpoints

Create skill agent

POST/skills/:skill_id/agents

Creates a new agent document in the skill agents directory.

Path parameters

skill_idstringrequired

The unique identifier for the skill

Request body

namestringrequired
descriptionstringoptionalnullable
contentstringoptional

Example request

curl -X POST "https://api.metorial.com/skills/ski_Rm4Mnheq2bfEPhBhP7SY/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "content": "example_content"
}'

List skill agents

GET/skills/:skill_id/agents

Returns a paginated list of agents for a specific skill.

Path parameters

skill_idstringrequired

The unique identifier for the skill

Query parameters

include_archivedbooleanoptional

Example request

curl -X GET "https://api.metorial.com/skills/ski_Rm4Mnheq2bfEPhBhP7SY/agents" \
  -H "Authorization: Bearer metorial_sk_io2h4..."

Get skill agent by ID

GET/skills/:skill_id/agents/:skill_agent_id

Retrieves a specific agent within a skill.

Path parameters

skill_idstringrequired

The unique identifier for the skill

skill_agent_idstringrequired

The unique identifier for the skill_agent

Example request

curl -X GET "https://api.metorial.com/skills/ski_Rm4Mnheq2bfEPhBhP7SY/agents/ski_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."

Update skill agent

PATCH/skills/:skill_id/agents/:skill_agent_id

Updates the name or description for a specific skill agent.

Path parameters

skill_idstringrequired

The unique identifier for the skill

skill_agent_idstringrequired

The unique identifier for the skill_agent

Request body

namestringoptional
descriptionstringoptionalnullable

Example request

curl -X PATCH "https://api.metorial.com/skills/ski_Rm4Mnheq2bfEPhBhP7SY/agents/ski_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description"
}'

Delete skill agent

DELETE/skills/:skill_id/agents/:skill_agent_id

Archives a specific skill agent and removes its linked store item.

Path parameters

skill_idstringrequired

The unique identifier for the skill

skill_agent_idstringrequired

The unique identifier for the skill_agent

Example request

curl -X DELETE "https://api.metorial.com/skills/ski_Rm4Mnheq2bfEPhBhP7SY/agents/ski_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."