agentleFS
tuanductrantuanductran/hr-skills/.agents/skills/markdown/SKILL.md

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

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.
  • AnthropicSkill

    documentation

    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

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
  1. Distinctive:

    follow a logical heading hierarchy

    line 37
  2. Distinctive:

    use fenced code blocks

    line 38
  3. Distinctive:

    keep related content together

    line 39
  4. Distinctive:

    prefer relative links within the repository

    line 41
  5. Distinctive:

    All documentation and skill content follows Atlassian's content design guidelines:

    line 49
  6. Distinctive:

    Use sentence case for all headings — capitalize the first word and proper nouns only

    line 51
  7. Very specific:

    Don't use e.g., i.e., etc., or & in prose — write "for example", "that is", "and so on", "and"

    line 52
  8. Distinctive:

    Don't use periods at the end of headings

    line 53
  9. Distinctive:

    Avoid gerunds in headings — prefer "Add a skill" over "Adding a skill"

    line 54
  10. Distinctive:

    Use "they/their" instead of gendered pronouns when the person's identity isn't known

    line 56
  11. Distinctive:

    Avoid idioms or culturally specific expressions that don't translate well

    line 57
  12. Very specific:

    Always leave a blank line between a heading or bold label and the list that follows it.

    line 62
  13. Very specific:

    Run bun run validate (for SKILL.md files) and bun run lint:md (for everything else) before committing any Markdown change.

    line 66
  14. Distinctive:

    Keep heading levels sequential.

    line 199
  15. Distinctive:

    Prefer relative links within the repository.

    line 200
  16. Distinctive:

    Use fenced code blocks consistently.

    line 201
  17. Distinctive:

    Keep terminology consistent across documentation.

    line 202
  18. Distinctive:

    Run Markdown validation before committing documentation changes.

    line 203
  19. Distinctive:

    Keep each document focused on a single topic.

    line 216
  20. Distinctive:

    Write Markdown that is easy to read in source form.

    line 217
  21. Distinctive:

    Keep repository terminology consistent.

    line 218
  22. Distinctive:

    Prefer relative links whenever possible.

    line 220

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:md

Automatically apply supported fixes.

bun run lint:md:fix

Run markdownlint-cli directly.

markdownlint .

Run markdown-link-check directly.

markdown-link-check

Run 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:md

Automatically apply supported fixes.

bun run lint:md:fix

Tips

  • 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.