markdown
Skill58 starsChanged 2 months agoMITView on GitHub
Repository guidance for writing, formatting, and validating Markdown documentation using markdownlint-cli, case-police, and markdown-link-check within the hr-skills monorepo.
18 other projects use a version of this.
Adopted by
Most recently taken up by
- p-chan/agent-skillstheir own version, first seen Nov 16, 2026
- p-chan/skillstheir own version, first seen Nov 16, 2026
- tahianahajanirina/claude-skillstheir own version, first seen Nov 15, 2026
- testdino-hq/google-styleguides-skillstheir own version, first seen Nov 8, 2026
- mattmireles/gemma-tuner-multimodaltheir own version, first seen Nov 1, 2026
- bsene/skillstheir own version, first seen Oct 25, 2026
Used with
Projects with it also use documentation.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
AnthropicSkilldocumentation
Write and maintain technical documentation. Trigger with "write docs for", "document this", "create a README", "write a runbook", "onboarding guide", or when the user needs help with any form of technical writing — API docs, architecture docs, or operational runbooks.
Also in 3 projects that use this
Other versions18 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 18
- mattmireles/gemma-tuner-multimodal★ 1.5ksame name
- DaveSkender/Stock.Indicators★ 1.3ksame name
- wado-lang/wado★ 120same name
- testdino-hq/google-styleguides-skills★ 15same name
- flowing-abyss/obsidian-vault-skills★ 9same name
- bsene/skills★ 7same name
- bmaltais/skills★ 2same name
- quatico-solutions/agent-skills★ 2same name
- Domush/ai-agent-web-development-skills★ 1same name
- instrument-org/skills★ 1same name
8 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- biomeSkill
- bunSkill
- changesetSkill
- clackSkill
- dry-refactoringSkill
- github-awesome-copilot-git-commitSkill
- hr-root-router-maintainingSkill
- hr-skills-maintainingSkill
- humanizerSkill
- jscpdSkill
- pdfSkill
- skill-vetterSkill
- turboSkill
- typescriptSkill
- valibotSkill
- hr-skillsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
22 rules. 0 are common, 19 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 12 edited versions we read keep these.
19
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 37
follow a logical heading hierarchy
- Distinctive: line 38
use fenced code blocks
- Distinctive: line 39
keep related content together
- Distinctive: line 41
prefer relative links within the repository
- Distinctive: line 49
All documentation and skill content follows Atlassian's content design guidelines:
- Distinctive: line 51
Use sentence case for all headings — capitalize the first word and proper nouns only
- Very specific: line 52
Don't use e.g., i.e., etc., or & in prose — write "for example", "that is", "and so on", "and"
- Distinctive: line 53
Don't use periods at the end of headings
- Distinctive: line 54
Avoid gerunds in headings — prefer "Add a skill" over "Adding a skill"
- Distinctive: line 56
Use "they/their" instead of gendered pronouns when the person's identity isn't known
- Distinctive: line 57
Avoid idioms or culturally specific expressions that don't translate well
- Very specific: line 62
Always leave a blank line between a heading or bold label and the list that follows it.
- Very specific: line 66
Run bun run validate (for SKILL.md files) and bun run lint:md (for everything else) before committing any Markdown change.
- Distinctive: line 199
Keep heading levels sequential.
- Distinctive: line 200
Prefer relative links within the repository.
- Distinctive: line 201
Use fenced code blocks consistently.
- Distinctive: line 202
Keep terminology consistent across documentation.
- Distinctive: line 203
Run Markdown validation before committing documentation changes.
- Distinctive: line 216
Keep each document focused on a single topic.
- Distinctive: line 217
Write Markdown that is easy to read in source form.
- Distinctive: line 218
Keep repository terminology consistent.
- Distinctive: line 220
Prefer relative links whenever possible.
“Common” is measured: kept by at least 6 in 10 of the 12 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Markdown
This skill describes how Markdown documentation is maintained throughout the hr-skills monorepo.
The repository standardizes on three complementary tools:
- markdownlint-cli for Markdown linting and formatting rules
- case-police for capitalization and terminology consistency
- markdown-link-check for validating repository links
Together these tools help keep documentation consistent, readable, and easy to maintain.
Supported tasks
- Explain Markdown conventions used by this repository
- Review Markdown structure and formatting
- Fix markdownlint-cli diagnostics
- Validate Markdown links
- Review heading hierarchy
- Check capitalization consistency
- Detect broken repository links
- Recommend repository-compliant Markdown
- Troubleshoot Markdown validation failures
Repository conventions
Repository documentation should:
- follow a logical heading hierarchy
- use fenced code blocks
- keep related content together
- use descriptive headings
- prefer relative links within the repository
- avoid duplicated documentation
- remain readable in both source and rendered form
Markdown quality is validated through formatting, capitalization, and link verification.
Content design rules
All documentation and skill content follows Atlassian's content design guidelines:
- Use sentence case for all headings — capitalize the first word and proper nouns only
- Don't use
e.g.,i.e.,etc., or&in prose — write "for example", "that is", "and so on", "and" - Don't use periods at the end of headings
- Avoid gerunds in headings — prefer "Add a skill" over "Adding a skill"
- Phrase list items in parallel: fragments get a lowercase first letter and no period, complete sentences get a capital first letter and a period
- Use "they/their" instead of gendered pronouns when the person's identity isn't known
- Avoid idioms or culturally specific expressions that don't translate well
- Be clear, concise, and direct; use contractions ("don't", "can't") for a conversational tone
Blank line before lists
Always leave a blank line between a heading or bold label and the list that follows it. Missing blank lines can break rendering, and the skill validator (bun run validate) enforces this rule for SKILL.md files specifically.
This applies to every Markdown file in the repository — AGENTS.md, README.md, SKILL.md, docs/*.md, and generated files. AI tools in particular must insert a blank line every time a heading (##, ###) or a bold label (**Label:**) is immediately followed by a list — this is easy to get wrong when generating Markdown programmatically.
Run bun run validate (for SKILL.md files) and bun run lint:md (for everything else) before committing any Markdown change.
Repository tooling
markdownlint-cli
Responsible for:
- Markdown syntax validation
- heading hierarchy
- document structure
- fenced code blocks
- list formatting
- repository Markdown conventions
The repository uses a shared markdownlint configuration together with
.markdownlintignore to ensure consistent documentation across all packages.
Repository configuration includes:
- maximum line length disabled
- duplicate headings allowed in different sections
- multiple H1 headings permitted
- blank lines around lists not enforced by markdownlint itself (
MD032: false) — see "Blank line before lists" below for the separate rule that does cover this - fenced code blocks required
- table column alignment not enforced
case-police
Responsible for:
- capitalization consistency
- repository terminology
- naming conventions
- heading capitalization
This helps keep documentation consistent across the entire repository.
markdown-link-check
Responsible for:
- validating relative links
- detecting broken repository references
- checking Markdown links
Repository configuration ignores:
- external URLs
- root-relative paths
- anchor links
- numeric references
Common commands
Validate Markdown documentation.
bun run lint:mdAutomatically apply supported fixes.
bun run lint:md:fixRun markdownlint-cli directly.
markdownlint .Run markdown-link-check directly.
markdown-link-checkRun case-police directly.
case-police .Key prompts
Markdown
- "Review this Markdown document."
- "Fix markdownlint-cli diagnostics."
- "Improve the document structure."
- "Review the heading hierarchy."
Documentation
- "Rewrite this document following repository conventions."
- "Recommend repository-compliant Markdown."
- "Detect duplicated content."
- "Improve readability."
Links
- "Validate repository links."
- "Detect broken references."
- "Review relative links."
- "Explain markdown-link-check diagnostics."
Terminology
- "Review capitalization consistency."
- "Fix case-police diagnostics."
- "Normalize repository terminology."
- "Review heading capitalization."
Examples
Validate repository documentation.
bun run lint:mdAutomatically apply supported fixes.
bun run lint:md:fixTips
- Write descriptive headings.
- Keep heading levels sequential.
- Prefer relative links within the repository.
- Use fenced code blocks consistently.
- Keep terminology consistent across documentation.
- Run Markdown validation before committing documentation changes.
Common issues
- Skipping heading levels.
- Broken relative links.
- Inconsistent capitalization.
- Mixed heading styles.
- Duplicated documentation.
- Invalid Markdown formatting.
Best practices
- Keep each document focused on a single topic.
- Write Markdown that is easy to read in source form.
- Keep repository terminology consistent.
- Validate documentation before every commit.
- Prefer relative links whenever possible.
- Separate documentation changes from functional code changes.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

