Skills and Playbooks
Reusable capability packages that Trinity syncs from git repositories, assigns to agents, and delivers into their containers — invocable from the agent's Skills tab, from chat autocomplete, or by the agent itself.
Building Agents — Playbooks, Plugins, Deployment
Apr 2026
Build an AI Recruiter Agent
Jun 2026
Concepts
SKILL.md plus optional scripts/, templates, and resources..claude/skills/; Shared skills are the ones assigned from the library. Each skill is a card with Run and Edit & Run./ in the Chat tab to see the agent's skills with argument hints.The Skills Library Is Multi-Source
Trinity syncs from one or more GitHub repositories: a bundled public community catalog (github.com/abilityai/trinity-skills, shown as Trinity Community Skills) that is seeded on fresh installs, plus any custom repositories your admin adds.
Manage sources in Settings → Agents → Skills Library. The panel lists sources in resolution order — the first row is marked wins conflicts, the seeded catalog bundled, and each row shows whether it tracks a branch or is pinned to a tag, with the ref. Per source you can Sync, Disable/Enable, or Remove; Sync all pulls every enabled source. + Add a skills repository asks for a Name, a Repository URL (github.com only), what to Track — Branch (follows new commits) or Tag (pinned — a moved tag is refused)— and the branch or tag name. Errors are shown verbatim under the source, so a refused tag names the tag and says what to do.

