What is write-readme?

A guide for writing a project's README, the main document that explains what the project does and how to install and use it.

Use it when creating or updating a README for a software project, including its quick-start instructions and agent-related guidance.

It gives the README a consistent structure and keeps installation instructions, examples, badges, and links organised.

write-readme — Skill by urmzd

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/urmzd/dotfiles/write-readme

Any agent

npx skills add urmzd/dotfiles --skill write-readme

Clone the repo

git clone --depth 1 https://github.com/urmzd/dotfiles

Made for: Claude Code, Codex.

Per session 104 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.

When invoked 2,716 The whole file, excluding the scripts and references it only reads on demand.

Security scan C 2 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.

Model	Per session	Once invoked
Fable 5	$0.00104	$0.02716
Opus 5	$0.00052	$0.01358
Sonnet 5	$0.00021	$0.00543
Haiku 4.5	$0.00010	$0.00272

Measured 2d ago against content hash 7e1b57fb9428, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade C, and why

write-readme scanned grade C with 2 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 2d ago.

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.

Downloads and executes remote codehighSupply chain

curl | sh runs whatever the server returns today, which is not necessarily what it returned when this was reviewed.

Include Prerequisites when: Neovim plugin needs a specific Neovim version, a library needs a specific compiler, a web app needs a node/pnpm version, a CLI needs an external binary to function. Skip it when a plain `cargo

Makes network callslowCapability

Not a fault in itself. Listed so you know the mod talks to something, and to what.

Include Prerequisites when: Neovim plugin needs a specific Neovim version, a library needs a specific compiler, a web app needs a node/pnpm version, a CLI needs an external binary to function. Skip it when a plain `cargo

dot_agents/skills/write-readme/SKILL.md · 335 lines

How it starts

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

README Standards

Centered Header Template

Every README starts with a centered header block:

<p align="center">
  <h1 align="center">{Display Name}</h1>
  <p align="center">
    {One-line description}
    <br /><br />
    <a href="...releases">Download</a>
    &middot;
    <a href="...issues">Report Bug</a>
    &middot;
    <a href="{url}">{Third Link}</a>
  </p>
</p>

Link 1: "Install" for libraries (Go go get, Python uv add), "Download" for binaries
Link 2: "Report Bug" (always links to /issues)
Link 3: contextual Go Docs, GitHub Action, PyPI, Crates.io, Experiments, etc.

Badges

Centered, immediately below header. Use exactly the set that applies; no more, no less. Maximum four badges.

Badge	When	Template
CI	always	`![CI](https://github.com/{owner}/{repo}/actions/workflows/ci.yml/badge.svg)`
License	always	`![License](https://img.shields.io/github/license/{owner}/{repo})`
Registry	published libraries only	crates.io / npm / PyPI / pkg.go.dev shield
Release	projects with downloadable binaries	`![Release](https://img.shields.io/github/v/release/{owner}/{repo})`

Personal sites, curricula, and archives ship with CI + License only. Do not add badges that link to empty or placeholder resources.

<p align="center">
  <a href="...ci.yml"><img src="...badge.svg" alt="CI"></a>
  &nbsp;
  <a href="LICENSE"><img src="...license.svg" alt="License"></a>
</p>

Demo Image

Position: immediately after badges, before any ## section. One hero image per README.

Source: showcase/ directory, always. Never assets/, doc/, or a repo-root image. The showcase/ name is pinned by style-brand.

Format: .gif for terminal recordings (teasr), .png for static screenshots, .svg only for vector diagrams.

Width: 80%.

<p align="center">
  <img src="showcase/demo.gif" alt="Demo" width="80%">
</p>

Projects without a visual output (libraries with no CLI, curricula, archives) skip the demo. Do not synthesize a demo for a project that has nothing to show.

Read the full file on GitHub · 335 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.

2d ago First seen · 335 lines · 104 tokens per session scan C 7e1b57fb9428

Subscribe to this mod's changes

write-readme is a skill published in the GitHub repository urmzd/dotfiles (3 stars, last pushed 20d ago), licensed Apache-2.0. It adds 104 tokens to every session and 2,716 once invoked, about $0.0005 per session on Opus 5. A static security scan graded it C with 2 findings (downloads and executes remote code, makes network calls). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Documents Writing and docs chezmoi dotfiles neovim nvim tmux zsh

benchling-integration

Benchling Python SDK and REST API integration for registry entities, inventory, ELN entries, workflows, Benchling Apps, and Data Warehouse queries. Use when automating lab data with benchling-sdk or the v2 API.

magic3007/dotfiles · 50 tokens

astropy

Core Python library for astronomy and astrophysics workflows that need Astropy APIs, including units/quantities, coordinates, FITS I/O, tables, time systems, WCS, and cosmology. Use when implementing or debugging astronomical data analysis code with Astropy.

magic3007/dotfiles · 56 tokens

esm

Comprehensive toolkit for EvolutionaryScale protein language models including ESM3 (generative multimodal design across sequence, structure, and function) and ESM C (efficient embeddings). Use for protein sequence/structure/function tasks, inverse folding, embeddings, variant design, and ESMFold2 structure prediction…

magic3007/dotfiles · 96 tokens

create-pr

Rebase from the latest origin/main, squash the commits from it, and then create a PR on github with intelligent commit messages based on staged changes.

magic3007/dotfiles · 34 tokens

mcp-notion-usage-guide

MCP Notion工具使用指南，包含常见问题解决方案和最佳实践。使用当： (1) 访问Notion数据库view URL出现"URL type view not currently supported"错误， (2) 需要获取数据库schema和表结构信息， (3) 查询数据库中的条目内容， (4) 创建页面时MULTISELECT字段值不存在导致失败， (5) 需要更新数据库schema添加新选项， (6) 开发需要集成Notion数据的自动化工作流， (7) querydatasources/query-database-view返回Business Plan要求错误， (8) 需要在无Business…

magic3007/dotfiles · 152 tokens

scan-commit

Automatically scan the repository for unstaged/untracked changes, group them into logical commits using hunk-level analysis, stage and commit them following Conventional Commits.

magic3007/dotfiles · 35 tokens

write-readme