repository-docs
Write and sync README, AGENTS.md, and repo docs with verified behavior.
Install
npx skills add https://github.com/fmind/dot/tree/main/skills/repository-docs
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install fmind-dot@llmmart
git clone https://github.com/fmind/dot.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole fmind/dot collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Repository Documentation
Keep human and agent docs aligned with live code, with one canonical owner per claim.
Workflow
- Inventory: find
README.md, root/nestedAGENTS.md,docs/,.github/*.md, generated help, and.agents/skills/*/SKILL.md(plus any repo skill catalog). - Verify against code: check entry points, source, tests, manifests,
misetasks, hooks, CI, and--helpfor every path, flag, version, and example. - Route by audience: README guidance and README assets for human identity, visuals, badges, and quickstart; AGENTS guidance for agent commands, invariants, and layout; skills for reusable workflows (link instead of copying).
- Gate: run repo doc checks,
dot agent context --checkafter instruction/skill edits,lychee --include-fragments=full <files>(checks anchors +#:~:text=; add--include-verbatimwhen code-block URLs carry claims),dprint check, and any site build; inspect rendered layout changes. - Report: changed files, verification evidence, and unverified external claims.
Gotchas
- Regenerate, never hand-edit generated docs; report local checks, CI, deploy, and publication statuses separately.
- Portable Markdown defaults:
1.ordered lists, language-tagged fences, one-line paragraphs, relative or~-relative paths in skills/AGENTS.md, and official docs URL comments atop comment-capable configs (below any schema directive). Preserve public anchors and exclude secrets or session state. - Guard
$tokens and backticks:dprint-plugin-markdownparses two bare$characters on one line (such as$VARor brand$tokens outside code spans) as inline$...$LaTeX math and mangles adjacent backticks and spaces; wrap$tokens in inline code or split lines, and check instruction docs for escaped, unmatched, or adjacent backticks.
Documentation
- GitHub README guidance · AGENTS.md · Agent Skills
- Companions: agent-project, skillify, dprint, diagrams-as-code.
Files (dot)
-
references
-
agents.md 1.7 KB
Loading… -
readme-assets.md 1.5 KB
Loading… -
readme.md 2.1 KB
Loading…
-
-
templates
-
README.md 3.2 KB
Loading…
-
-
SKILL.md 2.6 KB
--- name: repository-docs description: "Write and sync README, AGENTS.md, and repo docs with verified behavior." license: MIT metadata: kind: task author: Médéric HURIER (Fmind) source: github.com/fmind/dot/tree/main/skills/repository-docs created: "2026-09-07" updated: "2026-11-11" --- # Repository Documentation Keep human and agent docs aligned with live code, with one canonical owner per claim. ## Workflow 1. **Inventory**: find `README.md`, root/nested `AGENTS.md`, `docs/`, `.github/*.md`, generated help, and `.agents/skills/*/SKILL.md` (plus any repo skill catalog). 1. **Verify against code**: check entry points, source, tests, manifests, `mise` tasks, hooks, CI, and `--help` for every path, flag, version, and example. 1. **Route by audience**: [README guidance](references/readme.md) and [README assets](references/readme-assets.md) for human identity, visuals, badges, and quickstart; [AGENTS guidance](references/agents.md) for agent commands, invariants, and layout; skills for reusable workflows (link instead of copying). 1. **Gate**: run repo doc checks, `dot agent context --check` after instruction/skill edits, `lychee --include-fragments=full <files>` (checks anchors + `#:~:text=`; add `--include-verbatim` when code-block URLs carry claims), `dprint check`, and any site build; inspect rendered layout changes. 1. **Report**: changed files, verification evidence, and unverified external claims. ## Gotchas - **Regenerate, never hand-edit** generated docs; report local checks, CI, deploy, and publication statuses separately. - **Portable Markdown defaults**: `1.` ordered lists, language-tagged fences, one-line paragraphs, relative or `~`-relative paths in skills/`AGENTS.md`, and official docs URL comments atop comment-capable configs (below any schema directive). Preserve public anchors and exclude secrets or session state. - **Guard `$` tokens and backticks**: `dprint-plugin-markdown` parses two bare `$` characters on one line (such as `$VAR` or brand `$` tokens outside code spans) as inline `$...$` LaTeX math and mangles adjacent backticks and spaces; wrap `$` tokens in inline code or split lines, and check instruction docs for escaped, unmatched, or adjacent backticks. ## Documentation - [GitHub README guidance](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) · [AGENTS.md](https://agents.md) · [Agent Skills](https://agentskills.io/specification) - Companions: [agent-project](../agent-project/SKILL.md), [skillify](../skillify/SKILL.md), [dprint](../mise/references/dprint.md), [diagrams-as-code](../diagrams-as-code/SKILL.md).
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.