A private source repository authenticates with the platform GitHub PAT. Trinity offers that token only to github.com and hands it to git with each request, so it is not written into the library's checkout in the platform data directory. A checkout cloned by an earlier release can still hold the token in its remote URL — one more reason to rotate the platform token after upgrading (see Upgrading).
When two sources ship the same skill name, resolution is by priority (lower wins), then by age. Custom sources default to priority 100 and the bundled community source to 1000 — so your own repository always wins a name clash, and a source you add later needs no reordering.
Nothing is overwritten silently. The winning skill carries a shadowed_by marker naming the sources whose copy is unreachable. The Library card shows it as a shadowed badge whose tooltip names those sources; it also appears on the source status and as a warning at injection time. Skill names stay bare (pdf-export, never community/pdf-export), so an agent's /skill-name invocation never changes because a source was added.
Deleting a source does notunassign its skills — they keep resolving through whatever source still provides them.
Upgraded from a single-library install
An installation that predates multiple sources carries one legacy skills-library URL setting. On the first sync after upgrading, an install with no sources adopts that URL as a custom source named Migrated library (tracking the branch it tracked before) and clears the setting — no admin action needed. If the install already has sources, the URL is matched against them by repository, so https://github.com/Org/repo.git, https://github.com/Org/repo/ and github.com/Org/repo all count as the same source, and nothing happens.
A legacy URL that names a repository which is not one of your sources is refused — adding a source is an admin action, never an automatic one — and Trinity files one low-priority Legacy skills-library adoption refused heads-up in the Operations queue, from _skills-sync. It is one row per refused URL, however many syncs run: each later sync updates that row (seen N times) instead of filing another, and a different URL raises its own. The platform ends the row itself once the URL is adopted or no longer configured, and it expires 14 days after the last sync that saw it (see Approvals → Platform heads-ups). To dismiss it sooner, cancel it (POST /api/operator-queue/{id}/cancel, or Clear All on the Needs Response tab, which cancels every open item) rather than clicking Got it: an acknowledged alert waits for an agent reply that never comes and cannot be cleared, while a cancelled one stays gone. After you end it, the same refusal files nothing for 7 days. If you want that repository, add it as a source in the panel above. The legacy setting itself can no longer be written through the settings API.
Repository layout
A source repository can lay its skills out in one of three ways. Trinity tries them in order and falls through on anything invalid:
Declared — a catalog.yaml at the repo root with a skills_root: key naming the directory that holds skill folders. One flat level deep.
Conventional — a skills/ directory containing at least one <name>/SKILL.md.
Legacy — .claude/skills/, the original convention.
Existing repositories keep working with no configuration. The resolved root is reported per source in the library status, along with a layout_conflict flag if a repository carries more than one recognizable layout.
Supply-chain posture: pinned tags
Skills carry executable scripts/, and library automation can push them to your whole fleet unattended. So:
v0.5.0 of trinity-skills. New upstream commits do not reach your fleet until the tag is bumped and you sync. A fresh install is seeded at the platform's pin, and an upgrade carries the source forward to the new pin (next paragraph). To pin it to a different tag yourself, an admin updates the source's ref through PUT /api/skills/sources/{id} (the Settings panel adds, syncs, disables, and removes sources but does not edit a ref in place) — the steps are below. Removing the source and adding it again with the new tag is not equivalent: a source added through POST /api/skills/sources is always a custom source, so it loses the bundled badge and gets the custom-source priority, which can change which source wins when two sources ship a skill with the same name. TRINITY_DEFAULT_SKILL_SOURCE_REF in .env changes the tag a fresh install is seeded with, and the tag an untouched bundled source follows; TRINITY_DEFAULT_SKILL_SOURCE="" disables the seed entirely.trinity-skills repository, on a pin the platform chose, with no admin edit that sets its URL, ref or tag-vs-branch setting. It only moves forward (a downgraded image or a branch name never moves it), and a disabled bundled source is left alone; once you enable it again, it moves at the next backend start. Renaming it or changing its priority does not stop it following. Setting any of those three yourself ends following for good, even when you set the tag it is already on (that is how you hold it there; the manual steps below), and from then on the version is yours. Custom sources are never moved. Settings → Agents → Skills Library then shows the new tag, Never synced, and a line such as Followed bundled pin v0.3.0 → v0.5.0 on 29 Oct 2026; the move is also in the audit log as skill_source_follow_bundled_pin. The new tag reaches agents at the next sync — the source's own Sync, Sync all, or scheduled auto-sync — which re-injects the fleet when automatic re-inject is on, just as for a manual move. Two things to know: the new tag's first fetch is trusted the way a fresh install's is (the moved-tag check applies from the sync after), and a newer tag can drop a skill (step 1 below) — agents keep their old files, and the Library's Assigned but no longer in the library list shows which agents still have it.moved_tag and leaves your fleet alone. Moving to new content means pointing the source at a new tag name — an explicit admin action. Annotated and lightweight tags are both compared by the commit they point at, so a release tag that has not moved is never refused.Pinning the bundled source to a tag yourself (replace <tag> with the tag you are moving to). An upgrade normally does this for you. Doing it by hand, including setting the tag it already has to hold it there, stops the source following the platform's pin from then on:
Before you move. A newer tag can drop skills — for example, v0.5.0 dropped the four add-* installers (add-backlog, add-project-management, add-canon, add-orchestrator). An agent still assigned a dropped skill keeps its old files, but every later delivery reports "Skill not found in library". Unassign those skills first. An agent that still needs one can get it from the abilities marketplace as /agent-dev:<name> — a marketplace plugin, outside the Library.
Find the bundled row. With an admin token (POST /api/token; agent MCP keys are refused), call GET /api/skills/sources and find the entry in sources with "is_default": true. Note its id, and its current ref for rollback.
Change the ref. PUT /api/skills/sources/{id} with {"ref": "<tag>"}. Changing the ref resets the source's sync status to never; setting the tag it already has keeps its sync status and only stops it following.
Sync. Use the source's own Sync, Sync all in the Settings skill-sources panel, or Sync now on the Library's Skills tab. Each starts the fleet re-inject when the source's commit moved and automatic re-inject is on. If scheduled auto-sync is enabled, it also picks up the change on its next run and may re-inject across the fleet. With automatic re-inject off, restart the affected agents (an agent's skills are delivered again when it starts) or re-deliver one agent's skills with POST /api/agents/{name}/skills/inject.
Check. Confirm the skills you expect from the new tag are in the Library (for v0.5.0, project-status and update-status — 40 skills in all).
Rollback: the same PUT with the ref you noted, then sync the whole library again. Any agent assigned a skill that only the newer tag carries will then report it missing.
To revoke a skill from the community catalog, a new tag is cut without it.
Deprecated Skills
A library retires a skill by marking it in the skill's SKILL.md frontmatter:
deprecated: true # a real boolean
superseded-by: new-skill # optional: the successor, or a short sentenceA deprecated skill stays listed, assignable and injected— Trinity flags it, never hides or refuses it:
trinity skills list table has a deprecated column (yes, → <successor>, or blank).CLAUDE.md is not annotated.A deprecated value that is not a boolean, or a superseded-by that is not text, produces a named frontmatter_invalid warning and is ignored.
Browsing and Assigning
Two surfaces, two starting points:
| Surface | Purpose |
|---|---|
Library page → Skills tab (/library?tab=skills) | Start from a skill. See every skill, its contract, its source, the library's sync state, and which agents hold it — then assign it to one more agent or unassign it, without opening the agent. |
| Agent detail → Skills tab | Start from an agent. Assign skills opens the library picker: tick the skills this agent should have, save, and see each skill's last delivery on its card. |


