readme-style-guide
Skill9 starsChanged 7 months agoMITView on GitHub
Canonical README template and validation rules for Wicked Garden marketplace plugins.
In this repository142 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- plugin-json-schemaSkill
- releaseSkill
- scaffoldSkill
- wicked-garden-agentic-agentic-patternsSkill
- wicked-garden-agentic-architectSkill
- wicked-garden-agentic-context-engineeringSkill
- wicked-garden-agentic-frameworksSkill
- wicked-garden-agentic-performance-analystSkill
- wicked-garden-agentic-review-methodologySkill
- wicked-garden-agentic-safety-reviewerSkill
- wicked-garden-agenticSkill
- wicked-garden-agentic-trust-and-safetySkill
- wicked-garden-appsSkill
- wicked-garden-archetypeSkill
- wicked-garden-build-guideSkill
- wicked-garden-classifySkill
- wicked-garden-coreSkill
- wicked-garden-data-engineerSkill
- wicked-garden-dataSkill
- wicked-garden-deliberateSkill
- wicked-garden-demoSkill
- wicked-garden-domain-coverageSkill
- wicked-garden-domain-extractorSkill
- wicked-garden-domain-modelerSkill
- wicked-garden-domainSkill
- wicked-garden-draftSkill
- wicked-garden-editor-scaffoldSkill
- wicked-garden-engineering-api-documentarianSkill
- wicked-garden-engineering-architectureSkill
- wicked-garden-engineering-backendSkill
- wicked-garden-engineering-debuggingSkill
- wicked-garden-engineering-docsSkill
- wicked-garden-engineering-frontendSkill
- wicked-garden-engineering-integrationSkill
- wicked-garden-engineering-large-scale-migrationSkill
- wicked-garden-engineering-migration-engineerSkill
- wicked-garden-engineering-patchSkill
- wicked-garden-engineeringSkill
- wicked-garden-engineering-solution-architectSkill
- wicked-garden-engineering-system-designSkill
- wicked-garden-engineering-unit-test-qualitySkill
- wicked-garden-governed-workerSkill
- wicked-garden-groundSkill
- wicked-garden-jam-brainstorm-facilitatorSkill
- wicked-garden-jam-councilSkill
- wicked-garden-jamSkill
- wicked-garden-learnSkill
- wicked-garden-mcp-scaffoldSkill
- wicked-garden-mcpSkill
- wicked-garden-mem-captureSkill
- wicked-garden-mem-ingestSkill
- wicked-garden-memSkill
- wicked-garden-personaSkill
- wicked-garden-platform-auditSkill
- wicked-garden-platform-compliance-officerSkill
- wicked-garden-platform-complianceSkill
- wicked-garden-platform-errorsSkill
- wicked-garden-platform-gate-benchmark-rebaselineSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Every plugin README follows this structure.
- Distinctive: line 54
No prose explanations in Quick Start.
- Distinctive: line 72
Use active voice in "What It Unlocks" to imply directionality (who calls whom).
- Distinctive: line 88
Every marketing claim backed by a concrete example or code block
- Distinctive: line 89
No hedging language ("might", "could potentially")
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
README Style Guide
Standard structure, tone, and content rules for Wicked Garden plugin READMEs.
Canonical Section Order
Every plugin README follows this structure. Sections marked CONDITIONAL include their trigger rule.
1. # wicked-garden ← h1 + tagline (REQUIRED)
2. ## {Lifecycle/Value Section} ← CONDITIONAL: value invisible in single command
3. ## Quick Start ← REQUIRED: 3 commands max
4. ## {Core Workflows} ← REQUIRED: 2-3 real scenarios with output
5. ## Commands ← REQUIRED: reference table
6. ## When to Use What ← CONDITIONAL: 3+ commands with overlapping scope
7. ## How It Works ← CONDITIONAL: mechanism is part of value prop
8. ## Agents / Skills ← REQUIRED if plugin has agents or skills
9. ## Data API ← CONDITIONAL: plugin exposes CP data sources
10. ## Integration ← REQUIRED: 3-column table
11. ## License ← REQUIREDTagline Rules
The first line after the h1 heading is the tagline. It must:
- Be one sentence making a specific, differentiating claim
- Name the behavior or outcome, NOT the category
- Be falsifiable — a reader can verify whether it's true
GOOD: "Structural code intelligence across 73 languages — trace a JSP field to its database column."
BAD: "A code search plugin for Claude Code."
GOOD: "Cross-session memory with signal-based recall and automatic decay."
BAD: "A memory management plugin."Quick Start Rules
Exactly 3 commands, labeled:
- Install command
- First win (simplest useful command)
- Most common use case
No prose explanations in Quick Start. That goes in Workflows or How It Works.
Workflow Section
Appears BEFORE the Commands reference table. Workflows persuade; Commands reference.
Each workflow: heading + code block (3-5 commands) + optional expected output block. Show real output when possible — what does the user actually see?
Integration Table Format
Three columns are mandatory. The "Without It" column converts a dependency list into a value story.
| Plugin | What It Unlocks | Without It |
|--------|----------------|------------|
| wicked-mem | Decisions persist across sessions | Brainstorming works, but insights aren't stored |Use active voice in "What It Unlocks" to imply directionality (who calls whom).
Conditional Section Triggers
| Section | Include When |
| Lifecycle | Core value requires multiple invocations to see |
| When to Use What | 3+ commands with overlapping scope |
| How It Works | Internal mechanism is part of the value proposition |
| Data API | Plugin exposes data via DomainStore or external integrations |
| Agents & Skills | Merge tables if combined rows ≤5; split if either has 5+ |
Tone
- Confident, specific, technically precise
- Lead with "why" before "what"
- Every marketing claim backed by a concrete example or code block
- No hedging language ("might", "could potentially")
References
- Full annotated template:
refs/template.md - Validation rules and checklist:
refs/rules.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

