AGENT SKILL

claude-worker

A headless Claude Code run started in another repository, so the work loads that repository's own instructions instead of the current session's. Use when work belongs to a different repository than the one this session is in ("do this in the other repo", "work on the docs repo from here"), when a subagent would carry the wrong project's rules, or when a run needs its own tool set or settings. Not for work in the current repository (use an ordinary subagent), anything that needs a conversation mid-run, or tasks that need this session's context.

License 许可
MIT
所属仓库
justnnc/skills
最近更新
2026-10-22
Stars
★ 0
Forks
0

01 前言 Front Matter

name
claude-worker
license
MIT
description
A headless Claude Code run started in another repository, so the work loads that repository's own instructions instead of the current session's. Use when work belongs to a different repository than the one this session is in ("do this in the other repo", "work on the docs repo from here"), when a subagent would carry the wrong project's rules, or when a run needs its own tool set or settings. Not for work in the current repository (use an ordinary subagent), anything that needs a conversation mid-run, or tasks that need this session's context.
compatibility
Claude Code CLI on the same machine; commands use Bash-compatible syntax.

03 SKILL.md 正文

Claude as a worker in another repository

This skill starts one non-interactive Claude Code run (claude -p) rooted in another repository and checks what it did. It does not converse with the run, and the run never commits or pushes; the current session stays the supervisor and lands any change itself.

Why not a subagent. A subagent runs inside this session, rooted in this repository, with its instructions and settings. A headless run is a fresh process rooted in the other folder: it loads the instruction files Claude Code finds from there (that repository's, plus your user-level ones) and that folder's project settings. Use it when the other repository's rules should govern the work.

Before the run

Gate: no launch until the brief, the tool set and the target's configuration have all been checked.

  • The brief, in a file. Task, the files it may change, checks it must run and report, a time limit, the report shape and a word limit, and this line: "Leave all edits uncommitted; do not stage, commit, push or run any git command that writes." The run cannot ask, so the brief answers.
  • The tool set. Two flags do different jobs:
    • --tools "Read,Glob,Grep" sets which built-in tools exist at all; use it to keep a read-only run read-only. Add Edit,Write for writing, Bash only with a reason.
    • --allowedTools only pre-approves calls; it does not restrict. With no one to answer, a call that needs approval is denied. Use it to approve what the brief needs, e.g. specific Bash(...) patterns.
  • The target's configuration. A headless run can execute the repository's hooks and start its MCP servers without a trust prompt. Open the target's .claude/settings.json, .mcp.json and any plugin it enables before a first run there; do not launch into a repository you would not run code from.
  • Credentials. The run inherits your environment. For a writable run, unset tokens it does not need.
  • Cost and finish time, stated to the user before starting.

The run

cd <other-repo> && claude -p --model sonnet --tools "Read,Glob,Grep,Edit,Write" \
  --allowedTools "Edit,Write" < <scratch>/brief.md > <scratch>/out.txt 2>&1
status=$?; echo "exit $status"
  • Approve the writes. --tools makes Edit and Write exist; --allowedTools lets them run without a prompt nobody can answer. Drop both for a read-only run.
  • Prompt on stdin. List-valued flags such as --tools can absorb a positional prompt after them; stdin avoids that entirely.
  • --model takes an alias (sonnet, opus, haiku) or a full model ID.
  • Root it in the other folder. That folder decides which instruction files and project settings load. Do not add --bare: it skips instruction-file discovery, which is the point of this skill.
  • Run it detached and wait for it to exit; a real task outlasts a normal command timeout. Enforce the time limit from outside too (a timeout wrapper or stopping the process), not only in the brief.
  • One run, one brief. A run in progress cannot be messaged. To change course, stop it and start fresh.

After it returns

Gate: nothing from the run is relayed or landed until these hold.

  1. Exit status is zero. Otherwise read the tail of out.txt (login, quota, a denied tool) and report it; do not retry in a loop.
  2. The full change is known. In the target repository, git status and git diff, not only the files the run says it changed. git log shows no new commits and refs are unchanged.
  3. The brief's checks pass, run by you, not taken from the report.
  4. Report what changed, what was checked, and what the run could not do. The supervisor commits, by the target repository's own rules, only when the user says so.

Done when the change is verified against the diff and checks and reported, or the failure is reported with its reason.

Failure modes

  • Trusting the report. The run lists the files it meant to change. Read the diff instead.
  • Approving instead of restricting. A long --allowedTools list feels safe and restricts nothing. Use --tools for the set, --allowedTools for approvals.
  • Launching into unknown configuration. Hooks and MCP servers run without a prompt. Check them first.

Untested across platforms and versions beyond the Claude Code release it was written against; check claude --help if a flag is refused.

04 同仓库更多 Skills

justnnc
justnnc/skills

codex-worker

The OpenAI Codex CLI as a worker under Claude. Use when the user names Codex ("have Codex review this", "ask Codex", "run this on Codex", "hand this to Codex"), wants work done on Codex's quota instead of Claude tokens, or wants a review from another model family. Not for tasks that need this conversation's context, the user's running application, or tools only Claude has.

★ 0
justnnc
justnnc/skills

spec-audit

A read-only audit of a project's specs against the work that just landed. Use when a batch, feature or set of changes has been merged or is about to be pushed, when the user asks whether a spec is up to date, accurate or drifted from the code, or before a design discussion leans on a spec's text. Not for writing a new spec or design document, reviewing a design document, reviewing code for bugs, or planning work that is not built yet.

★ 0
justnnc
justnnc/skills

skill-craft

A craft checklist for agent skills. Use when the user asks to write, improve, review, test or tighten a skill, a SKILL.md, an agent definition or a reusable brief, or asks why an agent skips, misreads or never triggers a skill. Not for the subject matter of a skill, only how it is written.

★ 0
justnnc
justnnc/skills

prove-by-running

Execution proof that a script or tool works. Use when about to trust a new or changed script, hook, migration or release tool, and always for anything that rewrites git history, publishes or pushes, deletes, or transforms data; also when the user asks "does this actually work", "test this script", "prove it" or "try it on a copy first". Not for reviewing code by reading it, for writing unit tests of a library, or for fixing the faults found.

★ 0
justnnc
justnnc/skills

parallel-refactor

A fan-out of one large mechanical code change across parallel subagents. Use when a refactor, rename, migration or API move touches hundreds of call sites across many files, when the user asks to split a change per file or component or hand it to several agents at once, or asks how big a change is and whether it is mechanical. Not for edits inside one file, a redesign whose target shape is not yet decided, or a change small enough to make serially.

★ 0
justnnc
justnnc/skills

how-it-works

A cited, read-only explanation of how a mechanism in a codebase works. Use when the user asks "how does X work in this code", "where is Y computed", "walk me through Z", or wants a reference implementation read to compare with their own, in a large or unfamiliar codebase. Not for a file or function already known (just read it), bug hunting or debugging, reviewing a diff, or changing code.

★ 0