OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add twillai/skills --skill twill-cloud-coding-agent
Use Twill Cloud Coding Agent to manage Twill's public v1 API workflows. Create/list/update tasks, stream and cancel jobs, manage scheduled tasks, list repositories, and export Claude teleport sessions.
npx skills add twillai/skills --skill twill-cloud-coding-agent
Use this skill to run Twill workflows through the public v1 API.
Set API key and optional base URL:
All API calls use:
Authorization: Bearer $TWILL_API_KEY
Use this helper to reduce repetition:
GET /api/v1/auth/meGET /api/v1/repositoriesPOST /api/v1/tasksGET /api/v1/tasksGET /api/v1/tasks/:taskIdOrSlugPOST /api/v1/tasks/:taskIdOrSlug/messagesGET /api/v1/tasks/:taskIdOrSlug/jobsPOST /api/v1/tasks/:taskIdOrSlug/approve-planPOST /api/v1/tasks/:taskIdOrSlug/cancelPOST /api/v1/tasks/:taskIdOrSlug/archiveGET /api/v1/tasks/:taskIdOrSlug/teleport/claudeGET /api/v1/jobs/:jobId/logs/streamPOST /api/v1/jobs/:jobId/cancelGET /api/v1/scheduled-tasksPOST /api/v1/scheduled-tasksGET /api/v1/scheduled-tasks/:scheduledTaskIdPATCH /api/v1/scheduled-tasks/:scheduledTaskIdDELETE /api/v1/scheduled-tasks/:scheduledTaskIdPOST /api/v1/scheduled-tasks/:scheduledTaskId/pausePOST /api/v1/scheduled-tasks/:scheduledTaskId/resumeValidate key and workspace context:
List available GitHub repositories for the workspace:
Repository and branch are no longer accepted in the request body — the task runs against the workspace's connected repos as resolved by the agent at runtime.
Required fields:
commandOptional fields:
agent (provider or provider/model, for example codex or codex/gpt-5.4; provider shorthands accepted: claude-code, codex, open-code)userIntent (SWE, PLAN, ASK, DEV_ENVIRONMENT) — defaults to SWEreasoningEffort (low, medium, high, xhigh)parentId (id of an existing task to spawn this one from)titlefiles (array of { filename, mediaType, url })Response is { task: { id, slug, title, url }, job: { id, status } }. Always report task.url back to the user.
Supports cursor pagination via limit (default 20, max 100) and cursor. Response is { tasks, nextCursor }; each task includes id, slug, title, url, createdAt, latestJobStatus, and pr.
Returns task metadata plus latestJob including id, status, type, agentProvider, startedAt, completedAt, plan, planOutcome, finalAnswer (useful for ASK jobs), and pr when available.
Sending a message cancels any in-flight job for the task and starts a fresh run with this message (API/CLI bypass the UI queueing flow).
Optional fields: userIntent, reasoningEffort (low, medium, high, xhigh), files.
Supports cursor pagination:
limit defaults to 30 (max 100)cursor fetches older pagesjobs and nextCursorUse when the latest plan job is completed and ready for approval.
Stream emits JSON payloads in data: lines and terminates with a complete event.
Required: title (max 200 chars), message, cronExpression.
Optional: timezone (IANA name, defaults to "UTC"), agentProviderId (provider/model override, e.g. claude-code/sonnet, codex/gpt-5.4).
Repository / branch are no longer part of the scheduled-task payload — each run resolves repos at agent dispatch time, the same way one-shot tasks do.
Response is { scheduledTask: { id, workspaceId, createdById, title, message, cronExpression, timezone, nextRunAt, lastRunAt, enabled, agentProviderId, createdAt, updatedAt } }.
PATCH accepts any subset of title, message, cronExpression, timezone, agentProviderId (pass null to clear the override). DELETE returns { "success": true }.
userIntent (SWE, PLAN, ASK, DEV_ENVIRONMENT) when calling API endpoints directly.repository / branch on tasks or repositoryUrl / baseBranch on scheduled tasks — these fields were removed; repo/branch is resolved by the agent at run time from workspace context.task.url, and only poll/stream logs when requested.TWILL_API_KEY if missing.api() {
curl -sS "$@" -H "Authorization: Bearer $TWILL_API_KEY" -H "Content-Type: application/json"
}curl -sS "$TWILL_BASE_URL/api/v1/auth/me" -H "Authorization: Bearer $TWILL_API_KEY"curl -sS "$TWILL_BASE_URL/api/v1/repositories" -H "Authorization: Bearer $TWILL_API_KEY"api -X POST "$TWILL_BASE_URL/api/v1/tasks" -d '{"command":"Fix flaky tests in CI","userIntent":"SWE"}'curl -sS "$TWILL_BASE_URL/api/v1/tasks?limit=20&cursor=BASE64_CURSOR" -H "Authorization: Bearer $TWILL_API_KEY"curl -sS "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG" -H "Authorization: Bearer $TWILL_API_KEY"api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/messages" -d '{"message":"Please prioritize login flow first","userIntent":"PLAN"}'curl -sS "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/jobs?limit=30&cursor=BASE64_CURSOR" -H "Authorization: Bearer $TWILL_API_KEY"api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/approve-plan" -d '{}'api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/cancel" -d '{}'api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/archive" -d '{}'curl -N "$TWILL_BASE_URL/api/v1/jobs/JOB_ID/logs/stream" -H "Authorization: Bearer $TWILL_API_KEY" -H "Accept: text/event-stream"api -X POST "$TWILL_BASE_URL/api/v1/jobs/JOB_ID/cancel" -d '{}'curl -sS "$TWILL_BASE_URL/api/v1/scheduled-tasks" -H "Authorization: Bearer $TWILL_API_KEY"
api -X POST "$TWILL_BASE_URL/api/v1/scheduled-tasks" -d '{
"title":"Daily triage",
"message":"Review urgent issues and open tasks",
"cronExpression":"0 9 * * 1-5",
"timezone":"America/New_York",
"agentProviderId":"claude-code/sonnet"
}'curl -sS "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID" -H "Authorization: Bearer $TWILL_API_KEY"
api -X PATCH "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID" -d '{
"message":"Updated instructions",
"cronExpression":"0 10 * * 1-5",
"agentProviderId":"codex/gpt-5.4"
}'
curl -sS -X DELETE "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID" -H "Authorization: Bearer $TWILL_API_KEY"api -X POST "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID/pause" -d '{}'
api -X POST "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID/resume" -d '{}'