# Standards Index

> Maintain the documentation index to prevent orphaned standards

- Skill: `sethdford/standards-index` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sethdford/standards-index`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sethdford/standards-index/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: sethdford (https://skillmd.com/u/sethdford)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sethdford/standards-index

---


# Standards Index Skill

Keep all standard documents indexed and discoverable by maintaining category README files.

## Context

Every standard document must appear in the appropriate category README, or it becomes "orphaned" — undiscovered and unused. This skill teaches you to scan, verify, and fix the standards index structure.

## Domain Context

Standards are organized in `docs/standards/` by category:

- `engineering/` — Code patterns, architecture, APIs
- `design/` — UI, styling, accessibility
- `quality/` — Testing, governance, documentation
- `operations/` — Deployment, monitoring, incidents
- `architecture/` — Module boundaries, package design

Each category has a `README.md` that indexes all documents in that category. The index is the discoverable interface to all standards.

Reference: `levels/L1-context/library/` structure

## Instructions

1. **Scan all category directories** — Find every `.md` file that is not named `README.md`

   ```bash
   find docs/standards -type f -name "*.md" ! -name "README.md" | sort
   ```

   - Deliverable: Complete list of all standard files

2. **Verify each file in the README** — Check that each `.md` appears in its category's `README.md`
   - For each file found in step 1, search for it in the corresponding `README.md`
   - Format to look for: `- [Title](./filename.md) — Description`
   - Deliverable: List of files that ARE indexed (matches) and files that are NOT (orphaned)

3. **Run check-doc-index.sh** — Use verification script to catch any misses

   ```bash
   ./levels/L2-ceremonies/scripts/check-doc-index.sh
   ```

   - This script identifies orphaned documents and invalid references
   - Deliverable: Script output showing status

4. **Fix orphaned documents** — For each orphaned file:
   - Option A: Add reference to the appropriate category README
   - Option B: Delete the file if it's not needed (discuss with team first)
   - Option C: Move the file to the correct category
   - Update the README with alphabetized entry: `- [Standard Name](./filename.md) — One sentence description`
   - Deliverable: All orphaned docs either indexed or removed

5. **Verify index coherence** — Check that category READMEs are well-formed
   - Each README has a brief intro explaining the category
   - All entries are alphabetized by title
   - All descriptions are 1-line, scannable, consistent in format
   - Deliverable: Coherent, well-organized category indexes

## Anti-Patterns

1. **Orphaned standards** — Documents that exist but are not indexed
   - Happens when: A standard is created but not added to README
   - Impact: Standard is never discovered or used
   - Guard: Before creating any `.md` file in `docs/standards/`, plan its README entry

2. **Stale index entries** — README links to files that no longer exist
   - Happens when: A file is deleted or moved, but the README is not updated
   - Impact: Broken references in agent context
   - Guard: When deleting or moving a standard, immediately update the README

3. **Inconsistent formatting** — README entries don't follow a pattern
   - Happens when: Multiple people edit READMEs without a template
   - Impact: Index is hard to scan and maintain
   - Guard: Use the template format consistently: `- [Title](./file.md) — Description`

## Further Reading

- `levels/L2-ceremonies/scripts/check-doc-index.sh` — Verification script
- `levels/L1-context/library/README.md` — Example of well-maintained index
- `AGENTS.md` — How agent files reference the standards index