AGENT SKILL

autonomous-agent-design

Use when designing or evaluating an autonomous agent workflow. Covers task decomposition, tool scoping, result contracts, failure modes, and the shadow → draft → autonomous maturity sequence.

License 许可
MIT
所属仓库
pixeloven/crew
最近更新
2026-11-07
Stars
★ 1
Forks
0

01 前言 Front Matter

name
autonomous-agent-design
tier
concept
requires
[]
description
Use when designing or evaluating an autonomous agent workflow. Covers task decomposition, tool scoping, result contracts, failure modes, and the shadow → draft → autonomous maturity sequence.
expects-local
[ "agent-runtime" ]

03 SKILL.md 正文

Core design principles

Behavioral specialization → skills. Operational specialization → agents. Most specialization pressure resolves into a skill file, not a new agent. Only add an agent when the role genuinely requires a different stance or different tool scope.

Generic role agents, domain knowledge in skills. Six role agents (Lead, Triage, Investigator, Researcher, Implementer, Reviewer) cover the work modes. A consumer with a genuinely different work mode adds its own role in its overlay — curation, for instance, is a Librarian in one deployment and nothing at all in another. Specificity flows through skill composition.

Privilege gradient. Read-only and draft-only agents cover most work. Implementer is the deliberate write path. Design new capabilities at the lowest privilege level that accomplishes the task.

Task decomposition

Well-designed autonomous tasks are:

  • Bounded — a clear start state, end state, and definition of done
  • Single-purpose — one agent, one responsibility per task
  • Checkable — acceptance criteria that are machine-verifiable, not "looks right"
  • Recoverable — a defined action if the task fails (retry, escalate, or skip)

Complex work that spans multiple tasks belongs in a plan, not a single agent invocation.

Tool scoping

Give each agent the minimum tools needed for its role:

Agent Write tools? Cluster access?
Triage Labels and comments only No
Researcher Research note and issue comments; reply drafts in its response, never posted No
Investigator Issues and comments Read-only
Reviewer PR comments only No
Implementer Code, manifests, PRs No (via the GitOps controller)
Lead Issues, plans, dispatch No

Don't give an agent write access it doesn't need. A Researcher that can push code is a liability.

Result contracts

Every autonomous agent produces a structured result. The result must be:

  • Written to a structured result file at a path the runtime defines
  • Parseable by the orchestrator (Lead or the runtime's exit handler)
  • Sufficient for the next phase to proceed without re-reading the agent's full output

Minimum result fields: summary, status (success/partial/failed), list of artifacts produced.

Failure modes

Design for three failure classes:

Class Handling
Transient Retry with backoff — network, rate limit, temporary unavailability
Structural No retry — escalate to human; task is broken
Success Proceed to next phase

The concrete signaling (exit codes, result-file status fields) is the runtime's contract — see the project's agent-runtime local skill. A common mapping uses 75 / 1 / 0 for transient / structural / success, but the local contract is authoritative.

A task that silently succeeds while producing wrong output is worse than a clean failure. Validate output before signaling success.

Maturity sequence

Shadow → Draft → Autonomous. Never skip stages.

Stage Agent behavior Human role
Shadow Runs, produces output, takes no action Reviews output manually
Draft Produces artifacts (PRs, issue drafts, comments) but does not publish Reviews and approves before publish
Autonomous Runs and publishes without review Reviews asynchronously; intervenes on escalation

Earn autonomy on narrow, well-understood surfaces before expanding. A reviewer that auto-merges PRs is not a reviewer — it's a rubber stamp.

Idempotency

Autonomous agents run repeatedly — scheduled sweeps, retries, re-triggers. Every agent action must be safe to run twice:

  • Opening an issue: check for duplicates before filing
  • Writing a vault note: check the substrate first (see the project's knowledge-capture local skill Read Routing) so you don't duplicate prior analysis
  • Applying labels: idempotent by nature
  • Writing code: operate on a fresh branch per task

04 同仓库更多 Skills