visual-standards

Visual formatting standards for repository documentation — emoji heading prefixes, horizontal rules, TOC anchors, callouts, screenshots (device dimensions, HTML patterns, captions, shadows), and image optimisation. Load when generating READMEs with visual elements or working with screenshots.

Best use case

visual-standards is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Visual formatting standards for repository documentation — emoji heading prefixes, horizontal rules, TOC anchors, callouts, screenshots (device dimensions, HTML patterns, captions, shadows), and image optimisation. Load when generating READMEs with visual elements or working with screenshots.

Teams using visual-standards should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

  • You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

  • You only need a quick one-off answer and do not need a reusable workflow.
  • You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/visual-standards/SKILL.md --create-dirs "https://raw.githubusercontent.com/littlebearapps/pitchdocs/main/.claude/skills/visual-standards/SKILL.md"

Manual Installation

  1. Download SKILL.md from GitHub
  2. Place it in .claude/skills/visual-standards/SKILL.md inside your project
  3. Restart your AI agent — it will auto-discover the skill

How visual-standards Compares

Feature / Agentvisual-standardsStandard Approach
Platform SupportNot specifiedLimited / Varies
Context Awareness High Baseline
Installation ComplexityUnknownN/A

Frequently Asked Questions

What does this skill do?

Visual formatting standards for repository documentation — emoji heading prefixes, horizontal rules, TOC anchors, callouts, screenshots (device dimensions, HTML patterns, captions, shadows), and image optimisation. Load when generating READMEs with visual elements or working with screenshots.

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# Visual Standards

## Emoji Heading Prefixes

Use a single emoji before each H2 heading to create visual anchors when scrolling.

**Pattern:** `## {emoji} Section Title`

**Recommended emoji by section type:**

| Section Type | Emoji | Example |
|-------------|-------|---------|
| Quick start / Getting started | ⚡ | `## ⚡ Quick start` |
| Why / Value proposition | 💡 | `## 💡 Why ProjectName?` |
| Features | 🎯 | `## 🎯 Features` |
| Commands / API / Usage | 🤖 | `## 🤖 Commands` |
| Configuration | ⚙️ | `## ⚙️ Configuration` |
| Requirements / Prerequisites | 📦 | `## 📦 Requirements` |
| Documentation links | 📚 | `## 📚 Documentation` |
| Contributing | 🤝 | `## 🤝 Contributing` |
| Licence / License | 📄 | `## 📄 Licence` |
| Security | 🔒 | `## 🔒 Security` |
| Integrations / Plugins | 🔌 | `## 🔌 Integrations` |
| How it compares | ⚖️ | `## ⚖️ How it compares` |
| Roadmap | 🗺️ | `## 🗺️ Roadmap` |
| What it does / Use cases | 🚀 | `## 🚀 What ProjectName Does` |

**Rules:**
- One emoji per heading — never two
- Use the same emoji consistently for the same section type across projects
- Skip emoji prefixes for READMEs under 5 sections

## Horizontal Rules as Section Separators

Use `---` between major H2 sections to create visual breathing room (especially in 200+ line READMEs).

**When to use:** After hero/badge section, after TOC, between H2 sections, before licence/footer.
**When to skip:** Between H3 subsections, in short documents (under 150 lines), in non-README files.

## Table of Contents with Emoji Anchors

GitHub and GitLab strip the emoji character but retain the leading hyphen. Bitbucket prefixes all heading anchors with `markdown-header-` — load the `platform-profiles` skill when targeting Bitbucket.

```markdown
- [Quick start](#-quick-start)
- [Why ProjectName?](#-why-projectname)
- [Features](#-features)
- [Configuration](#%EF%B8%8F-configuration)
```

Include a TOC for READMEs with 7+ sections.

## Bold Inline Callouts

For brief warnings, tips, and notes, use bold inline callouts rather than GitHub-specific `[!NOTE]` syntax (which breaks on npm and PyPI).

```markdown
**Note:** This only applies when running in production mode.
**Tip:** Pass `--verbose` to see detailed output.
**Warning:** Never commit this file — it contains credentials.
```

