agentleFS
mikeparcewskimikeparcewski/wicked-garden/.claude/skills/readme-style-guide/SKILL.md

readme-style-guide

Skill9 starsChanged 7 months agoMITView on GitHub

Canonical README template and validation rules for Wicked Garden marketplace plugins.

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
  1. Distinctive:

    Every plugin README follows this structure.

    line 16
  2. Distinctive:

    No prose explanations in Quick Start.

    line 54
  3. Distinctive:

    Use active voice in "What It Unlocks" to imply directionality (who calls whom).

    line 72
  4. Distinctive:

    Every marketing claim backed by a concrete example or code block

    line 88
  5. Distinctive:

    No hedging language ("might", "could potentially")

    line 89

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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                                ← REQUIRED

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

  1. Install command
  2. First win (simplest useful command)
  3. 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

SectionInclude When
LifecycleCore value requires multiple invocations to see
When to Use What3+ commands with overlapping scope
How It WorksInternal mechanism is part of the value proposition
Data APIPlugin exposes data via DomainStore or external integrations
Agents & SkillsMerge 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.