create-docs-list-script-and-refactor-docs

Add an agent-friendly docs workflow to a repo, in a way that works across:

• Ruby on Rails repos (via a rake task)
• JS/TS repos (via npm/yarn/pnpm/bun scripts)
• other setups (the same concept; different runner)

Important: the code snippets in this skill are examples, not drop-in guarantees. You must implement the approach in a way that fits the repo, then run it, debug it, and iterate until it works in that specific codebase.

Goal

Create a single, easy-to-run "docs inventory" command that:

• lists all markdown docs (typically in docs/, including nested directories)
• validates each doc's YAML frontmatter (at minimum: frontmatter exists and summary is present + non-empty)
• prints read_when hints when present, so agents can quickly decide what to read next
• reminds contributors/agents to read relevant docs before changing code

Where docs live