@nerdev/skillset 0.2.1

package/skills/ai-agent/agent-docs-writer/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: agent-docs-writer
+description: "Use this skill to write, create, improve, or audit README.md and AGENTS.md for a code repository. Make the codebase legible to AI coding agents (Claude Code, Cursor, Codex, OpenCode, etc.) and to humans. Trigger on phrases like \"write an AGENTS.md\", \"make my repo agent-friendly\", \"onboarding doc for coding agents\", \"README for this project\", \"contributor guide\", \"docs so an AI agent does not break things\", or any request to document a codebase's context, conventions, glossary, or guardrails. Also use it to review or critique an existing README or AGENTS.md against this skill's checklist. Check that docs distinguish [planned] vs [shipped] reality and mark plan-drift with dated NOTE markers. Always use this instead of writing a generic README or AGENTS.md from scratch."
+---
+
+# Agent Docs Writer
+
+Writes a **README.md + AGENTS.md pair** for a repo. README answers
+"what is this and is it worth pulling in or reading further" for humans
+AND agents. AGENTS.md answers "how do I safely change this codebase"
+for a coding agent about to start work. They are two different
+documents with two different jobs. Never merge them into one file.
+
+This skill borrows the philosophy behind T3 Code's AGENTS.md (https://github.com/pingdotgg/t3code/blob/main/AGENTS.md). Be terse and glossary-first. Be opinionated about non-negotiables. Use concrete good/bad examples instead of abstract rules.
+
+## Workflow
+
+1. **Scan the repo** (do not just ask. Look first, then ask to fill gaps)
+2. **Interview** the user for the things scanning cannot tell you
+3. **Draft** README.md and AGENTS.md
+4. **Show the draft in chat** and get explicit confirmation before writing files
+5. **Write files** only after confirmation
+
+Never skip straight to writing files without showing a draft first. This is a hard requirement for this skill. It holds no matter how the user phrases the request.
+
+
+> **nerdev-docs integration:** This skill generates `AGENTS.md` for projects using the nerdev-co methodology. See [`nerdev-docs`](../nerdev-docs/SKILL.md) for the full documentation framework (ADRs, design docs, runbooks) that mandates AGENTS.md as a required document type.
+
+## Plan vs. Shipped-Reality rule (applies to every doc this skill writes or audits)
+
+Docs often come before the code they describe ("docs-as-spec"). That makes them a great thinking tool but a dangerous memory. Months later, re-reading a stale doc gives the author a **false memory of their own project**. In interviews or handoffs, describing architecture that does not exist reads as dishonest or confused.
+
+Therefore, whenever this skill writes or audits docs:
+
+1. **Distinguish "planned" from "shipped."** Every claim about architecture, features, or behavior must be one of:
+   - `[planned]`: vision/design intent, not yet built
+   - `[shipped]`: actually implemented and running
+   - When unsure, mark `[planned]` and ask the user. Never assume a doc describes reality.
+2. **Mark drift, do not rewrite history.** When a plan changed mid-build (feature dropped, tech swapped, scope cut), the doc keeps the original plan AND gets a drift marker at the top of the changed section:
+   `> NOTE (YYYY-MM-DD): superseded: actually shipped as X because <Y>`
+   The marker takes 30 seconds, and keeps the doc an honest archive of everything: the vision AND the reality.
+3. **Audit mode:** when reviewing existing docs, actively look for unmarked claims that do not match the code (in `package.json`, repo structure, tests, CI). Flag each one with the drift marker, do not silently "fix" it to match code. Include the question "did this actually ship?" for the user to answer.
+4. **Postmortem/case-study docs** (drafted during the build): end each milestone/postmortem with a "what actually changed" section dated at the time of writing. This keeps the final story true to what happened, not to the plan.
+
+
+## Step 1: Scan the repo
+
+Before asking the user anything, look for signal yourself:
+
+- `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` etc. → name, deps, scripts, language/framework, monorepo tooling (turborepo, nx, pnpm workspaces...)
+- Existing `README.md`, `CONTRIBUTING.md`, `AGENTS.md`, `CLAUDE.md`, `.cursorrules` → do not start from zero, extract and upgrade
+- Directory structure (`view` on repo root, 2 levels deep) → infer architecture (monorepo vs single app, apps/ + packages/, src/ layout, etc.)
+- Test setup, CI config (`.github/workflows/`), linter/formatter config → infer what "safe to change" looks like mechanically
+- Git remote / repo name → project identity
+
+Use `bash_tool` and `view` for this. Build a working picture before the interview. Then you ask fewer, sharper questions instead of generic ones the repo already answers.
+
+## Step 2: Interview
+
+Ask only what scanning could not answer. Use `ask_user_input_v0` where the answers are short or pick-one. Keep to the essentials below. Do not ask more than 3 to 4 questions at once.
+
+Essential things to nail down:
+
+1. **Glossary**. Does this project have terms that mean something specific/non-obvious here? (e.g. in T3 Code: "environment", "project", "thread", "turn" all have precise meanings that differ from casual usage). If yes, get a plain-language definition for each, one line, no jargon-on-jargon.
+2. **What makes this project special**. The thing a generic agent would get wrong by defaulting to "how everyone else does it." (e.g. "we don't use REST here, everything is RPC" or "this is a CLI-first tool, the web UI is secondary")
+3. **What to never compromise on**. The 2-5 hard invariants. Things like: never break backwards compat on X. Never touch generated files by hand. Always run migrations through Y. Security/auth code always needs a second look. This is the highest-value section. Push the user if they give you something vague like "write good code."
+4. **How and where it is working**. Deployment/runtime shape in one paragraph: where does this run, what is the boundary between packages, what talks to what.
+5. **Good/bad examples**. For at least the top 2-3 rules in AGENTS.md, get or infer one concrete "do this" / "not this" pair. Agents learn more from examples than from abstract prose. If the user cannot supply one, propose one based on the scanned code and confirm it.
+6. **A note from the author** (optional but recommended). One informal paragraph, in the user's own voice, that does not fit the structured sections. This is where personality and context live (e.g. "we've been burned by X before, that's why rule Y exists").
+
+If the user is clearly in a hurry or says "just draft something", infer sensible defaults from the repo scan. Mark inferred sections clearly as `[inferred, confirm or edit]` in the draft. Then move straight to drafting.
+
+## Step 3: Draft
+
+Use the templates in `templates/README.template.md` and `templates/AGENTS.template.md` as the structural skeleton. Read `references/principles.md` for the reasoning behind each section before filling them in. Do not skip it. It explains *why* each section exists so you do not flatten it into generic boilerplate.
+
+Show both drafts inline in the chat response (as markdown, not as files yet).
+
+**Drafting style (non-negotiable).** The reader knows English. Write for a 5th grader anyway.
+
+- Short and sweet. A sentence that works without words loses the words.
+- **No em dashes. Anywhere. Never.** Not in files, diffs, docs, comments,
+  or chat. Use commas or periods. One em dash means the deliverable fails
+  review.
+- Small paragraphs. Lists over prose.
+- `name: what it does` for every file, package, or feature:
+
+  ```
+  auth.ts: login, tokens, sessions.
+  ```
+
+- Abstract, not imported. No signatures, no import trees. Say what it does
+  and how it fits. A function name that adds nothing is left out.
+- Outcomes over details. What someone gets, or what breaks. Not how many
+  lines moved.
+- If a doc would survive unchanged in another project, it says nothing
+  about this one. Cut it.
+
+## Step 4: Confirm
+
+Ask explicitly: does this look right, anything to cut/add/reword? Iterate in chat. Do not write files until the user confirms.
+
+## Step 5: Write
+
+Once confirmed, write `README.md` and `AGENTS.md` to the repo root (or wherever the user's working directory is). Then present them.

package/skills/ai-agent/agent-docs-writer/references/principles.md

@@ -0,0 +1,73 @@
+# Why README and AGENTS.md are different documents
+
+**README.md** is a *decision* document, for humans and agents alike, at
+the "should I even engage with this" moment:
+- What this thing is, in one paragraph, no marketing fluff
+- Why it exists, and what problem it solves
+- Quick start: how to run it locally in the fewest steps possible
+- Where to look next (points at AGENTS.md for contributors and agents,
+  points at the docs site if one exists)
+
+README is *not* the place for detailed conventions, glossary, or "how
+to change things". That is AGENTS.md's job. A README bloated with
+contribution rules makes both documents worse. Humans skim past the
+parts they need. Agents burn context on things irrelevant to the
+"should I pull this in" decision.
+
+**AGENTS.md** is an *operating manual* for an agent (or human) about
+to make changes:
+- Assumes the reader already decided to work in this repo
+- Front-loads a glossary if the project has non-obvious terminology. An
+  agent that misreads a domain term will confidently make the wrong
+  change
+- States non-negotiables explicitly and early. Agents and new
+  contributors default to generic best practices unless told otherwise.
+  The whole value of this file is the *delta* from generic
+- Uses concrete good/bad examples over abstract rules. "Write clean
+  code" gives an agent nothing to pattern-match against. A paired
+  example does
+- Explains *where* things live and *how* the pieces talk to each other,
+  at the level needed to know which files are safe to touch for a given
+  kind of change
+- Can carry a personal, informal "note from the author" section. This
+  is where hard-won context lives that does not fit a structured
+  checklist (past incidents, non-obvious tradeoffs, "we tried X, don't")
+
+## Glossary discipline
+
+Only include a glossary if the project actually has overloaded or
+ambiguous terms. Forcing a glossary onto a project that does not need
+one is noise. Signal that a glossary is needed: one word carries
+different meanings inside this codebase than a newcomer would assume (T3
+Code's example: "project" vs "thread" vs "turn" vs "environment" each
+have precise, non-obvious meanings). Keep each definition to one plain
+sentence. A glossary written in jargon defeats its own purpose.
+
+## Non-negotiables discipline
+
+Push back (gently) if the user's answer to "what must never be
+compromised" is generic ("write good code", "follow best practices").
+Ask for the specific failure mode it prevents: what happened, or could
+happen, when someone breaks this rule? The best non-negotiables read like scar
+tissue, not aspirations. Aim for 2 to 5. More than that and nothing
+stands out as actually non-negotiable.
+
+## Good/bad examples discipline
+
+Every rule that is easy to violate by defaulting to "how you would
+normally do it" deserves a paired example. Show the wrong-by-default
+approach and the right one for this repo, with a one-line reason. This
+is the single highest-impact section for actually changing agent
+behavior. Agents are much better at pattern-matching against a concrete
+diff-shaped example than internalizing a prose rule.
+
+## Magic keyword / trigger note
+
+Some AGENTS.md files (and this skill itself) rely on being
+*discoverable*: a coding agent or a Claude Code session must be able to
+find and read this file without being told to. If the user's tooling
+supports it (Claude Code, Cursor, etc. increasingly auto-load
+AGENTS.md/CLAUDE.md from repo root), you need no special keyword. The
+filename convention itself is the trigger. Only add an explicit pointer
+(e.g. a line in README.md: "Read AGENTS.md before making changes") if
+the user's tooling does not auto-discover it.

package/skills/ai-agent/agent-docs-writer/templates/AGENTS.template.md

@@ -0,0 +1,44 @@
+# AGENTS.md
+
+Read this before making any changes to {project_name}. This file targets a coding agent, but applies equally to human contributors.
+
+<!-- Only include this section if the project has non-obvious/overloaded terminology. Skip it entirely otherwise. -->
+## Glossary
+
+- **{term}** means {one-sentence plain definition, scoped to this project}
+- **{term}** means {...}
+
+## What makes {project_name} special
+
+{The thing a generic agent would get wrong by defaulting to "how everyone else does it." 1-2 short paragraphs, not a list of features.}
+
+## What to never compromise on
+
+1. **{non-negotiable}**: {why: what breaks or what happened when someone violated this}
+2. **{non-negotiable}**: {why}
+3. **{non-negotiable}**: {why}
+
+## How and where it is working
+
+{One paragraph. State where this runs (browser, server, CLI, edge). State the major boundaries (packages, apps) and what talks to what. Give enough to know which files are in scope for a given kind of change. This is not a full architecture doc.}
+
+## Good vs. bad examples
+
+<!-- One pair per rule that is easy to get wrong by defaulting to generic practice. Keep to the 2-4 that matter most. -->
+
+### {rule name}
+
+Bad (generic default):
+```{lang}
+{example}
+```
+
+Good (how we do it here):
+```{lang}
+{example}
+```
+Why: {one line}
+
+## A note from the author
+
+{Optional. Informal, first person, the stuff that does not fit a checklist: past incidents, tradeoffs, "we tried X, don't."}

package/skills/ai-agent/agent-docs-writer/templates/README.template.md

@@ -0,0 +1,19 @@
+# {project_name}
+
+{one_paragraph_what_and_why: what this is and what problem it solves, no marketing fluff}
+
+## Quick start
+
+```
+{fewest possible commands to get it running locally}
+```
+
+## Structure
+
+{one short paragraph or bullet list: monorepo? apps/ + packages/? single app? what talks to what, at a glance}
+
+## Contributing / working in this repo
+
+See [AGENTS.md](./AGENTS.md) before making changes. It covers conventions, non-negotiables, and how the pieces fit together. This applies whether you are a human or a coding agent.
+
+{optional: links to docs site, issue tracker, discord, etc.}