Best-Effort Delivery

Keep moving without turning uncertainty into hidden risk.

Best-Effort Delivery is an Agent Skill for broad or ambiguous tasks where the user wants an autonomous pass without repeated clarification. It completes evidence-backed work immediately and batches genuine judgment calls into one interactive HTML review document.

Quickstart

Install the Skill:

npx skills add HuaTalk/best-effort-delivery-skill

Then ask your agent to proceed autonomously:

Use best-effort delivery. Do not ask me questions; finish everything you can and collect uncertain decisions for review.

The agent edits high-confidence source-of-truth files, validates those changes, and returns one temporary HTML path only when low-confidence decisions remain.

How It Works

The Skill decomposes work into independently assessable units and assigns each unit to exactly one tier:

| Tier | Result | Standard | |---|---|---| | High confidence | Land directly in source-of-truth files | Supported by repository evidence and easy to verify and revert | | Low confidence | Add to an interactive pending-confirmation document | Requires business judgment, has several valid interpretations, or is costly to reverse |

The review document makes every unresolved item a concrete single-choice decision. Recommended options are preselected, each question carries its evidence, and one action exports all choices as JSON for an idempotent follow-up pass.

Best effort changes the interaction pattern, not the agent's authority. Destructive operations, external messages, publication, and other consequential actions still follow the host agent's normal approval rules.

Installation

Agent Skills

Use this for Codex, Cursor, Windsurf, Gemini CLI, GitHub Copilot, Cline, and other Agent Skills-compatible tools:

npx skills add HuaTalk/best-effort-delivery-skill

npm

For environments using skills-npm:

npm install -D @huatalk/best-effort-delivery-skill
npx skills-npm setup

This channel becomes available after the first tagged npm release. Until then, install directly from GitHub with Agent Skills.

Claude Code

Register the repository as a plugin marketplace:

/plugin marketplace add https://github.com/HuaTalk/best-effort-delivery-skill.git

Install the plugin in a separate prompt:

/plugin install best-effort-delivery@best-effort-delivery

Restart Claude Code after installation. The native command is /best-effort-delivery:best-effort-delivery; the shorter /best-effort-delivery works when unambiguous.

Basic Workflow

1. Decompose - Split the goal into independently assessable units.
2. Gather evidence - Read local contracts, code, documentation, tests, and user-provided material.
3. Land high-confidence work - Complete and verify changes directly in source-of-truth files.
4. Batch uncertainty - Put genuine decisions into one temporary interactive HTML document, never into repository TODOs.
5. Review once - Accept defaults or choose alternatives, then export one JSON payload.
6. Resume idempotently - Apply only newly decided items after checking that their evidence is still current.

See worked examples for typical task shapes.

Interactive Review Contract

Every pending decision includes:

• Two to four concrete options plus an Other write-in.
• A safe recommended choice selected by default.
• A file/section target and a short evidence excerpt.
• A visible decided/total count.
• JSON export with id, target, choice, choiceLabel, and other.
• One serialized data source rendered with safe text APIs, so repository excerpts cannot become executable HTML and exported values cannot drift from the visible choices.

The document is written to the operating system's temporary directory, not the repository. It is a transient handoff artifact, not project documentation.

Triggering the Skill

The Skill is designed for explicit unattended-delivery intent:

Best effort; do not ask me.
Proceed autonomously and collect uncertain decisions for later.
Do everything you can while I am away.

It is not the default for small tasks where one clarification would immediately settle the result, nor does it override safety and authorization boundaries.

Design Principles

• Progress and restraint together - Evidence-backed work ships; uncertainty is made visible rather than guessed away.
• One review pass - Decisions are batched to preserve the user's focus.
• Concrete choices - Review options describe directly applicable outcomes, not vague actions such as "adjust" or "rewrite."
• Evidence at the decision point - The user should not need to search the repository to understand a choice.
• No speculative residue - Source files do not receive placeholders, partial branches, or uncertainty TODOs.
• Idempotent continuation - A resumed run consumes only the new decision payload and does not redo completed work.

Read the longer design rationale, agent portability notes, platform integration guide, and progressive-loading design.

Validation and Limitations

Repository CI checks version consistency, Skill frontmatter, local references, the HTML review contract, plugin JSON, and English-document language separation.

Confidence remains a judgment informed by available evidence. The Skill reduces interruptions and makes uncertainty reviewable; it cannot supply missing business authority or guarantee that every repository invariant is documented. Important changes still require the target project's normal tests and review.

The bundled HTML template is self-contained and responsive. Agents must replace all placeholders through its structured JSON data block, apply the documented Unicode escaping, and validate task-specific evidence before presenting it.

Updating

Agent Skills:

npx skills add HuaTalk/best-effort-delivery-skill

Claude Code:

/plugin update best-effort-delivery@best-effort-delivery

See the changelog for release details.

Scope Boundaries

The Skill governs how an agent handles uncertainty during an authorized task. It does not grant permission to delete data, force-push, publish packages, contact people, alter production systems, or perform other actions that normally require explicit approval.

Low-confidence items must be representable as review decisions. A true deadlock is exceptional and should trigger finer decomposition before the agent reports it.

Contributing

Changes to behavior must preserve the two-tier contract, review artifact schema, and idempotent resume rules. Follow CONTRIBUTING.md, update both README language versions, and run:

npm test

License

MIT