Skills

4 operations. {prefix} is the route prefix passed to MapTracon; the template uses /tracon.

GET {prefix}/api/skills

Operation ID: TraconListSkills

Lists the tenant’s skills.

Skills are scoped to the calling tenant; a skill defined for another tenant is never returned. Each entry is complete — instructions, resources, and scripts come with it, so a client does not need a second call per skill. The response is not paged.

Authorization: bearer authentication; Reader role policy when that policy is registered; AgentsRead API-key scope.

Response	Body	Headers
200 OK	application/json → array of AgentSkillDefinition	—

GET {prefix}/api/skills/{name}

Operation ID: TraconGetSkill

Returns a single skill and its resources.

The response carries the skill’s instructions together with every resource and script attached to it, including their content. The name resolves the way the runtime resolves it: a skill registered in code wins over a stored skill with the same name, and ‘origin’ says which one was returned (Code or Database) - so the content shown is the content that runs. Each script carries ‘contentHash’ and the skill carries ‘scriptSetHash’; a script grant pins one of them. A disabled skill is returned too. Names are compared exactly, case included; an unknown name returns 404. The list (GET /api/skills) shows stored skills only.

Authorization: bearer authentication; Reader role policy when that policy is registered; AgentsRead API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Response	Body	Headers
200 OK	application/json → AgentSkillDefinition	—

PUT {prefix}/api/skills/{name}

Operation ID: TraconSaveSkill

Creates or updates a skill.

The call replaces the whole skill: resources and scripts that the body omits are removed. A first save answers 201, a later one 200. The path name and the body name must be identical (400 otherwise). Name, description, and compatibility follow the skill frontmatter rules, and instructions, resources, and scripts are each bounded by the configured size limits. A script may be SAVED even when script execution is turned off — saving and running are separate permissions — but an extension with no registered interpreter is rejected, because such a script could never run and would leave dead data behind. A name registered in code answers 409: a skill defined in code wins name conflicts, so a stored skill with that name would never run. Changing a stored script’s content stops it from running until its script grant is given again for the new content.

Authorization: bearer authentication; Admin role policy when that policy is registered; AgentsAdmin API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Request body (required):

• application/json → AgentSkillRequest

Response	Body	Headers
200 OK	application/json → AgentSkillDefinition	—
201 Created	application/json → AgentSkillDefinition	—

DELETE {prefix}/api/skills/{name}

Operation ID: TraconDeleteSkill

Deletes a skill and its cascading resources.

Resources and scripts are removed with the skill. Agent definitions that still name the skill are NOT rewritten, and they stop resolving: compiling such an agent fails with ‘the skill was not found’ until the reference is removed or the skill is recreated. Check the agents that use a skill before deleting it. An unknown name returns 404. For a name registered in code only a stored skill with that name is removed (one saved before the name was taken in code, which never ran); the code skill keeps running, and a name with no stored skill answers 409.

Authorization: bearer authentication; Admin role policy when that policy is registered; AgentsAdmin API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Response	Body	Headers
204 No Content	—	—