Shareful Create

Create SHARE.md files that follow shareful.ai quality standards from first draft through validation.

Reference Files

Creation Workflow

Copy this checklist to track progress:

- [ ] Step 1: Ensure shares repo context exists
- [ ] Step 2: Classify the problem and choose solution type
- [ ] Step 3: Draft frontmatter
- [ ] Step 4: Draft the required body sections
- [ ] Step 5: Create SHARE.md
- [ ] Step 6: Validate with checklist

Step 1: Ensure Shares Repo Context Exists

Check if a shares repo is configured:

1. Read ~/.shareful/config.json for the sharesRepo path
2. If set, verify the path contains a shares/ directory
3. If not set, run npx shareful-ai init [name] to create and configure a repo

The init command creates the directory structure and saves the repo path to config.

Step 2: Classify Problem and Choose Solution Type

Determine what was solved and choose the correct solution_type:

Most shares are fix type. Use pattern only when the solution generalizes beyond a single error.

Step 3: Draft Frontmatter

Read references/frontmatter-guide.md for the complete schema and examples.

Required fields:

---
title: "Human-readable title"          # max 128 chars
slug: kebab-case-identifier             # max 64 chars, a-z 0-9 hyphens only
tags: [tag1, tag2, tag3]                # 1-10 tags, max 32 chars each, lowercase
problem: "One-sentence problem summary" # max 256 chars
solution_type: fix                      # fix | workaround | pattern | reference | config
created: 2026-02-08                     # YYYY-MM-DD
environment:                            # optional but recommended
  language: typescript
  framework: nextjs
  version: "15+"
---

Key rules:

• Slug is auto-generated from title: lowercase, strip special chars, spaces to hyphens, max 64 chars
• Slug MUST match the parent directory name
• Problem field should include the error message or symptom for searchability
• Tags should cover: primary technology, problem domain, and 1-2 descriptors

Step 4: Draft the Required Body Sections

Read references/writing-sections.md for templates and guidance.

Optionally read references/quality-examples.md for annotated good and bad examples.

All four sections are required:

1. ## Problem -- Show the broken state with real code and error messages
2. ## Solution -- Provide working code with multiple options when applicable
3. ## Why It Works -- Explain the underlying mechanism, not just "what" but "why"
4. ## Context -- List environment requirements, gotchas, and related tools

The body must be under 300 lines total. Aim for 60-150 lines.

Step 5: Create SHARE.md

Option A: Use the CLI

npx shareful-ai create --title "Fix Prisma N+1 queries" --tags "prisma,database,performance" --type fix --problem "Prisma makes hundreds of queries when loading related data"

Then edit the generated shares/<slug>/SHARE.md to replace template content with real content.

Option B: Write directly

Create shares/<slug>/SHARE.md with the complete frontmatter and body. Ensure the shares/ directory exists (run npx shareful-ai init if not).

Step 6: Validate with Checklist

Read references/validation-checklist.md and run all checks.

Expected output after this step:

• A complete shares/<slug>/SHARE.md file
• Frontmatter and section structure validated
• No placeholder content

Anti-patterns

• Writing a vague problem field ("Something is broken") instead of including the actual error message
• Using Why It Works to repeat the solution instead of explaining the underlying mechanism
• Forgetting language labels on code blocks
• Making the title too generic ("Fix TypeScript error") instead of specific ("Fix TypeScript module augmentation for third-party types")
• Slug not matching the directory name
• Exceeding 300 lines in the body
• Using pattern type for what is actually a fix (pattern is for reusable architecture, not bug fixes)

Related Skills

• shareful-search for discovering existing shares on shareful.ai