AI Skills
twill-cloud-coding-agent

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.

9stars
0forks
Updated 5/24/2026
Get SkillSource Code

Related Skills

homelab-vlan-segmentation238Kbackend-code-review153Kpr-triage81K
SKILL.md
read-only
name
twill-cloud-coding-agent
description

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.

Twill Cloud Coding Agent

Use this skill to run Twill workflows through the public v1 API.

Setup

Set API key and optional base URL:

export TWILL_API_KEY="your_api_key"
export TWILL_BASE_URL="${TWILL_BASE_URL:-https://twill.ai}"

All API calls use:

Authorization: Bearer $TWILL_API_KEY

Use this helper to reduce repetition:

api() {
  curl -sS "$@" -H "Authorization: Bearer $TWILL_API_KEY" -H "Content-Type: application/json"
}

Endpoint Coverage (Public v1)

  • GET /api/v1/auth/me
  • GET /api/v1/repositories
  • POST /api/v1/tasks
  • GET /api/v1/tasks
  • GET /api/v1/tasks/:taskIdOrSlug
  • POST /api/v1/tasks/:taskIdOrSlug/messages
  • GET /api/v1/tasks/:taskIdOrSlug/jobs
  • POST /api/v1/tasks/:taskIdOrSlug/approve-plan
  • POST /api/v1/tasks/:taskIdOrSlug/cancel
  • POST /api/v1/tasks/:taskIdOrSlug/archive
  • GET /api/v1/tasks/:taskIdOrSlug/teleport/claude
  • GET /api/v1/jobs/:jobId/logs/stream
  • POST /api/v1/jobs/:jobId/cancel
  • GET /api/v1/scheduled-tasks
  • POST /api/v1/scheduled-tasks
  • GET /api/v1/scheduled-tasks/:scheduledTaskId
  • PATCH /api/v1/scheduled-tasks/:scheduledTaskId
  • DELETE /api/v1/scheduled-tasks/:scheduledTaskId
  • POST /api/v1/scheduled-tasks/:scheduledTaskId/pause
  • POST /api/v1/scheduled-tasks/:scheduledTaskId/resume

Auth and Discovery

Validate key and workspace context:

curl -sS "$TWILL_BASE_URL/api/v1/auth/me" -H "Authorization: Bearer $TWILL_API_KEY"

List available GitHub repositories for the workspace:

curl -sS "$TWILL_BASE_URL/api/v1/repositories" -H "Authorization: Bearer $TWILL_API_KEY"

Tasks

Create Task

api -X POST "$TWILL_BASE_URL/api/v1/tasks" -d '{"command":"Fix flaky tests in CI","userIntent":"SWE"}'

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:

  • command

Optional 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 SWE
  • reasoningEffort (low, medium, high, xhigh)
  • parentId (id of an existing task to spawn this one from)
  • title
  • files (array of { filename, mediaType, url })

Response is { task: { id, slug, title, url }, job: { id, status } }. Always report task.url back to the user.

List Tasks

curl -sS "$TWILL_BASE_URL/api/v1/tasks?limit=20&cursor=BASE64_CURSOR" -H "Authorization: Bearer $TWILL_API_KEY"

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.

Get Task Details

curl -sS "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG" -H "Authorization: Bearer $TWILL_API_KEY"

Returns task metadata plus latestJob including id, status, type, agentProvider, startedAt, completedAt, plan, planOutcome, finalAnswer (useful for ASK jobs), and pr when available.

Send Follow-Up Message

api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/messages" -d '{"message":"Please prioritize login flow first","userIntent":"PLAN"}'

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.

List Task Jobs

curl -sS "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/jobs?limit=30&cursor=BASE64_CURSOR" -H "Authorization: Bearer $TWILL_API_KEY"

Supports cursor pagination:

  • limit defaults to 30 (max 100)
  • cursor fetches older pages
  • response includes jobs and nextCursor

Approve Plan

Use when the latest plan job is completed and ready for approval.

api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/approve-plan" -d '{}'

Cancel Task

api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/cancel" -d '{}'

Archive Task

api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/archive" -d '{}'

Jobs

Stream Job Logs (SSE)

curl -N "$TWILL_BASE_URL/api/v1/jobs/JOB_ID/logs/stream" -H "Authorization: Bearer $TWILL_API_KEY" -H "Accept: text/event-stream"

Stream emits JSON payloads in data: lines and terminates with a complete event.

Cancel Job

api -X POST "$TWILL_BASE_URL/api/v1/jobs/JOB_ID/cancel" -d '{}'

Scheduled Tasks

List and Create

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"
}'

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 } }.

Read, Update, Delete

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"

PATCH accepts any subset of title, message, cronExpression, timezone, agentProviderId (pass null to clear the override). DELETE returns { "success": true }.

Pause and Resume

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 '{}'

Behavior

  • Use userIntent (SWE, PLAN, ASK, DEV_ENVIRONMENT) when calling API endpoints directly.
  • Do not send 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.
  • Create task, report task.url, and only poll/stream logs when requested.
  • Ask for TWILL_API_KEY if missing.
  • Do not print API keys or other secrets.