Both surfaces write the same per-agent assignment, so there is one skill model whichever way you come at it.
Finding a skill. The Library's skill grid and the Assign skills picker share one filter bar: Filter skills (matches name and description), a source filter (hidden when there is only one source) and a category filter (hidden when no skill declares a category: in its frontmatter; a skill with none appears only under All categories). A stated total says how many there are and how many the filter shows — 42 skills · 6 shown, or No skill matches the filter. Long lists scroll inside a box that fills the window, so the page never grows with the library. On the agent's Skills tab, Own skills and Shared skills scroll together in one box under a header that counts both (12 own · 5 shared); on a wide window the Shared heading, with Assign skills, Manage sets and Sync now, stays docked in view while you scroll through Own skills.
From the agent's Skills tab
Library skills assigned to the agent are the cards under Shared skills, each with its version short-SHA, description, and the outcome of its last delivery. The owner or an admin manages them from the section's header. Assign skills opens the library picker: everything available, with its declared dependencies. Tick or untick skills and click Save assignments. Before you save, each changed row is marked with what Save will do — to add, to remove, or kept by set for a skill you untick that an assigned set still holds — and the footer counts every pending change, including rows a filter is hiding (2 to add, 1 to remove). A ticked skill hidden by the filter is still saved. The picker opens with the cursor in Filter skills; Esc clears the filter text, and Esc again closes the dialog. While there are unsaved changes, a click outside the dialog does not close it. Select all and Deselect all, above the list, tick or untick every listed skill in one click; with a filter on they act only on the rows it shows. Nothing is saved until you click Save assignments, and Reset puts the ticks back. Select all leaves deprecated skills as they are, so tick one by hand to assign it. Neither button changes a skill that a set assigns, or an assignment whose skill is no longer in the library: remove that one from its card. A save that would remove a skill that needs approval asks first, because its approval requirement goes with it. The save delivers straight away, and the note under the button says what happened:
| Note | Meaning |
|---|---|
| Saved and delivered — available now. | Every added skill is in the running agent. |
| Saved — the agent is stopped, so it applies on next start. | The assignment is recorded; the files arrive on start. |
| Saved — still installing; the lists update when it lands. | A large package outlived the request's wait; delivery continues in the background. |
| Saved; some skills did not install (…). Sync now to retry. | Named skills failed; the rest landed. |
| Saved but not delivered: <why>. Sync now, or the agent picks it up on next start. | The agent was mid-sync, still starting, its container state could not be read, or the install failed. The assignment is kept either way. |
Sync now (running agents only), in the same header, is the repair action: it re-copies every assigned skill unconditionally and is highlighted only when a delivery did not land. Per-skill outcomes are shown honestly — a skill that landed but is missing a declared binary or environment variable is flagged with a warning on its card, not reported as a clean success. The save itself says so too: the delivery note stays green, and a separate warning line names what is missing, for example pdf-report needs the binary pdftotext, which this agent doesn't have. The same line appears under the Library's Assign to… control. The card's note line opens a details dialog for a name conflict, a delivery error or warnings, and the full Superseded by … text. Unassign on a card removes that one skill; a skill that only a set brought is removed by unassigning the set.
Name conflict. If the agent already has its own .claude/skills/<name>/ directory that the platform did not create — usually a skill the agent wrote itself — the library skill of the same name is not installed. The agent's copy is left intact, is listed under Own skills, and is the one that runs. The Shared card shows a name conflict badge on every load, with Run disabled, and its note opens the two ways out: Unassign library skill keeps the agent's copy, or rename or remove the agent's directory and sync again to install the library version. Sync now does not override a conflict.
From the Library
Each skill card on the Library's Skills tab carries an Assigned to N agents line with chips linking straight to that agent's Skills tab — the first four, then +N more. Under it:
The three states of the holder list are kept distinct rather than collapsed into a zero. If the assignment data hasn't loaded yet you see a dash; if it couldn't be read you get an explicit failure with a retry; only a real, successful read reports “no agents yet” (admin) or “none of your agents” (everyone else). You see only what you can access: an admin gets the whole fleet, everyone else gets their own and shared agents.
Below the library listing sits Assigned but no longer in the library — assignments whose skill has since been removed upstream. This matters because revocation works by cutting a new tag withoutthe offending skill, after which a page keyed on the library listing would answer “who still has it?” with silence. The package stays on each agent until it is unassigned — with the × on the chip here, or from that agent's Skills tab.
Lists follow the assignment
Every change to an agent's assignments — assign, unassign, save, a manual sync, a background delivery finishing, a fleet re-inject — refreshes the open screens that list its skills: the Skills tab, the / autocomplete in Chat, and the / popup in the Workspace. Nothing needs a reload.
Skill Sets
A skill set is a named family of library skills that call each other — for example dev-backlog (backlog, groom, claim, …). Assigning the set assigns every member in one act, and the platform keeps the family current: a member added upstream arrives on the next re-inject, and one removed upstream is pruned.
A library source declares its sets in catalog.yaml, beside skills_root. Two forms are accepted:
sets:
project-management: [project-init, project-task] # short form
dev-backlog: # long form
skills: [backlog, roadmap, groom]
requires: {env: [GITHUB_TOKEN]} # credentials the set needs
schedules: # suggestions only
- {name: Weekly groom, cron: "0 9 * * 1", message: /groom}A set names skills from its own source. If it names one that source does not ship, it is listed as partial and cannot be assigned until the source is fixed. Set names resolve like skill names: the custom source wins, and a later source declaring the same name is shown as shadowed.
Who Can Change an Agent's Skills
People who own an agent (and admins) change its skills as before. Agentsare different: changing an agent's skills — another agent's or its own — is a separate permission, and no agent holds it by default. Permission to call an agent does not include it.
An admin grants it in Settings → Agents → Skill managers, or with the Change skills toggle in the agent's own Settings › Guardrails pane (see Permissions to Change Itself); both write the same permission. The Skill managers panel lists every agent that holds the permission, with who granted it and when, and a Revokebutton. Pick an agent and grant it. The system agent never needs the grant, and an ephemeral agent cannot receive it. Granting and revoking are audited, and only a person at the UI can do either — an API key cannot grant.
An agent without the grant is refused with 403 skill_management_not_permitted when it assigns, unassigns, replaces, or re-injects skills, or assigns a skill set — for any target, including itself. The same rule covers writing into an agent's .claude/skills/ through the Files API, and setting or clearing a skill's approval gate; the agent's owner and admins still edit skills in the Files tab (someone the agent is merely shared with can read them but not change them — see Agent Files → Who can do what). A granted agent still reaches only the agents its owner owns, and it can never set or clear a gate on itself. A fleet orchestrator that applies a skill map or an approval policy needs this grant.
What another agent may run is a separate question from who may change the list. An agent that holds a permission to call this agent may run the skills under Own skills (the ones the agent declares in its repository). A Shared skill — assigned from the library, directly or through a set — needs a per-skill grant an admin gives on the caller's Permissions tab, or the caller's request naming it is refused with skill_not_granted. The agent itself, its schedules and loops, and people are never affected. See Agent Permissions → Which skills a permission lets the caller run.
Skill Injection
Each assigned skill's whole package is written to ~/.claude/skills/<name>/, and a Platform Skills section is written into the agent's CLAUDE.md listing what was injected and what is still missing. Injection runs when you assign (running agents), when the agent starts, on a manual Sync now, and — if enabled — as a fleet sweep after a library sync.
Injection is:
.gitignore and untracked, so the agent's git auto-sync never commits platform packages into your repository.On an older agent image that predates package support, a multi-file skill degrades to SKILL.md onlywith an honest warning — the skill still works.
Unassigning Removes the Package
Unassigning a skill — whether you remove one skill or drop names from a bulk save — deletes the injected package from the agent, using the same manifest the injection recorded. Only paths a previous injection wrote are removed; directories left empty are cleaned up; anything else in the directory survives. The skill's .gitignore line is stripped too.
The unassignment itself always succeeds. If the agent is stopped, busy, or unreachable, removal is reported as deferred rather than failing the unassign — and the agent reconciles on next start, removing any platform-managed skill that is no longer assigned.
A reconcile that would remove an unusually large number of skills from one agent refuses wholesale and raises an operator alert instead, so a database problem cannot silently strip a fleet.
Keeping the Library Current (Automation)
Both settings default OFF — a zero-config installation behaves exactly as it always did. Configure them in Settings → Agents → Skills Library → Automation:
| Setting | Effect |
|---|---|
| Scheduled auto-sync | Trinity pulls every enabled source on an interval (default 1 hour; 5 minutes to 24 hours). Changing the interval applies without a restart. |
| Re-inject across the fleet after a sync | When a sync finds the library actually moved, running agents receive the updated packages automatically. |
Key properties:
Sync failures are never silent, and a sync contended by another worker reports busy rather than claiming failure.
Skill Frontmatter and Dependency Checks
A skill's SKILL.md frontmatter can declare:
description: — the one place a capability is described. Write what the skill does here, once, and every surface shows it: the Workspace's What it can do cards and new-chat hints, the agent's Skills tab, the Library and its assign dialog, the connector allow-list, the public link, the MCP skill tools, and the chat / menu. A skill with no description, or a blank one, reads No description yet on the cards and lists (on the Skills tab the card adds where to write it); the API and MCP tools return no description for it; the chat / menu and quick-action buttons show the skill's name alone. The Workspace / search lists skills by name only. template.yaml capabilities: are tags, not descriptions (see Template tags are not capabilities).automation: — the skill's intended automation level, shown on its card as a chip: runs unattended (autonomous), asks mid-run (gated) or start by hand (manual). It is the author's declaration; nothing enforces it.user-invocable: — whether the skill can be run from its card and is offered in / autocomplete (default true).allowed-tools: — the tools the skill may use, as Claude Code reads it. Write it in Claude Code's comma-separated form (allowed-tools: Read, Bash, Bash(git:*)) or as a YAML list ([Read, Bash]); both give the same list, and a comma inside parentheses (Bash(npm run lint, npm test)) stays part of one entry. Trinity reports this list in the agent's skill listing but does not enforce it — a Trinity run is restricted by the schedule, loop, or task's own allowed tools.argument-hint: — the argument syntax shown on the skill's card and in / autocomplete. The unquoted bracket idiom (argument-hint: [file]) is kept as written.requires: with packages, binaries, and env lists.category: — one short line, such as project-management. It only feeds the category filter in the Library and the Assign skills picker; nothing else reads it, no card shows it, and it is not returned by the MCP skill tools.deprecated: and superseded-by: — retire a skill (see Deprecated skills).approval: recommended — the author recommends approval before the skill runs (see Requiring approval for a skill).At injection, Trinity runs a declaration-only dependency check and produces per-skill warnings (a missing binary, a missing environment variable) instead of failing. Declared package installs are surfaced but not performed. Environment checks report variable namesonly — values are never read.
A skill whose frontmatter fails to parse gets a named warning and shows No description yet; nothing guesses a description from the file's body. It is never silently dropped.
Template tags are not capabilities
template.yaml can carry capabilities: (a list of tags) and use_cases: (example prompts). Neither describes a capability:
brain-orb turns on the Brain Orb). Settings › General › Technical details shows them as Template tags. The template check X-010 notes a tag that names no skill with a description, so the tags cannot drift from what the agent really has. The A2A agent card still lists these tags as its skills; moving the card to the agent's skills is a separate change.skills: in template.yaml declares skill names only; what each does is its SKILL.md description:.Inside the agent, the Skills tab, the / popup, and the chat empty state read each frontmatter field on its own. A field the agent cannot use — a list or mapping where text belongs, or an allowed-tools value that is a bare yes, a number, or has unbalanced parentheses — is dropped by itself, and the agent log warns once, naming the file and field. The skill keeps its description and every other field. Agents on an older base image instead lost the whole record over one such field, most often a comma-separated allowed-tools, and showed no description. The fix ships in the agent base image, so an existing agent picks it up after the base image is rebuilt (or re-pulled) and the agent is started cold — see Upgrading → Base Image Upgrade.
Running Skills

