Przejdź do treści
Biblioteka skilli
Programowanie · Automatyzacja

adr-tools

/adr-tools

Tworzy i zarządza rekordami decyzji architektonicznych za pomocą CLI adr-tools Nat Pryce'a: dodawanie, zastępowanie i łączenie ADR oraz generowanie spisu treści.

Licencja
MIT
Ostatnia zmiana repozytorium
14.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
3
Przestarzałość

Brak sygnałów. Repozytorium zmienione 14.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Tworzy i zarządza rekordami decyzji architektonicznych za pomocą CLI adr-tools Nat Pryce'a: dodawanie, zastępowanie i łączenie ADR oraz generowanie spisu treści.

Wyzwalacze z opisu

add an ADRrecord this decisioncreate an ADRsupersede ADR Nlink ADRsgenerate the ADR table of contents
Oryginalny opis (EN)

Create and manage Architecture Decision Records using the npryce adr-tools CLI. Use when the user asks to "add an ADR", "record this decision", "create an ADR", "supersede ADR N", "link ADRs", "generate the ADR table of contents", or any request involving the `adr` command. Pairs with the adr-author agent — this skill is the mechanics (commands, files, links); adr-author is the decision framework (when an ADR is warranted) and the prose authoring.

Jak działa

  1. Pre-flight
  2. Editor caveat — the most common failure
  3. Workflows
  4. Anti-patterns to refuse
  5. When to defer to adr-author
  6. Documentation style
Sekcje z nagłówków SKILL.md, w oryginale · 121 linii, 863 słów
Podgląd SKILL.md
---
name: adr-tools
description: Create and manage Architecture Decision Records using the npryce adr-tools CLI. Use when the user asks to "add an ADR", "record this decision", "create an ADR", "supersede ADR N", "link ADRs", "generate the ADR table of contents", or any request involving the `adr` command. Pairs with the adr-author agent — this skill is the mechanics (commands, files, links); adr-author is the decision framework (when an ADR is warranted) and the prose authoring.
role: worker
user-invocable: true
---

# ADR Tools

