write-adr

A template for writing an architecture decision record (ADR), a short document that explains an important software design choice for BrowserMesh.

In plain words
What is it for?
Use it to create numbered decision documents in the project’s docs/decisions/ folder when a change affects a public contract, runtime rule, dependency direction, or published tool interface.
Why use it?
It gives design-changing work a written rationale before coding starts, including the problem, the decision, its effects, and alternatives that were rejected.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/scrolldynasty/browsermesh/write-adr
Any agent
npx skills add scrollDynasty/BrowserMesh --skill write-adr
Clone the repo
git clone --depth 1 https://github.com/scrollDynasty/BrowserMesh

Made for: Claude Code, Codex.

Per session 60 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 643 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00060 $0.00643
Opus 5 $0.00030 $0.00321
Sonnet 5 $0.00012 $0.00129
Haiku 4.5 $0.00006 $0.00064

Measured yesterday against content hash 3be2c7308d9c, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

write-adr scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

.claude/skills/write-adr/SKILL.md · 61 lines

How it starts

The opening of the file, as written. The whole thing — 61 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Writing an ADR

ADR 0012 requires a controlled design before code for anything that changes a contract or an invariant. The ADR is that design, not a retrospective write-up.

Format

Follow ADR 0019 and 0020. They are the current form; the eighteen earlier files use two older layouts and are not the template. Do not retrofit them.

# ADR NNNN — Title in sentence case

Status: accepted

Date: YYYY-MM-DD

## Context

## Decision

## Consequences
  • Filename: docs/decisions/NNNN-kebab-case-title.md, NNNN zero-padded, next unused number.
  • Em dash after the number, not a colon.
  • Status: accepted lowercase — also proposed, superseded by ADR NNNN.
  • Sentence case in the title. No trailing period.

What each section carries

Context. The measured problem, not the wish. State numbers where numbers exist: byte sizes, test counts, timings, the version something was observed against. ADR 0020 opens with "tools/list was 134,839 bytes, 7.3× the official Playwright MCP server" — that is the standard. Name the constraint that rules options out; for BrowserMesh that is often a SPEC clause.

Decision. What is now true, in the present tense. Include what was rejected and why, especially the option a reader would otherwise propose. If a check lives in one layer rather than another, say which and why — ADR 0020 explains that an input-schema rejection names the offending field while a BrowserMeshError would surface as an uninformative INVALID_ARGUMENT.

Consequences. What this costs, what it forecloses, what now has to stay true. A consequence section that only lists benefits is unfinished.

Rules

  • One decision per ADR. A second decision is a second file.
  • An accepted ADR is not edited to reflect a later change of mind. Write a new ADR and set the old one to superseded by ADR NNNN.
  • The ADR outranks README.md and the docs site but is outranked by docs/SPEC.md and docs/architecture.md — see the source-of-truth order in CLAUDE.md. If the ADR contradicts the SPEC, one of them is wrong; resolve it before merging.
  • Update docs/architecture.md and any affected public tool description in the same change. Docs and implementation must not diverge silently.
  • docs/decisions/ is not in .prettierignore, so run npm run format before committing.

Read the full file on GitHub · 61 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. yesterday First seen · 61 lines · 60 tokens per session scan A 3be2c7308d9c

Subscribe to this mod's changes

write-adr is a skill published in the GitHub repository scrollDynasty/BrowserMesh (4 stars, last pushed yesterday), licensed Apache-2.0. It adds 60 tokens to every session and 643 once invoked, about $0.0003 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Related

Other skills, from other repositories

browser_harness

../../SKILL.md.

browser-use/browser-harness · 0 tokens

browser-harness

Always use browser-harness for any web interaction: automation, scraping, testing, or site/app work.

browser-use/browser-harness · 25 tokens

deep-reverse

Use only for explicit web or API protocol reverse engineering: endpoint discovery, request replay, signature/token/encryption analysis, JavaScript runtime tracing, browser-independent reproduction, or crawler implementation that must not depend on browser automation. Do not use for one-off visible-page extraction or…

KuiChi-x/reverseloom · 61 tokens

web-crawl

Get data from websites with the least necessary complexity. Use for quick lookups, visible-page extraction, search results, tables, pagination, detail-page traversal, downloadable files (Excel/CSV/PDF/ZIP), embedded page state, internal JSON/XHR APIs, bulk collection, reusable crawler generation, and delivery in any…

KuiChi-x/reverseloom · 108 tokens

eric-task-master

Install, connect, and use Eric Task Master for durable Playwright browser jobs with persistent or ephemeral Profiles, live fast-auto-human behavior control, task queues, progress health, semantic diagnostics, recovery, artifacts, and composable Task Packs.

npcworkspace-cmyk/eric-task-master · 52 tokens

opencli-usage

Use at the start of any OpenCLI session — this is the top-level map of what opencli can do, how to discover adapters, what flags and output formats are universal, and which specialized skill to load next. Point here when an agent asks "what can opencli do?" or "how do I find the right command?".

jackwener/OpenCLI · 74 tokens