Reserve GitHub callout syntax for GitHub-only documents (issue templates, PR templates).

## Screenshots & Device Images

For device-specific capture dimensions, HTML display patterns, retina handling, annotation conventions, captions, shadows/borders, browser chrome, file naming, and optimisation guidance, load `SKILL-reference.md` from this skill directory.

Related Skills

pitchdocs

5
from littlebearapps/pitchdocs

Generate marketing-quality repository documentation from codebase analysis. Scans 10 signal categories, extracts features with file-level evidence, and produces README, CHANGELOG, ROADMAP, and 15+ more docs. Zero runtime dependencies. For AI context file management, see ContextDocs.

user-guides

5
from littlebearapps/pitchdocs

Generates task-oriented user guides and how-to documentation for a repository. Creates docs/guides/ with step-by-step instructions for common workflows, integrations, and advanced usage. Links guides into README.md and CONTRIBUTING.md. Use when a project needs user-facing how-to documentation beyond the README quickstart.

roadmap

5
from littlebearapps/pitchdocs

Generates ROADMAP.md from project milestones, issues, and boards (GitHub, GitLab, or Bitbucket). Structures content with mission statement, current milestone progress, upcoming milestones, and community involvement section. Use when creating or updating a project roadmap.

public-readme

5
from littlebearapps/pitchdocs

Generates READMEs with the Daytona/Banesullivan marketing framework — hero section, benefit-driven features, quickstart, comparison tables, and compelling CTAs. Produces docs that sell as well as they inform. Use when creating or overhauling a project README.

platform-profiles

5
from littlebearapps/pitchdocs

Platform-specific equivalents for GitLab and Bitbucket when generating repository documentation. Lookup tables for file paths, badges, Markdown rendering, CI/CD, and CLI tools. Load this skill when working on non-GitHub repos or generating cross-platform docs.

pitchdocs-suite

5
from littlebearapps/pitchdocs

One-command generation and audit of the full public repository documentation set — README, CHANGELOG, ROADMAP, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, issue templates, PR template, and discussion templates. Use when setting up a new repo or auditing an existing one.

package-registry

5
from littlebearapps/pitchdocs

Documentation guidance for projects published to npm and PyPI package registries. Covers metadata fields that affect registry pages, README cross-renderer compatibility, trusted publishing, provenance badges, and audit checks. Use when a project has package.json or pyproject.toml and is published publicly.

llms-txt

5
from littlebearapps/pitchdocs

Generates llms.txt and llms-full.txt files following the llmstxt.org specification. Provides LLM-friendly content curation for AI coding assistants (Cursor, Windsurf, Claude Code) and AI search engines. Use when generating or updating llms.txt for a repository.

launch-artifacts

5
from littlebearapps/pitchdocs

Transforms README and CHANGELOG into platform-specific launch content — Dev.to articles, Hacker News posts, Reddit posts, Twitter/X threads, and awesome list submission PRs. Keeps promotion tethered to code artifacts, not generic marketing. Use when launching or announcing a project release.

geo-optimisation

5
from littlebearapps/pitchdocs

Generative Engine Optimisation (GEO) patterns for documentation that surfaces correctly in AI-generated answers — citation capsules, crisp definitions, atomic sections, comparison tables, statistics, and semantic scaffolding. Load when optimising docs for AI citation (ChatGPT, Perplexity, Google AI Overviews, Claude).

feature-benefits

5
from littlebearapps/pitchdocs

Systematic codebase scanning for features and evidence-based feature-to-benefit translation. Extracts what a project does from its code and translates it into what users gain — generates features and benefits sections, "Why [Project]?" content, and feature audit reports. Use when writing a features table for a README, extracting features from code, auditing feature coverage, or answering "why should someone use this project?".

docs-verify

5
from littlebearapps/pitchdocs

Validates documentation quality and freshness — checks for broken links, stale content, llms.txt sync, image issues, heading hierarchy, and badge URLs. Runs locally or in CI. Use to catch documentation decay before it reaches users.