z-shell · ss-o · Jun 21, 2026 · Jun 20, 2026 · Jun 20, 2026 · Jun 20, 2026
@@ -25,7 +25,7 @@ The wiki has three independent content roots. Place content by audience and
 purpose, not by topic:
 
 - **`docs/`** — Zi **end-user** documentation: getting started, usage, guides for
-  people *using* the tools.
+  people _using_ the tools.
 - **`community/`** — community-facing material: standards, contribution norms,
   ecosystem-wide conventions.
 - **`ecosystem/`** — ecosystem catalog: plugins, annexes, and related projects.
@@ -43,6 +43,17 @@ Maintainer/operational guides are **not** end-user docs — do not place them un
 - Never commit secret values or stale secret-key names in docs; reference the
   current canonical names only.
 
+## Zsh plugin READMEs
+
+Use [`templates/readme/zsh-plugin.md`](../../templates/readme/zsh-plugin.md)
+when creating a Zsh plugin repository or substantially restructuring its
+README. Focused corrections do not require an unrelated full rewrite.
+
+The template standardizes required information and visual hierarchy, not
+identical prose or artwork. Zi remains the first installation path. Include a
+screenshot or short demo only when it materially explains behavior, and keep
+long-form ecosystem guidance in the wiki.
+
 ## LLM/agent files
 
 Per the workspace LLM file-placement policy, keep generic agent instructions

@@ -1,21 +1,45 @@
 ---
 name: create-readme
-description: "Create a README.md file for the project"
+description: "Create or substantially refactor a repository README"
 ---
 
-## Role
+# Create README
 
-You're a senior expert software engineer with extensive experience in open source projects. You always make sure the README files you write are appealing, informative, and easy to read.
+Create an accurate, concise, and visually intentional repository landing page.
 
-## Task
+## Required workflow
 