Open agent detail → Skills tab.
Find the skill under Own skills or Shared skills.
Click Run to start the skill as a task; the run opens on the Tasks tab. Edit & Run opens the Tasks tab with the command filled in, so you can add instructions first.
Or, in Chat, type / to autocomplete a skill command.
Run needs the agent running. On a stopped agent, Own skills still shows the last list the platform saw (Showing its skills as of …) with Run disabled, and says Start the agent to see its own skills only if there is no such list.
Requiring Approval for a Skill
The owner of an agent, or an admin, can make any of its skills wait for a person's approval. Each card shows them a Requires approval toggle and a picker for who approves:
role:<id> (set_skill_gate accepts the same form), where your install provides roles. A role the roster does not name is refused with unknown_role; a named role nobody fills yet is saved with the warning approver_unassigned.The approvers must be able to open the agent. A choice whose people cannot is marked (not shared) in the picker, the gate line reads Needs approval from …: not shared with them, saving warns approver_not_shared, and a gated request is refused with approver_cannot_open_agent until the agent is shared with them.
A kind nobody fills yet is listed but cannot be picked. The controls work on a stopped agent's last-known list too, and are not offered on ephemeral agents or the system agent. A gate on a skill the agent no longer lists is kept, as Not in this agent's skills list: gate kept, until it is removed with Clear gate.
Everyone with access sees a gated card's line, which names the kind of approver, never a person: Needs approval from the primary contact, or Needs approval: you approve this if you are that approver. Run on a gated skill asks the approver instead, and the page says so (Not run: … needs approval before it can run); nothing runs until they approve (see Approvals → Gated-skill approvals for the card, the notices and what each requester hears). When the approver runs it themselves, it runs at once and is marked Ran without approval: you are the approver (others see its approver started it) on its Tasks row, its execution page and the Workspace reply.
A gate also changes what the whole agent can do. While an agent has one, the Bash guardrail refuses a coding-agent CLI started from Bash, for every skill on the agent, not only the gated one. It takes effect when the gate is saved, with no restart.
A skill's author can recommend approval with approval: recommended. A library skill that carries it is gated by default on every agent it is assigned to, and the owner can turn that off; an own skill is not gated for it. Where such a skill has no gate, the owner sees Author recommends approval: not gated. A later library change never loosens a gate that is already set.
A gate you set stays until someone clears it. Unassigning the skill removes it only when a person unassigns it and the package has left the agent; an agent's unassign, a sync or a restart keeps it, so unassigning and reassigning cannot drop a gate. A library default goes once the skill is unassigned and its package has gone.
Gates can also be set over the API or MCP (below), where each gate also takes a deadline for the approver: 1 to 168 hours, 24 by default. An orchestrator agent holding the skill-management permission can gate skills on the other agents its owner owns, never on itself. Every change is audited.
Trinity checks every request that names a gated skill. Inside the agent, a second check stops a run from loading a gated skill on its own. When an agent has gates but cannot run that check, its owner sees a warning at the top of the tab: its image predates the check (recreate the agent), or its runtime has no hooks, such as Codex or Gemini.
Running Skills Without Assignment (Skill Runner)
Two MCP tools let an agent run a permitted self-contained skill without assigning it:
| Tool | Description |
|---|---|
| list_runnable_skills() | List the skills this agent is permitted to run (its permitted set, decided by an operator — not the whole library) |
| run_skill(skill_name, input?) | Run a permitted skill and return its result |
The runner uses a separate workspace — it cannot see the calling agent's files. Use it for self-contained skills (call an API, generate an artifact from the inputyou pass). A skill that must operate on the caller's own files goes through assignment and injection instead.
The Skill Runner is an entitled surface. In a community build, run_skill and list_runnable_skills return a “disabled” result. On an instance with the entitlement, an admin turns the runner on and grants which agent may run which skill from a Skill Runner tab in Settings; the tab is hidden on instances without it.
For Agents
MCP tools for skills:
| Tool | Description |
|---|---|
| list_skills() | List library skills. Each entry carries its source name, any shadowed_by sources, and deprecated / superseded_by. |
| get_skill(name) | Skill details and contract, including deprecated / superseded_by |
| get_skills_library_status() | Library sync status, including the per-source array |
| list_skill_sets() | The skill sets the library declares: status (ok / partial / invalid; only ok can be assigned), members with their versions and a deprecated flag, problems and prerequisites |
| assign_skill_to_agent(skill_name, agent_name) | Assign one skill — or a set, as set:<name> — and deliver it. The response's delivery block reports injected, pending_start, in_progress, or not_delivered with a reason; delivery.skills[<name>].warnings leads with deprecated or deprecated:<successor> for a deprecated skill and, when the skill was put on a running agent, carries the dependency check's codes such as missing_binary:<name> or missing_env:<NAME>. A skill with nothing to report reads just {status: "injected"} |
| set_agent_skills(agent_name, skill_names) | Set the full skill list. set:<name> entries add sets; the agent's other sets are left alone. Remove a set with unassign_skill_set. Added names are delivered, dropped names are removed; delivery and removal report each half |
| sync_agent_skills(agent_name) | Force re-inject into a running agent — the manual retry after a not_delivered |
| get_agent_skills(agent_name) | List an agent's assigned skills. Each carries via_sets (the sets that brought it), individual, and peer_needs_grant — true for a library skill another agent may run only with a grant, false on a name-conflict row (the agent's own copy runs); the agent's sets are listed too |
| unassign_skill_set(agent_name, set_name) | Unassign a skill set; members also assigned on their own or through another set stay |
| list_skill_gates(agent_name) | The agent's gated skills: who approves each (primary or approver), the deadline, the origin (set or library_default), and approver_reachable (whether anyone fills that approver kind). With an agent key, its own gates, or an agent its owner owns when it holds the skill-management permission |
| set_skill_gate(agent_name, skill_name, approver?, deadline_hours?) | Gate a skill, or change its approver or deadline; an omitted field keeps its value. Refused by name: invalid_skill_name, invalid_approver, approver_unavailable, invalid_deadline, ephemeral_agent; warnings may say approver_unassigned |
| clear_skill_gate(agent_name, skill_name) | Remove a gate. Idempotent; clearing a library default keeps it off while the skill stays assigned |
| list_skill_sources, register_skill_source, update_skill_source, delete_skill_source, sync_skill_source, sync_skill_library | Manage library sources (admin principals only — see below) |
REST endpoints — see Backend API Docs for full schemas.
| Endpoint | Method | Description |
|---|---|---|
| /api/skills/library | GET | Merged skill listing across sources |
| /api/skills/library/status | GET | Sync state + per-source array |
| /api/skills/library/sync | POST | Sync every enabled source (admin; agent keys refused) |
| /api/skills/sources | GET/POST | List / register a source (admin; agent keys refused) |
| /api/skills/sources/apply | POST | Register or update a source keyed on its repository URL — 201 created, 200 updated or unchanged, 409 ambiguous_source (admin; agent keys refused) |
| /api/skills/sources/{id} | PUT/DELETE | Edit / remove a source (admin; agent keys refused) |
| /api/skills/sources/{id}/sync | POST | Sync one source (admin; agent keys refused) |
| /api/settings/skills-library | GET/PUT | Auto-sync and fleet re-inject configuration (admin) |
| /api/skills/assignments | GET | Which agents hold each skill, batched, plus assignable_agents — the agents the caller may assign to. Human-only; admins see the fleet, others their accessible agents (the response says which via scope) |
| /api/agents/{name}/skills | GET/PUT | Read / set an agent's assignments (owner). The PUT response carries delivery and removal |
| /api/agents/{name}/skills/{skill} | POST/DELETE | Assign (and deliver) / unassign one skill (owner). The POST response carries delivery |
| /api/skills/library/sets | GET | Every skill set the sources declare, with members, versions and status |
| /api/agents/{name}/skill-sets | GET | The agent's sets with their status and prerequisites |
| /api/agents/{name}/skill-sets/{set} | POST/DELETE | Assign / unassign a set |
| /api/agents/{name}/skills/inject | POST | Force re-inject into this agent (owner); 409 while another injection holds the agent |
| /api/skills/managers | GET | Agents that hold the skill-management permission (admin) |
| /api/agents/{name}/skill-manager | PUT | Grant or revoke that permission with {"granted": true|false} (admin, human-only) |
| /api/agents/{name}/skill-gates | GET | The agent's gates, plus approvers (per approver kind: reachable, and viewer_fills — whether you fill it). ?probe=true adds hook, whether the agent enforces gates inside itself (ok, predates, missing, unsupported_runtime, …), for a person who may manage its skills. Who may approve is never named |
| /api/agents/{name}/skill-gates/{skill} | PUT | Gate a skill — {approver?, deadline_hours?}; only the fields sent are applied. The owner or an admin; an agent key needs the skill-management permission, only on an agent its owner owns, never on itself (403 person_required) |
| /api/agents/{name}/skill-gates/{skill} | DELETE | Clear a gate. Idempotent; same permissions as PUT |
Assignment writes from an agent key (PUT/POST/DELETE on an agent's skills or skill sets, and inject) need the skill-management grant described above.
Source management is for admins — an admin signed in, an admin's own userkey, or the system agent — over REST or the source MCP tools above. Agent-scoped and connector keys are refused, whoever owns them. Registering or syncing a source decides which repository your fleet executes code from, so no agent can do it.
Limitations
allowed-tools frontmatter is informational in Trinity, not a restriction. Limit a run's tools on the schedule, loop, or task instead.skills_root layout supports a single flat directory, one level deep. Nested layouts require a future schema version, which current installations refuse (falling back to the probe) rather than misread.