agentsclimarketplace

Adr writer

Skill stark-ai-de/agent-skills/incubator/skills/repo-maintenance/adr-writer

Public Agent Skills for Codex operations, Cursor operations, Claude operations, repo maintenance, skill maintenance, productivity, and engineering workflows.

Install
npx -y skills add stark-ai-de/agent-skills --skill adr-writer

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Create short Architecture Decision Records under docs/adr. Use when the user makes a repo-level decision, changes skill format, publishing, validation, license, layout, or maintainer policy, and wants a concise ADR without documentation bloat.

The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

2.5 KB, as published. Nobody here has run it

ADR Writer

Goal

Create a short Architecture Decision Record that captures one repo-level decision without turning it into long-form documentation.

When to use

  • A decision changes repo structure, publishing, validation, license, layout, or skill standards.
  • A previous ADR is superseded, deprecated, or rejected.
  • The user asks to document a repo-level decision.

When not to use

  • Tiny copy edits, typo fixes, or minor template polish.
  • Routine skill additions that follow existing standards.
  • Temporary implementation details that do not affect future maintainers.

Inputs to inspect

  • docs/adr/README.md
  • docs/adr/TEMPLATE.md
  • Existing docs/adr/NNNN-*.md files
  • The decision context, current repo docs, and validation requirements

Workflow

  1. Identify the single decision sentence.
  2. Check docs/adr/README.md and the latest ADR number.
  3. Create the next docs/adr/NNNN-short-title.md.
  4. Use docs/adr/TEMPLATE.md or incubator/skills/repo-maintenance/adr-writer/assets/adr-template.md.
  5. Keep the ADR under 250 words, with a target of 120 to 180 words.
  6. Update the ADR index in docs/adr/README.md.
  7. Run ADR validation.

Safety rules

  • Do not write long ADRs.
  • Do not rewrite accepted ADRs; create a superseding ADR instead.
  • Do not document secrets, private internal details, customer data, or credentials.
  • Do not invent decision history. Mark uncertain decisions as Proposed.

References

Read only when needed:

  • assets/adr-template.md for the compact ADR template.

Scripts

Use only when the user wants a new ADR file created:

npm run adr:new -- "Use category-based skill folders"

Output format

Return:

  1. ADR path
  2. Decision sentence
  3. Word count
  4. Validation result
  5. Recommended next action

Completion criteria

  • The ADR records exactly one repo-level decision.
  • The ADR is under 250 words.
  • The ADR index is updated.
  • ADR validation passes.

Failure modes

  • If the decision is unclear, ask for the decision sentence before writing.
  • If the next ADR number cannot be determined, stop and report the conflicting files.
  • If validation fails, report the failing ADR rule and the file path.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.