-1. Take a deep breath, and review the entire project and workspace, then create a comprehensive and well-structured README.md file for the project.
-2. Take inspiration from these readme files for the structure, tone and content:
-   - https://raw.githubusercontent.com/Azure-Samples/serverless-chat-langchainjs/refs/heads/main/README.md
-   - https://raw.githubusercontent.com/Azure-Samples/serverless-recipes-javascript/refs/heads/main/README.md
-   - https://raw.githubusercontent.com/sinedied/run-on-output/refs/heads/main/README.md
-   - https://raw.githubusercontent.com/sinedied/smoke/refs/heads/main/README.md
-3. Do not overuse emojis, and keep the readme concise and to the point.
-4. Do not include sections like "LICENSE", "CONTRIBUTING", "CHANGELOG", etc. There are dedicated files for those sections.
-5. Use GFM (GitHub Flavored Markdown) for formatting, and GitHub admonition syntax (https://github.com/orgs/community/discussions/16925) where appropriate.
-6. If you find a logo or icon for the project, use it in the readme's header.
+1. Read the repository's source, tests, workflows, local instructions, release
+   model, and linked organization policy before drafting.
+2. Classify the repository. For a Zsh plugin, use
+   [`templates/readme/zsh-plugin.md`](../../../templates/readme/zsh-plugin.md)
+   as the canonical structure.
+3. Verify every feature, setting, default, alias, lifecycle claim, command, and
+   branch statement against the current implementation.
+4. Lead Zsh-plugin installation guidance with Zi. Keep other manager examples
+   concise and include only intentionally supported or verified paths.
+5. Keep long-form ecosystem guidance in the wiki and link to it.
+6. Preserve meaningful visual identity: a clear header, a restrained maintained
+   badge set, accessible alt text, and an optional behavior-focused screenshot
+   or demo.
+7. Do not add competitor comparisons unless comparison is the document's
+   explicit purpose.
+8. Run repository-appropriate Markdown, link, syntax, and behavior checks before
+   claiming completion.
+
+## Visual guidance
+
+- Use GitHub Flavored Markdown and minimal HTML where it materially improves the
+  header or image sizing.
+- Do not use decorative link clusters, excessive badges, emoji-heavy headings,
+  or images without useful alt text.
+- Prefer repository-owned assets.
+- Screenshot and terminal-demo automation is tracked in Linear ZSH-18; until it
+  lands, manually maintained visuals must be reviewed when documented output
+  changes.
+
+## Scope
+
+For focused README corrections, change only the affected content. Apply the
+full template when creating a repository or when the requested work is a
+substantial README refactor.
@@ -34,9 +34,13 @@ README.md
   workflows/
 ```
 
-Use the organization-approved license for the artifact. The initial `README.md`
-must state the purpose, install path, supported shell/runtime, verification
-command, release model, and wiki link.
+Use the organization-approved license for the artifact. For a Zsh plugin,
+start from [`templates/readme/zsh-plugin.md`](../templates/readme/zsh-plugin.md).
+The initial README must state the purpose, features, install path, supported
+shell/runtime, public configuration, lifecycle behavior, verification command,
+release model, and wiki link. Preserve the template's accessible visual
+hierarchy, but replace its placeholders and omit optional sections that do not
+serve the plugin.
 
 Do not copy generic `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/agents/`, or
 `.github/instructions/` files into child repositories. Link to the organization
@@ -116,12 +120,16 @@ Before opening the bootstrap pull request:
 6. Link the tracker issue and leave an `Agent handoff` comment for deferred
    template or release work.
 
-## Deferred template assets
+## Deferred scaffold assets
 
-Keep this runbook as the source of truth until repeated bootstrap work proves a
-stable scaffold. Create dedicated template repositories only through separate
-tracked issues; do not grow this public meta-repository into a generated source
-tree prematurely.
+The organization maintains focused templates such as
+`templates/readme/zsh-plugin.md`, but does not maintain a generated repository
+source tree. Create dedicated template repositories only through separate
+tracked issues after repeated bootstrap work proves a stable full-repository
+scaffold.
+
+Reusable screenshot and terminal-demo generation is tracked separately in
+[Linear ZSH-18](https://linear.app/ss-o/issue/ZSH-18/automate-readme-screenshots-and-terminal-demos-for-zsh-plugins).
 
 ## See also
 

@@ -0,0 +1,137 @@
+# Zsh Plugin README Template
+
+Use this template for new Z-Shell Zsh plugins and substantial README
+refactors. Replace every angle-bracketed field and remove instructional
+comments before publication.
+
+Required sections may be concise, but they must not be omitted. Optional
+sections should be included only when they help users understand or operate the
+plugin.
+
+---
+
+<div align="center">
+  <a href="https://github.com/z-shell/<repository>">
+    <img
+      src="https://raw.githubusercontent.com/z-shell/zi/main/docs/images/logo.svg"
+      alt="<Plugin name> logo"
+      width="72"
+      height="72"
+    />
+  </a>
+
+  <h1>&lt;Plugin name&gt;</h1>
+  <p>&lt;One sentence describing the observable value of the plugin.&gt;</p>
+  <p>
+    <a href="https://github.com/z-shell/<repository>/actions/workflows/<validation-workflow>.yml">
+      <img
+        src="https://github.com/z-shell/<repository>/actions/workflows/<validation-workflow>.yml/badge.svg?branch=main"
+        alt="CI status"
+      />
+    </a>
+    <a href="LICENSE">
+      <img
+        src="https://img.shields.io/github/license/z-shell/<repository>"
+        alt="License"
+      />
+    </a>
+  </p>
+</div>
+
+## Features
+
+- <Concrete capability>
+- <Concrete capability>
+- <Concrete capability>
+
+<!-- Optional: include a screenshot or short demo only when it makes behavior
+materially easier to understand. Use a repository-owned asset, useful alt text,
+and restrained dimensions. Until Linear ZSH-18 lands, generated visuals are not
+available and the asset must be reviewed manually when output changes. -->
+
+![<What the visual demonstrates>](repository-owned-asset-path)
+
+## Requirements
+
+- Zsh <supported version or "a currently supported Zsh release">
+- `<required-command>` available on `PATH`
+- <platform or terminal constraint, if any>
+
+## Installation
+
+### Zi
+
+```zsh
+zi light z-shell/<repository>
+```
+
+<!-- Optional: retain one advanced Zi example only when it demonstrates a real
+plugin capability, not merely an alternative spelling of the basic load. -->
+
+### Other plugin managers
+
+<List only intentionally supported or verified loading methods. Keep this
+section compact and do not compare competing projects' feature sets.>
+
+## Configuration
+
+<State which values must be set before loading. Document only the public
+contract.>
+
+| Name               | Type     | Default     | Effect              |
+| ------------------ | -------- | ----------- | ------------------- |
+| `<public-setting>` | `<type>` | `<default>` | <Observable effect> |
+
+## Usage
+
+<Show the smallest useful example. Use a table for exact alias, command, or
+option mappings.>
+
+## Lifecycle and side effects
+
+- <State changed during load>
+- <Behavior when a required dependency is unavailable>
+- <Unload function and the state it restores>
+
+## Verification
+
+From the repository root:
+
+```bash
+<exact verification command>
+```
+
+<State any prerequisite not supplied by the repository.>
+
+## Documentation and support
+
+- [Z-Shell wiki](https://wiki.zshell.dev/)
+- [Report an issue](https://github.com/z-shell/<repository>/issues)
+
+## Release model
+
+<State the stable branch, development branch when applicable, and whether the
+plugin is consumed directly from Git or published as a versioned artifact.>
+
+## Contributing and license
+
+Contributions follow the
+[Z-Shell organization guidance](https://github.com/z-shell/.github).
+This project is distributed under the terms in [LICENSE](LICENSE).
+
+---
+
+## Maintainer checklist
+
+- [ ] The purpose and feature claims match current implementation behavior.
+- [ ] Zi is the first installation path.
+- [ ] Other manager examples are intentionally supported or verified.
+- [ ] Public settings, aliases, functions, hooks, and defaults are complete.
+- [ ] Load failures and unload behavior are documented.
+- [ ] The verification command runs from a clean checkout.
+- [ ] Long-form guidance links to the wiki instead of being duplicated.
+- [ ] Badges are maintained signals rather than decoration.
+- [ ] Images use useful alt text and durable repository-owned URLs.
+- [ ] Screenshots or demos are included only when they explain behavior.
+- [ ] Release-model and stable-branch statements match organization policy.
+- [ ] No competitor comparison creates an avoidable drift obligation.