twill-cloud-coding-agent

v2026.09.24
twillai/skills00

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.

GitHub
安装命令
npx skhub add twillai/twill-cloud-coding-agent
Markdown
SKILL.md

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.
发现
标签

此技能尚未发布标签。

版本
最新版本元数据

版本

v2026.09.24

发布时间

Sep 24, 2026

分类

未分类

许可证

未指定

源路径

twill-cloud-coding-agent

默认分支

main

最新提交

8f523cb

Tree SHA

61d2915