Claude Skill

repository-docs

Write and sync README, AGENTS.md, and repo docs with verified behavior.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download fmind-dot-skills_repository-docs-3bbe830.zip · 6 KB

Install

skills CLI npx skills add https://github.com/fmind/dot/tree/main/skills/repository-docs
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install fmind-dot@llmmart
Git 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

  1. Inventory: find README.md, root/nested AGENTS.md, docs/, .github/*.md, generated help, and .agents/skills/*/SKILL.md (plus any repo skill catalog).
  2. Verify against code: check entry points, source, tests, manifests, mise tasks, hooks, CI, and --help for every path, flag, version, and example.
  3. 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).
  4. 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.
  5. 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

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.

No comments yet.

Reviews (0)

No reviews yet.