Mechanics for working with [npryce/adr-tools](https://github.com/npryce/adr-tools) — the `adr` CLI that creates numbered Architecture Decision Records. Pairs with the [`adr-author`](../../agents/adr-author.md) agent: that agent decides *whether* an ADR is warranted and writes the prose; this skill drives the CLI correctly.

## Pre-flight

```bash
command -v adr || echo "adr-tools not installed — see https://github.com/npryce/adr-tools"
cat .adr-dir 2>/dev/null   # project's configured ADR directory
ls "$(cat .adr-dir 2>/dev/null || echo docs/adr)/" 2>/dev/null | head -3
```

If the pre-flight reports `adr` missing, run `/project-init` to set up this repo's tooling — it installs the `adr` CLI as a capability tool (see its `${CLAUDE_PLUGIN_ROOT}/skills/project-init/references/capability-tools.md`) — or install it directly: see [npryce/adr-tools](https://github.com/npryce/adr-tools) (the CLI link is the fallback).

Project convention is `docs/adr/`. `adr-tools` stores the directory in `.adr-dir` at the project root — `adr` reads that file to find the ADRs no matter what subdirectory you're in. If `.adr-dir` is missing, run `adr init docs/adr` once. Do not init silently into a different path — confirm with the user if existing ADRs live somewhere unexpected.

## Editor caveat — the most common failure

`adr new` opens `$VISUAL` or `$EDITOR` (defaulting to `vi`). In a Claude Code shell this hangs the command and exits non-zero — the file is created but empty. Two workarounds:

1. **Preferred — bypass the editor.** Run with a no-op editor, then write the body with the Write tool:

   ```bash
   EDITOR=true VISUAL=true adr new "<title>"
   ```

   The command prints the new file path to stdout. Read it, then replace the template Context/Decision/Consequences sections with the real content via Edit or Write.

2. **Fallback — let it fail, then fill in.** `adr new "<title>"` will create the templated file and exit non-zero from the editor failure. Read the new file (it lives at `<adr-dir>/NNNN-<slugified-title>.md` — typically `docs/adr/`) and fill it in.

The skill always prefers workaround 1.

## Workflows

### Create a new ADR

```bash
EDITOR=true VISUAL=true adr new "<title in plain words>"
```

Then Edit the generated file to fill in:

- **Status** — `Accepted` (default) is fine for decisions already made. Use `Proposed` only if there is genuine open debate.
- **Context** — what forces drove this decision (constraints, alternatives considered, prior art)
- **Decision** — what we are doing (active voice, present tense: "Adopt X" not "We will adopt X")
- **Consequences** — easier / harder / risks. Be specific. If you cannot name a concrete trade-off, the decision probably did not need an ADR.

Commit the new ADR in the same commit (or PR) as the implementation it justifies.

### Supersede an earlier ADR

```bash
EDITOR=true VISUAL=true adr new -s <N> "<new title>"
```

`adr-tools` automatically:

- Inserts a "Supersedes [ADR N](N-old-title.md)" link in the new ADR's Status section.
- Edits ADR N's Status to "Superseded by [ADR M](M-new-title.md)".

Do not delete the old ADR. Its history is the point.

### Link two ADRs without superseding

```bash
adr link <SOURCE> "<LINK>" <TARGET> "<REVERSE-LINK>"
```

Example: `adr link 12 "Amends" 10 "Amended by"`. Use this for relationships like Amends/Refines/Constrains. Multiple links are normal.

### List all ADRs

```bash
adr list
```

Returns sorted file paths. Pipe through `xargs head -1` for a quick title scan.

### Generate the table of contents

```bash
adr generate toc > docs/adr/README.md
```

Run this after creating or superseding any ADR, then commit the regenerated TOC alongside the ADR change. Without this, the index drifts.

### Generate the dependency graph

```bash
adr generate graph | dot -Tpng > docs/adr/graph.png
```

Optional but useful when supersede/link chains get deep. Requires Graphviz (`dot`).

## Anti-patterns to refuse

- **Don't renumber ADRs.** `adr-tools` assigns sequential numbers; references in commits, PRs, and other ADRs depend on them being stable. If a number is wrong, supersede; never renumber.
- **Don't edit ADR status with a text editor when superseding.** Use `adr new -s <N>` so the bidirectional link is automatic and consistent.
- **Don't squash multiple decisions into one ADR.** One decision per file. If a "Decision" section has multiple bullets that are not facets of the same choice, split.
- **Don't write Decision in future tense.** "We will adopt X" reads as a proposal; "Adopt X" reads as a decision. Use the latter for `Accepted` status.
- **Don't omit Consequences.** An ADR without trade-offs is a note, not a decision record. If there genuinely are no consequences, the decision did not need an ADR — defer to the [`adr-author`](../../agents/adr-author.md) decision framework.

## When to defer to adr-author

This skill handles the CLI mechanics. Use the [`adr-author`](../../agents/adr-author.md) agent when:

- It is unclear whether the change *warrants* an ADR (see its decision framework).
- The decision has policy or architectural implications and you want prose with the right scope.
- You need to maintain the ADR index README beyond what `adr generate toc` produces.

A typical flow: the user asks "should we ADR this?" → adr-author decides yes/no and drafts the body → this skill runs the `adr new` / `adr link` commands and regenerates the TOC.

## Documentation style

Prose you write follows [`${CLAUDE_PLUGIN_ROOT}/knowledge/documentation-style.md`](${CLAUDE_PLUGIN_ROOT}/knowledge/documentation-style.md) (Whole-file load: short):

- Follow the Google Developer Documentation Style Guide.
- Use ASD-STE100-derived precision rules.
- Apply Zinsser's four principles: clarity, simplicity, brevity, and humanity.

Wersje

W bazie nie ma innych skilli o nazwie adr-tools.

Migawka bazy z 13.11.2026 · wersja paczki 9543ae49a6a6 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 84adr
    Tworzy i prowadzi rekordy decyzji architektonicznych, czyli ADR, gdy trzeba zapisać decyzję lub przygotować obsługę ADR w projekcie.
  • 100adr
    Tworzy, przegląda i zarządza rekordami decyzji architektonicznych (ADR): automatyczna numeracja, wykrywanie szablonu, kontrola jakości i utrzymanie indeksu.
  • 100architecture
    Zarządza rekordami decyzji architektonicznych (ADR) i diagramami C4.
  • 100adr
    Zapisuje, wyszukuje i uwzględnia rekordy decyzji architektonicznych przez CLI adr przed zmianą architektury lub interfejsu.
  • 100adr-ops
    Pisze, indeksuje i lintuje ADR jako dopisywaną pamięć odzyskującą powód kształtu systemu: szablon, kolejny numer, zastępowanie decyzji.
  • 100adr-compliance
    Pomaga audytować zgodność kodu z zaakceptowanymi rekordami decyzji architektonicznych (ADR): sprawdzanie kodu względem ADR, wykrywanie naruszeń i egzekwowanie decyzji.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.