shareful-create

Original：🇺🇸 English

Translated

Guides creation of high-quality SHARE.md files for shareful.ai. Covers repo setup, frontmatter, required sections, and validation. Use when the user wants to create a share, document a coding solution, contribute to shareful.ai, or run npx shareful-ai create.

7installs

Sourceshareful-ai/skills

Added on2026-02-10

NPX Install

npx skill4agent add shareful-ai/skills shareful-create

SKILL.md Content

View Translation Comparison →

Shareful Create

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

Reference Files

File	Read When
`references/frontmatter-guide.md`	Writing or reviewing frontmatter fields
`references/writing-sections.md`	Writing the four body sections
`references/quality-examples.md`	Calibrating quality or reviewing a draft share
`references/validation-checklist.md`	Final validation pass before finishing

Creation Workflow

Copy this checklist to track progress:

text

- [ ] 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:

Read
```
~/.shareful/config.json
```
for the
```
sharesRepo
```
path
If set, verify the path contains a
```
shares/
```
directory
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

Type	Use when	Title convention
`fix`	Directly resolves a bug or error	"Fix ..."
`workaround`	Temporarily bypasses a known issue	"Workaround for ..."
`pattern`	Reusable coding pattern or architecture	"Use ...", "Implement ..."
`reference`	Lookup guide or cheat sheet	"Guide to ...", "Reference for ..."
`config`	Configuration change resolving a setup issue	"Configure ..."

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:

yaml

---
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:

## Problem -- Show the broken state with real code and error messages
## Solution -- Provide working code with multiple options when applicable
## Why It Works -- Explain the underlying mechanism, not just "what" but "why"
## 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

bash

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