Scheduling & Automation
Cron schedules, webhooks, loops, self-reminders, fan-out, asks and approvals, the skills library and the abilities plugins. Short, grounded answers with links to the full documentation.
69 questions
- •How do I schedule a recurring task for an agent?
- •Can I set a timezone for my schedule?
- •How do I know my cron expression is valid before I save the schedule?
- •Can a scheduled run deliver its output to a person's Workspace instead of only the execution log?
- •Can a scheduled brief remember things about the person it's for?
- •Why was my companion agent's scheduled brief skipped with "Held"?
- •Why didn't my schedule fire even though it's enabled?
- •What's the difference between disabling a schedule and turning off autonomy?
- •Can I run a schedule right now without waiting for the next cron tick?
- •What happens when a schedule fires while the agent is already busy?
- •How long can a scheduled task run before it times out?
- •Do failed scheduled runs retry automatically?
- •Can Trinity check that a scheduled run actually did its job?
- •What happens to the execution history if I delete a schedule?
- •Can my agent skip a scheduled run when there's nothing to do?
- •Can an agent schedule itself to run again later?
- •How is an agent self-reminder different from a cron schedule?
- •Do agents run on a heartbeat, or on triggers?
- •How does an agent carry a piece of work that takes many days across many sessions?
- •How do I see or cancel the reminders an agent set for itself?
- •How do I trigger a schedule from an external system like CI/CD?
- •What should I do if my webhook URL leaks?
- •Why are my webhook calls getting rejected with 429?
- •What is an agent loop and when should I use one instead of a schedule?
- •What happens to a running loop if the backend restarts?
- •Can I start and watch a loop from the Workspace?
- •Can I just tell my agent in chat to run a loop or check something every few minutes?
- •Can each loop iteration see the previous iteration's result?
- •How do I keep a loop from running forever or burning my budget?
- •What happens to a loop when one iteration fails — does it stop or keep going?
- •Can an agent start a loop on another agent it has no permission for?
- •How do I run many tasks in parallel on one agent?
- •What are skills and playbooks, and how do I run one?
- •How do I find out which agents already have a given skill?
- •Can I assign a skill from the Library page?
- •What happens if I assign a skill the library marked deprecated?
- •Can a skill be a whole folder of files instead of a single markdown file?
- •Why does my playbook say "No description available"?
- •Does a skill's allowed-tools frontmatter limit what the agent can do?
- •How do I assign skills to an agent, and do I need to restart it?
- •Why does a library skill show "name conflict" instead of installing?
- •Why is my orchestrator agent refused with skill_management_not_permitted?
- •How do I make a skill wait for someone's approval before it runs?
- •What happens after a gated skill request is approved?
- •What does the approval card for a gated skill show, and who gets it?
- •Why didn't I receive an approval request for a gated skill?
- •What happens when an agent's work needs a human decision?
- •How can I see whether a schedule is actually performing well?
- •Can the skills library sync from more than one repository?
- •I upgraded from a single skills-library URL — where did my library go?
- •Where do skills have to live inside a source repository?
- •Will a skills-library update reach my running agents automatically?
- •What happens when I unassign a skill — do the files stay on the agent?
- •Why is the community skills source pinned to a tag instead of tracking a branch?
- •The add-project-management plugin installs nothing — where did it go?
- •Do I need to install the trinity plugin inside my agent before it can run /trinity skills?
- •My template declares schedules — will Trinity create them?
- •What should a schedule's message contain?
- •My scheduled skill hangs every run and burns its whole timeout — why?
- •Can an agent trigger a schedule to get around the agent-to-agent chain limit?
- •How do I stop a webhook sender's retries from firing my schedule twice?
- •What does "Something else" on an approval do?
- •Why was my agent's ask refused with too_many_options or title_too_long?
- •Can I talk an ask through with the agent before I answer it?
- •How do I tell an agent its ask doesn't need a decision?
- •Why does an expired approval say "whether the action went ahead is unknown"?
- •Why does a heads-up in the Operations queue say "seen 5 times" instead of filing new rows?
- •Why did my agent get a "queue flood" heads-up?
- •Can I use a legacy timezone name like US/Eastern in a schedule?
How do I schedule a recurring task for an agent?
Open the agent's detail page, go to the Schedules section, and click Create Schedule. Give it a name, a cron expression (for example 0 9 * * 1-5 for weekdays at 9 AM), the message or task to send, a timezone, and an optional description. You can also pick a model override per schedule from the Model picker (Claude Opus 5.5, Fable 5.1, Sonnet 5, Haiku 4.5 and older models, or any model id you type); left empty, it uses the platform default. Each time the schedule fires, it creates an execution record with status, duration, response, and cost. See Scheduling.
Can I set a timezone for my schedule?
Yes. Every schedule has its own timezone setting, chosen when you create or edit it, so 0 9 * * *fires at 9 AM in that timezone rather than in UTC. The default is UTC if you don't set one. See Scheduling.
How do I know my cron expression is valid before I save the schedule?
The schedule form checks the expression as you type, with the same grammar the scheduler uses. While creating, an inline error appears under the field once you leave it with an invalid expression; while editing, an invalid stored expression is flagged immediately; and Create (or Update) is disabled only while the field is non-empty and invalid. The presets Daily 9 AM, Weekly Mon, Every 6h and Every 30mfill the field for the common cadences. The server stays the authority — an expression the form accepts but the scheduler rejects still fails on save with the reason — and a schedule already stored with an unregistrable expression shows a warning triangle in its cron chip and never fires until fixed. See Scheduling.
Can a scheduled run deliver its output to a person's Workspace instead of only the execution log?
Yes. Set deliver_to_workspace_email on the schedule over the API or with create_agent_schedule / update_agent_schedule— the UI form has no field for it, and passing nullon an update stops delivering. The run's output then arrives as a message from the agent in that person's Mainchat with it, rateable like any reply and delivered at most once per fire; it waits up to two minutes for a reply already in progress in that chat, and it appears on the person's next Workspace load or chat switch rather than popping up mid-conversation. You can always name yourself; naming someone else — who must be the agent's owner or someone it is shared with — takes the agent's owner or an admin. If the address can't reach the agent (never shared, share revoked, unknown), the run fails and says so on its execution row, and a malformed address is rejected when you save rather than hours later. See Scheduling.
Can a scheduled brief remember things about the person it's for?
Yes. A run of a schedule that names a person with deliver_to_workspace_emailruns as that person's seat: the agent receives their per-person memory before it starts and can write it back with write_user_memory, so the next brief builds on the last. Cron, Run now and webhook fires all serve the named person. The tool replaces the whole notes blob, so the agent must write the complete updated notes. The write is refused while another turn for someone else is running on the same agent, so give each brief its own time. The person sees every write in their Workspace and can undo the latest one. See Scheduling.
Why was my companion agent's scheduled brief skipped with "Held"?
An agent whose template declares a role is a companion, and its cron-fired Workspace brief is held until its owner marks it ready on the Role card in the Workspace agent details. A held brief is recorded as a skippedexecution with the reason — not a failure, not retried, not alerted. Run now and webhook fires are not held. Agents whose brief was already firing before the upgrade were marked ready automatically. See Scheduling.
Why didn't my schedule fire even though it's enabled?
The most common cause is the agent-level autonomy toggle: it's a master switch, and no schedules fire while it's off, regardless of their individual enabled state. Next, look at the schedule's cron chip in the list — a warning triangle with the tooltip Invalid cron expressionmeans the stored expression is one the scheduler can't register, and that schedule never fires until you fix it. Also check that the agent still exists and isn't deleted (schedules stop firing immediately when an agent is deleted) and, if the agent has freeze schedules if sync failing enabled, that its git sync hasn't failed three times in a row and that it hasn't been out of step with its repository for more than 24 hours — the skipped run in the execution history names which. If the scheduler was restarted, missed runs are only caught up within a 1-hour grace window; anything older is skipped rather than fired late. See Scheduling.
What's the difference between disabling a schedule and turning off autonomy?
Disabling a schedule affects just that one schedule; its siblings keep firing. The autonomy toggle is agent-level and a gate, not a bulk edit: nothing fires while it's off, but each schedule keeps its own enabled/disabled state (an enabled one shows a "Will not fire — autonomy off" warning), so turning autonomy back on restores exactly the schedules you had enabled. Use the per-schedule toggle for fine-grained control and autonomy as the emergency brake or "pause everything" switch. See Scheduling.
Can I run a schedule right now without waiting for the next cron tick?
Yes. Click Run now on the schedule in the UI, or call POST /api/agents/{name}/schedules/{id}/triggervia the API. Manual triggers always fire — they bypass the pre-check hook entirely, even if the hook would have skipped the run. The result appears in the execution history like any other run. See Scheduling.
What happens when a schedule fires while the agent is already busy?
Each agent has a configurable number of parallel task slots (default 3). If all slots are taken when a scheduled task arrives, the task is queued in a persistent, first-in-first-out backlog instead of being dropped, and it runs as soon as a slot frees up. Queued tasks that sit unprocessed for more than 24 hours are expired. Retries also count against the same slots. See Scheduling.
How long can a scheduled task run before it times out?
Each agent has an execution timeout cap (default 60 minutes, configurable from 1 minute up to 2 hours). A schedule can set its own timeout_seconds; when unset it inherits the agent's cap, and when set it can never exceed it. Creating a schedule with a timeout above the agent cap fails with a validation error, and lowering the agent cap below an active schedule's timeout is rejected too — raise the agent cap first, then the schedule timeout. See Scheduling.
Do failed scheduled runs retry automatically?
Only if you turn retries on. Each schedule has max_retries (range 0–5) and retry_delay_seconds(default 60, range 30–600). A schedule created in the UI or over the REST API starts with retries off (max_retries: 0); one created with the create_agent_schedule MCP tool starts with 1 retry. Rate-limit errors use double the delay, capped at 300 seconds. Each retry creates a new execution record linked to the original via retry_of_execution_id, and the execution list groups retries under their parent run. A run that stopped at its turn limit is never retried, since it would stop at the same place. A retry of a cron run also respects autonomy and the git-sync pause: turn autonomy off and a pending retry is dropped. See Scheduling.
Can Trinity check that a scheduled run actually did its job?
Yes, with post-run validation. Set validation_enabled: true on the schedule over the API, or with create_agent_schedule / update_agent_schedule; the schedule form has no field for it. After each successful run, the same agent runs one extra execution in a clean context that audits the result, and the run's business_status becomes validated or failed_validation (or validation_unavailable when the run's response was empty, with no alert). A fail or partial verdict raises one high-priority Validation Failed alert in the Operations queue, but it does not trigger a retry. Each validation pass is a real execution, so it costs a run; validation_prompt and validation_timeout_seconds(30–600, default 120) tune it. See Scheduling.
What happens to the execution history if I delete a schedule?
Deleting a schedule is a soft delete: it stops firing immediately, but the schedule row and all its execution records are preserved. An admin can recover a soft-deleted schedule, and if it was enabled it rejoins the scheduler shortly after recovery. Soft-deleted schedules are permanently purged after a retention period: 5 days on a fresh install, 30 days on an install upgraded from before those defaults, and an admin can change it. See Scheduling.
Can my agent skip a scheduled run when there's nothing to do?
Yes, with the pre-check hook. If the agent's template ships an executable at ~/.trinity/pre-check, Trinity runs it before each cron tick: empty stdout with exit 0 records a skipped execution at zero cost without ever invoking the model, while non-empty stdout becomes the actual task message. The hook is language-agnostic (any shebang works) and fail-open — a broken or slow hook never suppresses a run. It runs before every cron schedule on the agent, and TRINITY_SCHEDULE_ID, TRINITY_SCHEDULE_NAME and TRINITY_SCHEDULE_MESSAGEin its environment say which one is firing — so a hook can gate one schedule and print the others' own message back. Manual Run now triggers bypass it. See Scheduling.
Can an agent schedule itself to run again later?
Yes, with a self-reminder. While it's running, an agent can set a one-shot reminder — a future re-invocation of itselfcarrying a message it writes ("check whether the build passed"). When the time comes, Trinity dispatches a normal execution of that same agent with that message. Reminders are durable, so a pending one survives a backend or container restart and still fires. See Agent Reminders.
How is an agent self-reminder different from a cron schedule?
A schedule is a recurring, owner-created cron job that fires on a cadence you define in the UI or API. A reminder is one-shot and agent-initiated: the agent decides during a run to wake itself once at a later time, without an owner setting anything up. Use schedules for standing recurring work; reminders are for an agent deferring a single follow-up it discovered mid-task. See Agent Reminders.
Do agents run on a heartbeat, or on triggers?
Mostly on schedules. A schedule fires one message on a cron cadence, ideally a one-line playbook call such as /daily-briefing, so each standard operating procedure becomes its own schedule, and an agent can have as many as it needs. The triggered cases have their own tools: a webhook fires a schedule from an outside system, event subscriptions react to other agents, loops run bounded back-to-back work, and reminders let an agent wake itself once. Polling on a schedule ("check the inbox every hour") is often simpler and sturdier than waiting for a push, and a pre-check hook keeps the empty runs free. See Scheduling, What should a schedule's message contain? and How do I trigger a schedule from an external system like CI/CD?.
How does an agent carry a piece of work that takes many days across many sessions?
Through a project and a steward that runs on a schedule. The agent-devproject skills keep the project's goal, tasks and log outside any single chat, and the steward skill (/agent-dev:project-steward) runs on its own schedule. Each pass reads what needs attention, checks finished work, moves the next task forward and raises an ask when something is stalled. Trinity doesn't run the steward for you: an agent steward needs that schedule, and the project's Steward card says No sweep scheduleduntil it has one. On instances licensed for Projects the same record appears in the Workspace, and elsewhere the skills keep it in the agent's repository. See Workspace Projects → The steward and What is the Steward card on a project page?.
How do I see or cancel the reminders an agent set for itself?
When a reminder fires it runs as a normal execution, so it shows up in the agent's Executions list grouped under a Reminderstrigger bucket. The agent manages its own pending reminders through its tools — listing and cancelling them — and this is self-only: an agent can only see and cancel the reminders it set for itself, not another agent's. See Agent Reminders.
How do I trigger a schedule from an external system like CI/CD?
Enable a webhook on the schedule: open the schedule's Webhook panel and click Enable webhook, which mints a public URL containing a 256-bit token. Any external system can then POSTto that URL — no Trinity account or JWT needed — and gets back 202 Accepted. You can include an optional {"context": "..."}body (up to 4,000 characters). It is added below the schedule's message, marked as external data rather than instructions, and the agent receives it with the run. Every call is audit-logged. See Webhook Triggers.
What should I do if my webhook URL leaks?
Rotate or revoke it: Rotate URL mints a new token and the old URL returns 404 immediately, while Revoke turns the webhook off entirely. For defense in depth, enable Signature authentication— Trinity shows you a signing secret exactly once, and every request must then carry an X-Trinity-Signature: sha256=<hex> header computed as HMAC-SHA256 of the raw request body; unsigned or badly signed calls are rejected with 401. Note that rotating the URL also clears the signing secret, so re-enable signing afterward. See Webhook Triggers.
Why are my webhook calls getting rejected with 429?
Webhook triggers are rate-limited to 10 calls per 60-second window per webhook token (configurable by the operator), with an additional per-IP limit protecting the endpoint before token lookup. When you exceed the limit you get a 429 response — back off and retry after the window passes. If you need to fire more often than that, batch the work into fewer triggers or use the context body to pass multiple items in one call. See Webhook Triggers.
What is an agent loop and when should I use one instead of a schedule?
A loop runs the same task against one agent repeatedly, strictly one iteration at a time, up to a bounded max_runs (1–100) — for example "process the next backlog item" × 20. Use a loop for back-to-back bounded work sessions, agentic retry ("keep trying until the tests pass"), or short polling; use a schedule for anything recurring on a cadence slower than the loop's 1-hour delay ceiling. You start a loop from the agent's Loopstab, from the Workspace rail's Loops tab, by asking the agent in chat, via the run_agent_loop MCP tool, or via REST, and each iteration is a normal execution with its own cost and timeout. See Agent Loops.
What happens to a running loop if the backend restarts?
It carries on. A loop is a durable record, not an in-memory job: on boot, a loop that was between runs is picked up again, and a loop whose iteration was in flight continues from that run's outcome — nothing is dispatched twice and nothing is lost. The interrupted status in the lifecycle table only applies to loops from older builds, before loops became durable. See Agent Loops.
Can I start and watch a loop from the Workspace?
Yes, if you're a platform user: open the rail's Loops tab in the chat and click Start a loop (or Start another loop). The small form asks for the agent (in a room, which participant), what to do each run, the number of runs, and an optional cost budget, and states the guardrails up front — it stops by itself after 3 identical replies in a row and after 3 consecutive failures, with no time limit unless you set one. Each row shows Run N of M, how much of each guardrail is left, Stop while it's active, and a status that says why it ended: Done, Done, with errors, Stopped by you, Stopped — cost budget reached / time limit reached / it stopped making progress, or Failed. External clients never see this tab, and loop runs are left out of the activity shown to them. See Agent Loops.
Can I just tell my agent in chat to run a loop or check something every few minutes?
Yes. Asking for repetition in chat starts a Trinity loop — or, for a single deferred follow-up, a reminder. The platform routes "run a loop" and "do this every few minutes" to these server-side primitives and withholds the harness's own loop and wake-up tools in headless runs, because those would report success and then never fire once the turn ended. The loop it starts is an ordinary one: it shows in the Loops tab and the Workspace rail, each iteration is an execution, and the standard guardrails apply. See Agent Loops.
Can each loop iteration see the previous iteration's result?
Yes, through the message template. The template supports {{run}} (the 1-indexed run number) and {{previous_response}}(the trailing 2,000 characters of the previous iteration's response, empty on run 1). Because {{previous_response}}is lossy, don't rely on it for real artifacts — instruct the agent to keep the draft or report in a workspace file and re-read it each run, since the agent's filesystem persists across iterations. See Agent Loops.
How do I keep a loop from running forever or burning my budget?
Loops have several independent brakes. max_runs (required, capped at 100) is the guaranteed ceiling; an optional stop_signalends the loop early when the agent's response contains that substring; max_cost_usd stops the loop at a run boundary once accumulated spend meets the budget; max_duration_secondssets a wall-clock deadline (up to 7 days); and no-progress detection stops the loop when consecutive runs return identical responses (default: 3 identical runs, set the threshold to 0 to disable). All of these are checked between runs — the in-flight iteration always finishes first, so a single run can overshoot a budget or deadline. A separate failure policy governs what happens when an iteration errorsrather than runs long — see the abort-vs-continue question below. You can also click Stop at any time for a graceful stop. See Agent Loops.
What happens to a loop when one iteration fails — does it stop or keep going?
That's set by the loop's failure policy, on_failure. The default is abort: the loop fails fast, stopping the moment an iteration errors. Switch to continueand the loop tolerates a failed iteration and moves on to the next run — but it still aborts if failures pile up, once it hits max_consecutive_failures (default 3) errors in a row; a successful run resets that streak. A continue-mode loop that finishes with some tolerated failures reports a completed_with_errors status. See Agent Loops.
Can an agent start a loop on another agent it has no permission for?
No. run_agent_loop applies the same permission rule as chat_with_agent: an agent can loop on itself, and on another agent only if it has been granted permission to call it. Without a grant, the tool refuses before any loop starts and returns an Access denied result. get_loop_status and stop_looplook up the loop's agent and apply the same rule, answering Loop '<id>' not found or not accessible on a refusal. If an agent's permission is removed while its loop runs, the agent's owner can still stop the loop from the Loops tab. See Agent Loops.
How do I run many tasks in parallel on one agent?
Use fan-out: it dispatches 1–50 independent tasks to an agent concurrently (up to max_concurrency, default 3, max 10), waits for all of them to finish, and returns aggregated results in input order. timeout_secondsonly limits the wait — tasks still open at the deadline keep running — and async_mode: true skips the wait entirely and returns the fan_out_id to poll. It's available via the fan_out MCP tool or POST /api/agents/{name}/fan-out— there is no UI, and it currently works only on the calling agent itself. Every batch gets a server-minted fan_out_id; each subtask is its own execution record stamped with that id and consumes one of the agent's parallel slots, and a batch can be read back while it's still running with get_fan_out_result or GET /api/agents/{name}/fan-out/{fan_out_id}. See Fan-Out.
What are skills and playbooks, and how do I run one?
A skill is a reusable capability packaged in the platform's skills library — one or more GitHub repositories synced to Trinity. Each skill is a folder built around a SKILL.md instruction file, optionally bundled with supporting scripts, templates, and resources. The agent's Skills tab lists its own skills under Own skills and the ones assigned to it from the library under Shared skills, each with a Run button that sends the skill as a task, and in the Chat tab you can type / to autocomplete a skill command with ghost text showing the syntax and argument hints. That tab used to be called Playbooks; API names such as run_playbook keep the old word. See Skills and Playbooks.
How do I find out which agents already have a given skill?
The Librarypage's Skills tab (/library?tab=skills) shows, for every skill, an Assigned to N agentsline with chips linking straight to each agent's Skills tab. It's bounded — the first four agents, then +N more. Admins see the whole fleet; everyone else sees their own and shared agents, and the wording says which. Below the listing sits Assigned but no longer in the library: assignments whose skill was removed upstream. That list matters because revocation works by publishing a new version without the offending skill, and the package stays on each agent until you unassign it — with the ×on its chip right there, or from the agent's Skills tab. See Skills and Playbooks.
Can I assign a skill from the Library page?
Yes. Each skill card on the Library's Skills tab has an Assign to…control listing the agents you may still assign it to — agents you own (an admin sees every agent), minus those that already hold it. Pick one and click Assign; the delivery note appears under the control: Assigned and delivered — available now, applies on next start, or a named failure. The ×on an agent chip unassigns the skill from that agent, and it appears only where you're allowed to make the change — an agent merely shared with you shows as a holder but carries no control. Both surfaces write the same per-agent assignment, so it doesn't matter whether you start from the skill or from the agent's Skills tab. There is no Sync button on the Library; to retry a failed delivery, assign the same agent again. See Skills and Playbooks.
What happens if I assign a skill the library marked deprecated?
It works. A deprecated skill stays listed, assignable and injected; Trinity flags it rather than hiding it. The Library card and the agent's Skills tab show a deprecated badge and, when the library named one, a Superseded by … line, and the assign or save shows a warning line naming the successor. An agent that already holds the skill keeps it unchanged until the library deletes it, after which it shows under Assigned but no longer in the library. See Skills and Playbooks.
Can a skill be a whole folder of files instead of a single markdown file?
Yes. A skill is a full-directory package, not just one markdown file: alongside the SKILL.mdinstructions it can carry scripts, templates, and any resource files the capability needs. When the skill is assigned, Trinity injects the entire directory into the agent, versioned by the folder's content so re-syncs only push real changes. This lets a skill ship helper code and assets, not only prose. See Skills and Playbooks.
Why does my playbook say "No description available"?
The agent's Skills tab, the /popup, and the chat empty state take a skill's description from the description: field in its SKILL.md frontmatter, so first check that the field is there; a card without one reads No description (the Playbooks tab it replaced said No description available). On an agent running an older base image, one unreadable frontmatter field blanked the whole record — most often Claude Code's comma-separated allowed-tools: Read, Bash— and the skill showed only its folder name. Current agent images read each field on its own, accept both the comma-separated and the list form of allowed-tools, and drop only the bad field, with one warning in the agent log naming the file and field. To pick that up on an existing agent, rebuild or re-pull the agent base image and start the agent cold. See Skills and Playbooks.
Does a skill's allowed-tools frontmatter limit what the agent can do?
Not in Trinity. The agent reads the field — in Claude Code's comma-separated form (Read, Bash, Bash(git:*)) or as a YAML list — and reports it in its skill listing, but nothing in Trinity enforces it. To restrict the tools a run may use, set allowed tools on the schedule, loop, or task that runs it. See Skills and Playbooks.
How do I assign skills to an agent, and do I need to restart it?
No restart. Open the agent's Skills tab, click Assign skills, tick the skills, and click Save assignments— the save delivers straight away to a running agent, and the note under the button says what happened: delivered — available now, the agent is stopped, so it applies on next start, still installing (a large package outlived the 20-second wait and continues in the background), or a named failure. Each skill lands as a whole directory under ~/.claude/skills/<name>/, so its scripts and resources come too, and the per-skill result tells you honestly whether it's missing a declared binary or environment variable. Sync nowis the repair action for a delivery that didn't land, not a required step, and every assignment change refreshes the open Skills tab and / autocomplete without a reload. Admins manage the sources the library syncs from in Settings → Agents; skills themselves are edited in their GitHub repository, not in Trinity. See Skills and Playbooks.
Why does a library skill show "name conflict" instead of installing?
The agent already has its own .claude/skills/<name>/ directory that the platform did not create — usually a skill the agent wrote itself. Trinity never overwrites it: the agent's copy stays and is the one that runs, and Sync nowdoes not change that. To keep the agent's skill, open the note on the skill's card under Shared skills on the Skills tab and click Unassign library skill. To use the library version, rename or remove the agent's directory and sync again. See Skills and Playbooks.
Why is my orchestrator agent refused with skill_management_not_permitted?
Changing an agent's skills — another agent's or its own — is a separate permission, and no agent holds it by default. An admin grants it in Settings → Agents → Skill managers, or with the Change skillstoggle on the agent's Settings tab; only a person at the UI can grant or revoke it. People who own the agent, admins and the system agent are not affected. A granted agent still reaches only its owner's agents. The same kind of named refusal covers other agents' schedules, instructions and agent management, each with its own permission. See Skills and Playbooks → Who can change an agent's skills and Agent Configuration → Permissions to change itself.
How do I make a skill wait for someone's approval before it runs?
Open the agent's Skills tab and, as its owner or an admin, turn on Requires approvalon the skill's card and pick who approves: the primary contact, an approver role where your install offers one, or one of the roles from the agent's canon, listed under Roles. From then on any request that names the skill — from a person, another agent, a schedule or a channel — is held before the agent sees it, and the approver gets a card to approve or reject. The approvers must be able to open the agent: the picker marks a role whose people cannot as (not shared), and a role nobody fills as (nobody yet). When the approver asks for it themselves, it runs at once and is marked Ran without approval. Gates are per agent, and can also be set over the API or with the set_skill_gate MCP tool. See Skills and Playbooks → Requiring approval for a skill.
What happens after a gated skill request is approved?
The request runs once, exactly as it appeared on the card, as a new execution on the agent. An agent that asked gets a notice when the request is decided and a second when the approved run ends, with its status and a short quote of the reply or error; a person gets the same two notices in their Workspace Inbox, and the notice line in the Chat tab quotes the run's reply the same way. Each notice opens with the outcome (Approved, now running, Finished successfully, Failed, …), and a rejection carries the approver's reason when one was typed. An agent that asked while answering someone in a conversation writes its reply into that conversation, headed Approval update in the Workspace. Schedules, channel users and public-link visitors get only the request id up front. A rejection, an expiry or a cancellation runs nothing. See Approvals → Gated-skill approvals.
What does the approval card for a gated skill show, and who gets it?
The card shows which agent would run which skill (each with its description), the exact input that Approveruns, any context lines the agent would also receive, who asked — a person by email, an agent by name, or A schedule, A messaging-channel user, A public-link visitor — when it was raised and the deadline. A request typed in the Chat tab with earlier turns as context leads with that message as Request, with the full text below it. It goes to the people in the approver role the gate names who can also open the agent, in their Workspace Inbox, on the Operations page and on the mobile admin; only they get Approve / Reject, and everyone else reads who it is waiting on. Once decided, the card says how it ended — Approved, Ran, Rejected, Expired, Cancelled, Stale, Not run or Not confirmed— and links to the run for platform users who can open it. See Approvals → Gated-skill approvals.
Why didn't I receive an approval request for a gated skill?
Most often because you cannot open the agent. An approval reaches only the people in the approver role who own the agent, have it shared with them or are admins; if the role names you but the agent is not shared with you, the request is refused with approver_cannot_open_agentand nothing is raised — the agent's Skills tab shows the gate as not shared with them, and sharing the agent fixes it. If nobody fills the role at all, the request is refused with role_unassigned instead. If you asked for the skill yourself, as the approver, it ran at once without a card and was marked Ran without approval. And an approval that was raised but already decided, expired or cancelled has left the Inbox's Actiontab — look under All, or on the Operations page's Resolved tab. See Approvals → Gated-skill approvals.
What happens when an agent's work needs a human decision?
The agent raises an ask (a question or an approval) with ask_operatorand ends its turn. The ask doesn't block the agent while it waits. It goes to the person in the role it's addressed to, by default the agent's primary contact, and the owner when nobody holds that seat. An ask addressed to a canon role (role:<id>, where your install provides roles) has no such fallback: when it reaches nobody (roles unavailable on the install, nobody seated, or nobody seated who can open the agent), the ask is refused and the agent is told why. That person sees it in their Workspace Inbox. Whento ask is the agent's own rule, written in its instructions or a shared policy. Role assignments under the agent's Settings › People decide only whogets asked. If a skill must never run without sign-off, don't leave that to the agent's judgment: turn on Requires approval for the skill so Trinity holds every request before the agent sees it. See Approvals → Asks addressed to a Workspace user and How do I make a skill wait for someone's approval before it runs?.
How can I see whether a schedule is actually performing well?
Three places, no setup required. The Schedules tab shows inline stats per schedule (7-day success rate, average duration, last-run status dot); the agent's Overview tab has a "Schedules performance" section rolling up every schedule over a 7/14/30-day window; and clicking Show execution history on a schedule opens a detailed Analytics card with run counts, success rate, duration percentiles (p50/p95/p99), total cost, top tools called, and a daily timeline, switchable between 24h, 7d, and 30d windows. The same data is available via the API and works even when the agent is stopped. See Scheduling.
Can the skills library sync from more than one repository?
Yes. Trinity syncs from any number of GitHub repositories: a bundled public community catalog that ships pre-configured, plus custom repositories your admin adds in Settings → Agents. When two sources ship the same skill name, the lower-priority number wins — custom sources default to 100 and the community source to 1000, so your own repository always wins a clash. Nothing is overwritten silently: the winning skill is marked with which sources it shadows, in the library listing and as a warning at injection time. See Skills and Playbooks.
I upgraded from a single skills-library URL — where did my library go?
It became a source. An install 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 — nothing for an admin to do. If the install already has sources, the URL is matched against them by repository — https://github.com/Org/repo.git, https://github.com/Org/repo/ and github.com/Org/repoall count as the same source — and nothing changes. A legacy URL naming a repository that is not one of your sources is refused rather than added, because adding a source is an admin action, and Trinity files one low-priority Legacy skills-library adoption refused heads-up in the Operations queue; clearing that row is covered in Troubleshooting. If you want that repository, add it under Settings → Agents → Skills Library. See Skills and Playbooks.
Where do skills have to live inside a source repository?
One of three layouts, tried in order: a root catalog.yaml with a skills_root: key naming the directory; a skills/ directory containing at least one <name>/SKILL.md; or the legacy .claude/skills/. Existing repositories keep working with no configuration, and an invalid declaration falls through to the next layout rather than blanking the source. See Skills and Playbooks.
Will a skills-library update reach my running agents automatically?
Only if you turn it on — both automation settings default to off. Under Settings → Agents → Skills Library → Automation, enable Auto-sync to pull sources on an interval (default hourly), and Fleet re-inject to push changed packages to running agents. Re-inject fires only when a commit actually moved, so a no-op pull never sweeps the fleet, and stopped agents pick changes up on their next start. The panel shows the last sync status and the last fleet report, and raises an operator alert if any agent failed. See Skills and Playbooks.
What happens when I unassign a skill — do the files stay on the agent?
No. Unassigning removes the injected package, using the manifest recorded at injection time, so only files the platform wrote are deleted; anything the agent authored survives, and directories left empty are cleaned up. If the agent is stopped, busy, or unreachable, the unassignment still succeeds and the removal is reported as deferred — the agent reconciles on its next start. A reconcile that would strip an unusually large number of skills from one agent refuses outright and raises an operator alert instead. See Skills and Playbooks.
Why is the community skills source pinned to a tag instead of tracking a branch?
Because skills carry executable scripts, and with fleet re-inject on, a source tracking a branch head would put every merged upstream commit onto every agent with no human in the loop — and the community catalog accepts public contributions. The bundled community source is therefore pinned to a release tag of the catalog that we bump; new upstream commits reach your fleet only when an admin moves the source to a newer tag — by editing its ref (PUT /api/skills/sources/{id}) or removing and re-adding it — and syncs. Custom sources track a branch by default, since you control who writes to them, but you can choose Tag under Track when adding one to pin it the same way. A pinned tag that later resolves to a different commit is refused (moved_tag) rather than adopted; annotated and lightweight tags are compared by the commit they point at, so a release tag that hasn't moved is never refused. See Skills and Playbooks.
The add-project-management plugin installs nothing — where did it go?
It's deprecated: it stays in the marketplace for one release as a pointer stub, and its skill now lives in agent-dev as /agent-dev:add-project-management. The runtime skills it installs — /project-init, /project-task, /project-steward, /project-reconcile, /project-intake and, since agent-dev 1.22, /project-status— are also standalone in the agent-dev plugin (now 31 skills) and mirrored into the bundled community skills catalog, so on Trinity you can assign them to a deployed agent from the Library without running the installer at all; /project-init materializes the project standard itself on first run. Also new in agent-dev: /agent-dev:commitdoubles as a plain save — with no issue claimed it becomes a checkpoint commit of the agent-state files (memory, outputs, skills, CLAUDE.md, template.yaml — never .env or anything credential-shaped). See Abilities Marketplace.
Do I need to install the trinity plugin inside my agent before it can run /trinity skills?
No. Trinity's agent image ships with the abilityai marketplace registered and trinity@abilityaiinstalled, and every container boot re-installs it if it's missing — whether or not the agent's template.yamldeclares it. That's what lets an agent created from a bare repository run /trinity:onboard in place and write its own declaration. A plugins: block that omits it never uninstalls it (the boot step only adds), and a declaration that points the abilityai marketplace name at another repository is ignored. An agent still on an image built before the pre-install pays one install at its next boot; an image built with --build-arg TRINITY_PREINSTALL_PLUGINS=0(air-gapped installs) skips the pre-install, and what the boot step couldn't fetch is reported in the agent's compatibility report rather than failing the start. See Abilities Marketplace.
My template declares schedules — will Trinity create them?
Yes. A schedules: block in template.yaml is materialized as real schedules when the agent is created, through the UI, the API, and MCP alike. Each entry needs a name, a strict 5-field cron, and a message; up to 20 per template. A malformed entry is dropped with a named error rather than failing the creation, and every materialized schedule inherits the agent's execution timeout so it can never exceed the agent's own cap. See Creating Agents.
What should a schedule's message contain?
Ideally a single line that invokes one of the agent's skills by name — /daily-briefing— and nothing else: no inline instructions, arguments, or business logic. The logic then lives in the versioned playbook, so changing what a scheduled run does is an edit to the skill, and the execution history shows which playbook ran. A prose message is a second, unversioned copy of the procedure that drifts from the skill it describes. /create-agent:custom generates schedules in this shape and /create-agent:review flags prose messages as findings. See Scheduling.
My scheduled skill hangs every run and burns its whole timeout — why?
The skill almost certainly asks a question at one of its decision points. On an unattended cron there is nobody to answer, so every run blocks on the prompt until the execution times out with nothing committed. The fix belongs in the skill, not in the schedule message: give it a headless run mode — the abilities convention is a --autonomous argument, so the schedule message becomes /<skill> --autonomous— in which the skill never prompts, takes the safe default at each gate, never takes a destructive path a gate was protecting, and records any non-trivial decision as a needs-attentionline instead of guessing. The orchestrator bundle's gated skills already ship this mode. See Abilities Marketplace.
Can an agent trigger a schedule to get around the agent-to-agent chain limit?
No. When an agent triggers a schedule with its own key, for example with trigger_agent_schedule, the run counts as one more hop in that agent's call chain, just like chat_with_agent. A trigger past the limit (8 hops by default) is refused with 403 inter_agent_depth_exceeded before anything runs, and a retry of that run keeps its depth. Cron fires, webhook fires and Run now from the UI start a new chain. See Scheduling.
How do I stop a webhook sender's retries from firing my schedule twice?
Send an Idempotency-Key header with each delivery, using a value that stays the same when the sender retries the same event. A repeat with the same key within 24 hours returns the first result with X-Idempotent-Replay: true instead of firing again, or 409 while the first delivery is still running. A call without the header fires every time, so a plain ping-to-trigger is never swallowed. See Webhook Triggers.
What does "Something else" on an approval do?
It tells the agent that none of its options is approved and gives it your own instruction instead. Every approval an agent raises offers it, on the Operations page, the mobile admin and the Workspace. The instruction is required (up to 4,000 characters), and the agent carries out none of the listed options and re-plans from what you wrote. Approvals the platform raised itself offer only their own options. See Approvals.
Why was my agent's ask refused with too_many_options or title_too_long?
Trinity keeps each ask to one decision a person can take at a glance. By default an approval may offer at most 5 options (Something else not counted), each at most 60 characters, with a title of at most 120 characters, and an option that imitates Something else is refused as invalid_options. ask_operator returns the code and the limit in force; a queue-file entry over a limit is held in the file with its id listed under platform.ingestion until the agent fixes it. Split two decisions into two asks and move the reasoning into the question. See Approvals.
Can I talk an ask through with the agent before I answer it?
Yes, in the Workspace. Click Discuss on an approval or a question to open a chat with the agent about that ask; the ask heads the chat and stays pending until you answer it on its own card. Clicking again shows Continue discussionand reopens the same chat. If you answer after discussing and the owner has turned on the wake, the agent's result is posted into that chat. See Approvals.
How do I tell an agent its ask doesn't need a decision?
Click Dismiss on the ask in the Workspace. It ends without an answer, after a 5-second Undo window and with no confirmation. The agent reads it as dismissed with an empty answer and is told not to raise the same ask again straight away; if its owner turned on the wake, it is woken once. Alerts have no Dismiss: acknowledge them with Got it. See Approvals.
Why does an expired approval say "whether the action went ahead is unknown"?
Because the agent, not Trinity, held that action. When an agent asks for approval and nobody answers before the deadline, the ask expires as not approved, but Trinity cannot see whether the agent went ahead anyway. The Resolved tab, the queue detail and the mobile admin say so, and the agent reads disposition_reason: "outcome_unknown". An expired approval for a gated skill never says this: the platform held that request, so nothing ran. See Approvals.
Why does a heads-up in the Operations queue say "seen 5 times" instead of filing new rows?
Some platform heads-ups describe a condition, such as a subscription low on headroom or a refused skills-library URL. Trinity keeps one pending row per condition and updates it with each new reading, so the card counts how often it was seen and when last. When the condition clears, the platform ends the row itself (Ended by the platform — the condition cleared); otherwise it expires 14 days after its last reading. After you end one, the same reading files nothing for 7 days unless its priority rises. See Approvals.
Why did my agent get a "queue flood" heads-up?
The agent has too many open asks or is raising them too fast. Each agent may have 25 pending asks of its own and create 60 per minute by default; over that, new asks are refused (429 queue_full or rate_limited) or, from the queue file, held and admitted later. Trinity files one queue-flood heads-up per episode, and the platform's own heads-ups never count toward the agent's 25. Answer or cancel some of the agent's open asks, and fix whatever makes it ask so often. See Approvals.
Can I use a legacy timezone name like US/Eastern in a schedule?
Yes — legacy IANA aliases such as US/Eastern, Asia/Calcutta, and Europe/Kiev resolve correctly. A timezone the platform genuinely cannot resolve is rejected when you create the schedule, with a message naming the problem, rather than being accepted and then silently never firing. See Scheduling.