agentleFS
millhqmillhq/mill/.claude/skills/brief/SKILL.md

brief

Skill1 starsChanged 2 months agoApache-2.0View on GitHub

Compose a dispatch brief for a builder agent (goal 0192's context-completeness discipline). Use EVERY time an Agent dispatch is about to be written — before the prompt is drafted, not after. Loads the divergence list and the checklist that keeps a smaller model inside this project's patterns instead of the industry-familiar ones.

80 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use capture, strategy and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • toneron2Skill

    capture

    Capture thoughts to inbox with automatic classification

    Also in 6 projects that use this

  • EpistatesSkill

    strategy

    Plan weekly or monthly X content strategy. Use when the user wants to plan their content calendar, set growth goals, build a content pipeline, or think strategically about their X presence.

    Also in 4 projects that use this

  • aleksander-dytkoSkill

    decision

    Make a product decision with full context from the vault and available sources

    Also in 3 projects that use this

  • dirienSkill

    decide

    Three-agent adversarial debate protocol for strategic decisions. Two advocates steelman opposing positions while a moderator identifies risks and synthesizes a binding consensus. Use when choosing between alternatives, evaluating tradeoffs, or making high-stakes decisions.

    Also in 5 projects that use this

  • JaimeGBASkill

    ingest

    Digest an external source (article, paper, transcript, URL, book chapter) and integrate its content into the knowledge base

    Also in 7 projects that use this

  • howellsSkill

    reconcile

    Audit a project against current plugin conventions and offer to update structure.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 73 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read divergences.md in this folder.

    line 17
  2. Distinctive:

    Check each constraint you are about to state against the code, and against the other constraints (three briefs in one arc shipped …

    line 24
  3. Distinctive:

    Haiku explorer: read-only tasks only; state the question, the places to look, and the answer format.

    line 74

“Common” is measured: kept by at least 6 in 10 of the 73 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Writing a dispatch brief

The failure this skill exists to prevent (goal 0192, defect_class: familiar-pattern-fallback): with incomplete context, any reader — orchestrator included — falls back on the industry-familiar pattern, which is right often enough to fail silently at the boundaries. Brief completeness must RISE as the executing model tier drops; a Sonnet brief carries more, not less, than an Opus one would need.

Before drafting

  1. Read divergences.md in this folder. Copy into the brief every product-model/testing-harness divergence whose area the task touches — as written, not paraphrased. If the task exposes a divergence not yet on the list, ADD it to divergences.md in the same change. Skip § Operations: that block now lives in .claude/agents/builder.md's body (loaded only when the builder runs), not copied into the brief.
  2. Check each constraint you are about to state against the code, and against the other constraints (three briefs in one arc shipped impossibilities; one brief told an agent to update SPEC.md while forbidding it to touch the directory SPEC.md lives in).

The brief must contain

  • Divergence statements, not pointers. "The obvious answer here is X; this project does Y; because Z." Never bare "follow our rules" — a pointer is exactly what a familiar-pattern fallback reads past.
  • Enumerated choices wherever the agent must not invent: legal values listed, not described.
  • The design contract verbatim for anything user-facing (labels, copy, states, hierarchy) — agent discretion is implementation only.
  • Objective gates: what "done" is, as checkable predicates (commands to run, files that must exist, a PR number that must resolve via gh pr view <n> --json number,state).
  • Report shape: the exact fields the report must carry, including Review, so a stopped agent's last message is a deliverable, not a status. This is the one piece of the old operational block that still belongs in the brief, not the agent definition — it differs per brief.
  • Adoption comparison: quote the goal's record required by adopt-converged-patterns.md: chosen solution/version/highest-level API, full capability/upstream comparison, actual mismatch if rejected, and the remaining Mill adapter/domain boundary for implementation and verification. The chosen abstraction owns the relevant lifecycle without parallel homemade machinery. Unresolved fit → stop, research, no dispatch.
  • Model: Sonnet unless the brief carries a one-sentence Opus justification; never Fable; at most one Opus builder live.
  • Sized to ≤3 contract items. A fourth item is the next slice, not a fourth bullet in this one — a 4+ item brief is the size class that hit the turn cap with zero commits (goal 0414 S4); the three-item briefs landed in one run.

Dispatch shape

The dispatch itself is short: Agent({subagent_type: "builder", prompt: "brief: <path to the brief file>. goal: <path to the goal file>. <the one or two facts that differ this time — branch name, PR title, an amendment>."}). The worktree scope, poll-in-place rule, docs-repo handling, the never-list, the pre-PR reviewer dispatch and the own-the-PR-to-merge procedure all live in .claude/agents/builder.md already — never repeat them in the dispatch prompt or the brief body.

Tier calibration

  • Sonnet builder: everything above, in full. Assume no inference beyond the written word; ambiguity becomes the familiar pattern.
  • Haiku explorer: read-only tasks only; state the question, the places to look, and the answer format. No build steps.
  • Any tier: a design question surfacing mid-build gets REPORTED, never decided by the agent — say so explicitly.

After the dispatch closes

Record in the goal file (or the wave note) whether any brief constraint proved wrong, and which — 0192's acceptance is measured on this, not on the brief feeling thorough.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.