skills.rest
britt
brittCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

markdown-formatting

Applies consistent Markdown conventions and templates to PR descriptions, issues, and documentation.

5|Updated Nov 9, 2025
Search Tags:#documentation#writing#markdown#github#formatting#PR description#issue template
One-click install
npx skills add https://github.com/britt/agent-skills --skill markdown-formatting-britt
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: markdown-formatting
Source: https://github.com/britt/agent-skills/tree/main/skills/markdown-formatting
Command: npx skills add https://github.com/britt/agent-skills --skill markdown-formatting-britt

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Inconsistent Markdown formatting across PR descriptions, issue bodies, and documentation makes content hard to scan and unprofessional. This Skill enforces uniform conventions for headings, lists, code blocks, links, and emphasis so every structured artifact follows the same readable patterns. ## Core Features & Use Cases - Formatting Rules: Enforces heading hierarchy (no skipped levels), - list markers, language-tagged code blocks, descriptive link text, and disciplined bold/italic usage. - Ready-Made Templates: Provides fill-in templates for PR descriptions (Summary, Changes, Test Plan) and issue bodies (Problem, Steps to Reproduce, Expected, Actual). - Anti-Pattern Detection: Flags walls of text, mixed list markers, code blocks without language identifiers, and headings misused as emphasis. - Use Case: When drafting a GitHub PR description, the Skill structures it with a one-line summary, a bulleted change list, and a checkbox test plan referencing related issues like #87. ## Quick Start Ask the AI to format your PR description or issue body using the markdown-formatting conventions and templates.

Frequently Asked Questions about markdown-formatting

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

FAQPage Schema
How do I write a good GitHub PR description?▼

Structure the PR description with a one-line Summary, a bulleted Changes list, and a checkbox Test Plan. Use `##` headings, `-` list markers, backticks for code identifiers, and reference related issues with the `#123` format.

How to format a GitHub issue body with steps to reproduce?▼

Use the issue template with four sections: Problem, Steps to Reproduce as a numbered list, Expected behavior, and Actual behavior. This structure gives maintainers the context needed to triage and debug quickly.

What Markdown conventions should documentation follow?▼

Reserve `#` for the document title, use `##` for main sections without skipping levels, prefer `-` for unordered lists, and always specify a language identifier on fenced code blocks like ```typescript or ```bash.

When should Markdown templates not be used?▼

Skip templates and strict formatting rules for conversational chat replies, since normal responses do not need structured sections. Apply the conventions only to artifacts that will be saved or published, such as PRs, issues, and reports.

Why do code blocks need a language identifier?▼

A language identifier enables syntax highlighting when the Markdown is rendered on platforms like GitHub, making code easier to read. Blocks without a language render as plain monochrome text.

Related Skills

Explore More Software Engineering Skills→
dropseeddropseed
1.0k

plain-bug

Collect bug details and create a GitHub issue via gh CLI.

Official
Intermediate
pjcjpjcj
7

create-pr

Create GitHub pull requests with ticket references and Markdown descriptions.

Community
Intermediate
konflux-cikonflux-ci
1

fix-review

Interpret review feedback, plan minimal code fixes, and verify with tests and linting.

Official
Advanced
sathishssj3sathishssj3
2

pr-template-builder

Creates GitHub pull request, issue, and discussion templates with YAML configuration.

Community
Intermediate