skills.rest
dxiiren
dxiirenCOMMUNITY
Explore all skills by this author →
GitHub

update-or-create-docs

Enforces style consistency and sibling index updates when creating or editing .docs/ documents.

Updated Aug 1, 2026
Search Tags:#git#documentation#markdown#consistency#style guide#docs automation#index sync
One-click install
npx skills add https://github.com/dxiiren/project-skeleton --skill update-or-create-docs-dxiiren
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: update-or-create-docs
Source: https://github.com/dxiiren/project-skeleton/tree/main/.claude/skills-optional/update-or-create-docs
Command: npx skills add https://github.com/dxiiren/project-skeleton --skill update-or-create-docs-dxiiren

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Documentation sets drift out of sync: new docs get added without updating the index, and style conventions diverge across files. This Skill enforces a hard rule that every .docs/ document change must be accompanied by updates to .docs/README.md and .docs/tldr.md, verified by a mechanical git-based sync checker. ## Core Features & Use Cases - Sibling Update Gate: Runs check-sibling-sync.py against git state (staged, unstaged, untracked) to verify that .docs/README.md and .docs/tldr.md changed alongside any other .docs/ document, exiting 1 if a sibling is missing. - Style Consistency Rules: Requires every doc to open with a TL;DR blockquote, end with a Related docs table, use tables over prose, and state mechanisms explicitly. - Structured Authoring Workflow: Guides reading a sibling doc first for style, then creating or updating content, then updating the index row and the 30-second tldr.md summary. - Use Case: After adding a new architecture doc under .docs/03-architecture/, the Skill ensures the README index row and tldr.md summary are written in the same pass and the sync script prints SYNC OK before reporting done. ## Quick Start Ask the assistant to write a new doc for the authentication flow in .docs/ and have it update the README index and tldr.md, then run the sibling sync check.

Frequently Asked Questions about update-or-create-docs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I keep a docs index in sync with new documentation files?▼

Update the index file in the same commit as the doc change and verify with a git-based checker. This Skill's check-sibling-sync.py reads staged, unstaged, and untracked changes under .docs/ and fails if README.md or tldr.md were not touched alongside any doc edit.

How to enforce documentation style consistency across a team?▼

Define explicit style rules such as a mandatory TL;DR blockquote, a Related docs table at the end, tables over prose, and no badges or emoji. Pair the rules with a mechanical gate script so compliance is verified by git state rather than memory.

Does check-sibling-sync.py require any Python packages?▼

No, the script uses only the Python standard library (argparse, subprocess, os, sys). It shells out to git commands like git diff and git ls-files, so git must be installed, but no pip dependencies are needed.

Why does the sibling sync check fail when I only edited one doc?▼

The check fails because editing any .docs/ document other than README.md or tldr.md requires both siblings to also appear in the git diff. Update the index row in .docs/README.md and the summary section in .docs/tldr.md, then rerun the script.

Can the sync checker run outside a git repository?▼

The script locates the repo root via git rev-parse and falls back to a path three levels above itself, but change detection relies entirely on git diff and git ls-files. Without git state it cannot detect changed docs, so it effectively requires a git repository.

Related Skills

Explore More Software Engineering Skills→
ShoebtamboliShoebtamboli
14

create-task-files

Convert planning lists into structured markdown task files with YAML frontmatter.

Community
Intermediate
kortix-aikortix-ai
20.2k

docs-sync

Rewrites documentation pages to match code changes and opens a daily drift PR.

Official
Advanced
bactopiabactopia
523

review-docs

Validate reference documentation against live repository state using bactopia-docs.

Official
Intermediate
beelabstudiobeelabstudio

documentation-writer

Creates and maintains technical documentation, API docs, README files, and user guides.

Official
Basic