Agent Skills › YaoApp/yao › yao-job

yao-job

GitHub

管理后台任务，支持启动、监控、等待及终止长时间运行的命令。提供作业列表查询、状态过滤、输出读取（含环形缓冲区处理）及详细结果获取功能。

tools/skills/yao-job/SKILL.md YaoApp/yao

触发场景

运行后台任务检查作业状态读取作业输出管理长时间运行的命令

安装

npx skills add YaoApp/yao --skill yao-job -g -y

更多选项

非标准路径

npx skills add https://github.com/YaoApp/yao/tree/main/tools/skills/yao-job -g -y

不安装直接使用

npx skills use YaoApp/yao@yao-job

指定 Agent (Claude Code)

npx skills add YaoApp/yao --skill yao-job -a claude-code -g -y

安装 repo 全部 skill

npx skills add YaoApp/yao --all -g -y

预览 repo 内 skill

npx skills add YaoApp/yao --list

SKILL.md

Frontmatter

{
    "name": "yao-job",
    "description": "Background job management — start, monitor, wait, stop long-running commands. ALWAYS invoke this skill when the user asks to run background tasks, check job status, read job output, or manage long-running commands."
}

Background Jobs

Tools

yao_job_start — Start a command. background false (default) blocks until done and returns output_tail; background true returns job_id immediately.
yao_job_list — List jobs. Supports --status filter and --limit/--offset pagination.
yao_job_get — Get full details for a job (or daemon by ID).
yao_job_output — Read process output (works for both job and daemon IDs).
yao_job_wait — Block until a background job finishes or timeout expires. Jobs only, not daemons.
yao_job_stop — Kill a running job.

Parameters

yao_job_start

Param	Required	Default	Description
`command`	yes	—	Shell command to execute
`description`	yes	—	Concise 5–10 word summary
`background`	no	`false`	`true` returns immediately; `false` blocks until done
`args`	no	—	Additional arguments (rarely needed; prefer inline in `command`)
`working_dir`	no	workspace	Working directory
`max_duration_ms`	no	—	Kill the job after this many milliseconds

yao_job_list

Param	Default	Description
`status`	all	Filter: `running`, `stopping`, `completed`, `failed`, `cancelled`, `all`
`limit`	20	Max items per page
`offset`	0	Skip first N items

yao_job_output

Param	Required	Description
`job_id`	yes	Job or daemon ID
`offset`	no	Byte offset to read from (0 = beginning)

Output read behavior:

Returns all available content from offset in a single read (no limit parameter).
Ring buffer caps at 10 MB; older content beyond this is discarded.
When content has been discarded, lossy=true in the response.
size = total bytes the process has produced; offset = earliest readable byte position.
Example: a 20 MB output has size=20000000, offset≈10000000, lossy=true — the first ~10 MB was discarded.

yao_job_wait

Param	Required	Default	Description
`job_id`	yes	—	Job ID
`timeout_ms`	no	60000	Timeout in milliseconds

Response Fields

All responses are JSON. Job objects contain:

id, kind, session_id, status, description, background,
command, command_argv, command_line, pid, pgid, user,
started_at, finished_at, duration_ms, exit_code, signal, detail, seq

Foreground start (background=false)

Returns the job object plus output_tail (≤4KB tail of stdout+stderr):

{ "id": "job_...", "status": "completed", "exit_code": 0, ..., "output_tail": "hello world\n" }

List (paginated)

{ "jobs": [...], "total": 130, "offset": 0, "limit": 20, "has_more": true }

Wait

{ "job": { ... }, "timed_out": false }

Stop (already terminal)

{ "job": { ... }, "detail": "already in terminal state (failed); no action taken" }

Errors

Structured JSON with code and message:

{ "error": { "code": "invalid_argument", "message": "job_id is required" } }

Codes: invalid_argument, not_found, internal.

Usage Rules

Use background true (not bare --background) for commands expected to run longer than 30 seconds.
Always provide a description.
Foreground is default — the result and output come back in one call.
Monitor background output with yao_job_output to check progress.
Use yao_job_wait to block until a background job completes rather than polling.