How do I install the Cfn Doc Lint skill?

Run npx skillmds@latest add masharratt/cfn-doc-lint in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Cfn Doc Lint safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Cfn Doc Lint?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Cfn Doc Lint free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Cfn Doc Lint?

masharratt (@masharratt) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Cfn Doc Lint by masharratt — Agent Skill

Name: Cfn Doc Lint
Rating: 4.5 (4 reviews)
Author: masharratt

Cfn Doc Lint

Enforce the feature-status.md and state-machines.md doc contract: closed status vocabulary, required columns, per-entity state-machine shape, cell-length caps, TOC for large files, plural filename. Use after editing either doc, or run --check-all to audit every project. Catches the three failure modes that rotted the portfolio: changelog-in-status-doc, status-vocab drift, and duplicate state-machine entities.

masharratt Updated Sep 10, 2026

File contents

CFN Doc Lint

Purpose: the two commit-time docs (readme/feature-status.md, readme/state-machines.md) rotted across 28 projects for the same three reasons: changelog dumped where status belongs, status vocabulary drifting so no grep works, and duplicate state-machine entities contradicting each other. This skill enforces the contract in SCHEMA.md so docs stay machine-parseable and human-scannable.

The contract lives in SCHEMA.md (same dir). This skill is the enforcement; the schema is the spec.

Usage

# one doc (auto-detects type by filename)
.claude/skills/cfn-doc-lint/execute.sh <project>/readme/feature-status.md

# a project dir (lints both docs if present)
.claude/skills/cfn-doc-lint/execute.sh <project>

# every project
.claude/skills/cfn-doc-lint/execute.sh --check-all /home/masha/projects

Exit 0 = clean (warnings allowed). Exit 1 = one or more ERRORs.

What it checks

Structural (ERROR, fails the lint):

Filename. Must be exactly feature-status.md or state-machines.md (plural). Flags singular state-machine.md and domain-prefixed variants.
Last-Updated date stamp in the first 20 lines (Last Updated / Last Verified / Last Reviewed / verified against + an ISO date).
Status Legend in feature-status (explicit header, or a table defining the five tokens).
TOC in any state-machines file over 300 lines (anchor links in first 60 lines).
Duplicate entity in state-machines (same normalized H2 name twice). Catches the date-prepend-instead-of-edit failure mode.
Cell walls over 800 characters.

Quality (WARN, reports only):

Status tokens outside the enum (prod | beta | dev | stub | deprecated).
Verbose cells (280-800 chars).
State-machine entities missing States, Transitions, or Source grounding.
Many dated H2/H3 headers in feature-status (changelog smell).

Adding it to a workflow

Wire execute.sh as a PostToolUse hook scoped to the two filenames so a non-conforming doc fails at edit time. See the project .claude/settings.json hook section. Run --check-all in the commit skill or CI to audit the portfolio.

When NOT to use

This lints doc structure, not doc truth. It will not tell you a feature marked prod is actually broken, or that a state machine omits a real transition. For staleness against code, pair with cfn-detect-stale-docs.

---name: cfn-doc-lintdescription: Enforce the feature-status.md and state-machines.md doc contract: closed status vocabulary, required columns, per-entity state-machine shape, cell-length caps, TOC for large files, plural filename. Use after editing either doc, or run --check-all to audit every project. Catches the three failure modes that rotted the portfolio: changelog-in-status-doc, status-vocab drift, and duplicate state-machine entities.---# CFN Doc Lint**Purpose:** the two commit-time docs (`readme/feature-status.md`, `readme/state-machines.md`)rotted across 28 projects for the same three reasons: changelog dumped wherestatus belongs, status vocabulary drifting so no grep works, and duplicatestate-machine entities contradicting each other. This skill enforces the contractin `SCHEMA.md` so docs stay machine-parseable and human-scannable.The contract lives in `SCHEMA.md` (same dir). This skill is the enforcement;the schema is the spec.## Usage```bash# one doc (auto-detects type by filename).claude/skills/cfn-doc-lint/execute.sh <project>/readme/feature-status.md# a project dir (lints both docs if present).claude/skills/cfn-doc-lint/execute.sh <project># every project.claude/skills/cfn-doc-lint/execute.sh --check-all /home/masha/projects```Exit 0 = clean (warnings allowed). Exit 1 = one or more ERRORs.## What it checksStructural (ERROR, fails the lint):- **Filename.** Must be exactly `feature-status.md` or `state-machines.md` (plural). Flags singular `state-machine.md` and domain-prefixed variants.- **Last-Updated date stamp** in the first 20 lines (`Last Updated` / `Last Verified` / `Last Reviewed` / `verified against` + an ISO date).- **Status Legend** in feature-status (explicit header, or a table defining the five tokens).- **TOC** in any state-machines file over 300 lines (anchor links in first 60 lines).- **Duplicate entity** in state-machines (same normalized H2 name twice). Catches the date-prepend-instead-of-edit failure mode.- **Cell walls** over 800 characters.Quality (WARN, reports only):- Status tokens outside the enum (`prod | beta | dev | stub | deprecated`).- Verbose cells (280-800 chars).- State-machine entities missing States, Transitions, or Source grounding.- Many dated H2/H3 headers in feature-status (changelog smell).## Adding it to a workflowWire `execute.sh` as a PostToolUse hook scoped to the two filenames so anon-conforming doc fails at edit time. See the project `.claude/settings.json`hook section. Run `--check-all` in the commit skill or CI to audit the portfolio.## When NOT to useThis lints doc structure, not doc truth. It will not tell you a feature marked`prod` is actually broken, or that a state machine omits a real transition. Forstaleness against code, pair with `cfn-detect-stale-docs`.

Frequently asked questions