readme-formatting（README formatting ORM）

README Formatting (Constructive Standard)

Format README files with consistent Constructive branding including centered header logos and appropriate badges for different package types.

When to Apply

Use this skill when:

• Creating a new npm, pnpm, or pgpm package
• Publishing a module to npm or pgpm registry
• Asked to add header images or badges to a README
• Standardizing README formatting across packages
• A README is missing the Constructive logo header

Header Logo

All Constructive packages should include a centered logo at the top of the README, immediately after the package title.

Standard Header (Most Packages)

# package-name

<p align="center" width="100%">
  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
</p>

Root Repository Header

For root-level README files (monorepo roots), use the filled logo with smaller height:

# Repository Name

<p align="center" width="100%">
  <img height="150" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/logo.svg" />
</p>

Badges

Badges appear in a centered paragraph below the logo. Include badges based on package type and visibility.

Badge Types

Badge Templates

CI Status Badge:

<a href="https://github.com/{org}/{repo}/actions/workflows/ci.yml">
  <img height="20" src="https://github.com/{org}/{repo}/actions/workflows/ci.yml/badge.svg" />
</a>

MIT License Badge:

<a href="https://github.com/{org}/{repo}/blob/main/LICENSE">
  <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
</a>

npm Version Badge (from package.json in repo):

<a href="https://www.npmjs.com/package/{package-name}">
  <img height="20" src="https://img.shields.io/github/package-json/v/{org}/{repo}?filename=packages%2F{package-folder}%2Fpackage.json"/>
</a>

npm Version Badge (from npm registry):

<a href="https://www.npmjs.com/package/{package-name}">
  <img height="20" src="https://img.shields.io/npm/v/{package-name}.svg"/>
</a>

Downloads Badge (optional):

<a href="https://www.npmjs.com/package/{package-name}">
  <img height="20" src="https://img.shields.io/npm/dm/{package-name}.svg"/>
</a>

Complete Badge Section

<p align="center" width="100%">
  <a href="https://github.com/{org}/{repo}/actions/workflows/ci.yml">
    <img height="20" src="https://github.com/{org}/{repo}/actions/workflows/ci.yml/badge.svg" />
  </a>
  <a href="https://github.com/{org}/{repo}/blob/main/LICENSE">
    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
  </a>
  <a href="https://www.npmjs.com/package/{package-name}">
    <img height="20" src="https://img.shields.io/npm/v/{package-name}.svg"/>
  </a>
</p>

Package Type Guidelines

npm/pnpm Packages (Published to npm)

Include: Logo + CI badge + License badge + Version badge

# @scope/package-name

<p align="center" width="100%">
  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
</p>

<p align="center" width="100%">
  <a href="https://github.com/constructive-io/repo/actions/workflows/ci.yml">
    <img height="20" src="https://github.com/constructive-io/repo/actions/workflows/ci.yml/badge.svg" />
  </a>
  <a href="https://github.com/constructive-io/repo/blob/main/LICENSE">
    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
  </a>
  <a href="https://www.npmjs.com/package/@scope/package-name">
    <img height="20" src="https://img.shields.io/npm/v/@scope/package-name.svg"/>
  </a>
</p>

Package description here.

pgpm Packages (PostgreSQL Modules)

Include: Logo + CI badge + License badge (no npm version badge)

# @pgpm/module-name

<p align="center" width="100%">
  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
</p>

<p align="center" width="100%">
  <a href="https://github.com/constructive-io/repo/actions/workflows/ci.yml">
    <img height="20" src="https://github.com/constructive-io/repo/actions/workflows/ci.yml/badge.svg" />
  </a>
  <a href="https://github.com/constructive-io/repo/blob/main/LICENSE">
    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
  </a>
</p>

Module description here.

Internal/Private Packages

Include: Logo only (no badges needed)

# package-name

<p align="center" width="100%">
  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
</p>

Package description here.

Packages with Custom License

For packages with "All Rights Reserved" or custom licenses, omit the license badge:

<p align="center" width="100%">
  <a href="https://github.com/constructive-io/repo/actions/workflows/ci.yml">
    <img height="20" src="https://github.com/constructive-io/repo/actions/workflows/ci.yml/badge.svg" />
  </a>
</p>

Complete README Template

# @scope/package-name

<p align="center" width="100%">
  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
</p>

<p align="center" width="100%">
  <a href="https://github.com/{org}/{repo}/actions/workflows/ci.yml">
    <img height="20" src="https://github.com/{org}/{repo}/actions/workflows/ci.yml/badge.svg" />
  </a>
  <a href="https://github.com/{org}/{repo}/blob/main/LICENSE">
    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
  </a>
  <a href="https://www.npmjs.com/package/@scope/package-name">
    <img height="20" src="https://img.shields.io/npm/v/@scope/package-name.svg"/>
  </a>
</p>

Brief description of what the package does.

## Installation

\`\`\`bash
pnpm add @scope/package-name
\`\`\`

## Usage

\`\`\`typescript
import { something } from '@scope/package-name';
\`\`\`

## API

Document the main exports and functions.

## License

MIT (or appropriate license)

Checklist

When formatting a README, verify:

• Package title is at the top (h1)
• Logo is centered below the title
• Logo uses correct URL (outline-logo.svg for packages, logo.svg for roots)
• Logo height is appropriate (250px for packages, 150px for roots)
• Badges are in a separate centered paragraph below logo
• Badge links point to correct URLs
• Version badge uses correct package name (with scope if applicable)
• License badge matches actual license in package
• CI badge points to correct workflow file

Common Mistakes

1. Missing logo: Always add the header logo
2. Wrong logo URL: Use the raw.githubusercontent.com URL, not a relative path
3. Badges in wrong order: CI, then License, then Version
4. Missing badge links: Each badge image should be wrapped in an anchor tag
5. Incorrect package name in version badge: Must match exactly what's published to npm
6. Using license badge for "All Rights Reserved": Only use for open source licenses

References

• Logo assets: https://github.com/constructive-io/constructive/tree/main/assets
• Shields.io badges: https://shields.io/
• Related skill: pnpm-publishing for publishing workflow
• Related skill: pgpm (references/publishing.md) for pgpm module publishing