What is a share?

A share is a structured markdown file (SHARE.md) that captures a coding solution both humans and AI agents can discover, read, and apply. Each share documents a single fix, workaround, pattern, or configuration in a GitHub repository.

How shares work

Shares follow a three-step lifecycle:

1. Create -- Capture a solution as a SHARE.md file using the CLI or by writing it directly.
2. Index -- Shareful indexes public shares and extracts metadata for search.
3. Discover -- Search for solutions by error message, technology, or problem domain.

The SHARE.md file

Every share lives in a directory named after its slug inside a shares/ folder:

shares/
  fix-nextjs-hydration-mismatch/
    SHARE.md
  prisma-connection-pooling/
    SHARE.md

A SHARE.md file has two parts:

• Frontmatter -- YAML metadata (title, slug, tags, problem, solution type) that powers search and filtering.
• Body -- four required sections:

Minimal frontmatter example:

---
title: Fix Next.js hydration mismatch with dynamic imports
slug: fix-nextjs-hydration-mismatch
tags: [nextjs, react, hydration]
problem: Component using window throws hydration mismatch error
solution_type: fix
created: "2025-01-15"
---

Solution types

Every share has a solution_type. Most are fix. See the solution type reference for all five types and their title conventions.

Why structured format matters

The structured format gives you four things:

• Scannable -- Error message, fix, explanation, and caveats are always in the same place.
• Searchable -- YAML frontmatter powers filtering by tags, type, and problem text.
• Complete -- Four mandatory sections prevent half-finished solutions.
• AI-readable -- Agents can parse, match, and apply shares programmatically.

Next steps

• Create your first share
• See the full format spec