From 80ff74468c8934f8af83563cefd7eb78cfdeb153 Mon Sep 17 00:00:00 2001 From: Salvydas Lukosius Date: Sat, 20 Jun 2026 02:06:03 +0100 Subject: [PATCH 1/5] docs(readme): add Zsh plugin template --- templates/readme/zsh-plugin.md | 141 +++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 templates/readme/zsh-plugin.md diff --git a/templates/readme/zsh-plugin.md b/templates/readme/zsh-plugin.md new file mode 100644 index 000000000..fd06907e6 --- /dev/null +++ b/templates/readme/zsh-plugin.md @@ -0,0 +1,141 @@ +# 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. + +--- + + + +
+ + <Plugin name> logo + + +

<Plugin name>

+

<One sentence describing the observable value of the plugin.>

+

+ + CI status + + + License + +

+
+ +## Features + +- +- +- + + + +![](repository-owned-asset-path) + +## Requirements + +- Zsh +- `` available on `PATH` +- + +## Installation + +### Zi + +```zsh +zi light z-shell/ +``` + + + +### Other plugin managers + + + +## Configuration + + + +| Name | Type | Default | Effect | +| ------------------ | -------- | ----------- | ------------------- | +| `` | `` | `` | | + +## Usage + + + +## Lifecycle and side effects + +- +- +- + +## Verification + +From the repository root: + +```bash + +``` + + + +## Documentation and support + +- [Z-Shell wiki](https://wiki.zshell.dev/) +- [Report an issue](https://github.com/z-shell//issues) + +## Release model + + + +## 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. + + From f0f6dea2a7bf4f9123a8f58416bd32a44dfb4db5 Mon Sep 17 00:00:00 2001 From: Salvydas Lukosius Date: Sat, 20 Jun 2026 02:37:23 +0100 Subject: [PATCH 2/5] docs(readme): integrate plugin template guidance --- .../documentation.instructions.md | 11 ++++ .github/skills/create-readme/SKILL.md | 52 ++++++++++++++----- runbooks/new-repository.md | 24 ++++++--- 3 files changed, 65 insertions(+), 22 deletions(-) diff --git a/.github/instructions/documentation.instructions.md b/.github/instructions/documentation.instructions.md index d5089fe32..a50b9dd6f 100644 --- a/.github/instructions/documentation.instructions.md +++ b/.github/instructions/documentation.instructions.md @@ -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 diff --git a/.github/skills/create-readme/SKILL.md b/.github/skills/create-readme/SKILL.md index d9dca3b47..4e929d66f 100644 --- a/.github/skills/create-readme/SKILL.md +++ b/.github/skills/create-readme/SKILL.md @@ -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. diff --git a/runbooks/new-repository.md b/runbooks/new-repository.md index 3caecbdcf..2fcbc5b70 100644 --- a/runbooks/new-repository.md +++ b/runbooks/new-repository.md @@ -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 From d15f5b65a037fd8b943609a985bee8efa0b40e92 Mon Sep 17 00:00:00 2001 From: Salvydas Lukosius Date: Sat, 20 Jun 2026 02:43:57 +0100 Subject: [PATCH 3/5] style(docs): format documentation instructions --- .github/instructions/documentation.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/instructions/documentation.instructions.md b/.github/instructions/documentation.instructions.md index a50b9dd6f..6c5bb9fd8 100644 --- a/.github/instructions/documentation.instructions.md +++ b/.github/instructions/documentation.instructions.md @@ -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. From 55d4f3d71383c5805ea8976f866119fcfc1875a5 Mon Sep 17 00:00:00 2001 From: Salvydas Lukosius Date: Sat, 20 Jun 2026 13:48:51 +0100 Subject: [PATCH 4/5] docs(readme): harden template accessibility --- templates/readme/zsh-plugin.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/templates/readme/zsh-plugin.md b/templates/readme/zsh-plugin.md index fd06907e6..783c518b2 100644 --- a/templates/readme/zsh-plugin.md +++ b/templates/readme/zsh-plugin.md @@ -1,4 +1,5 @@ -# Zsh Plugin README Template + @@ -16,7 +18,7 @@ plugin. <Plugin name> logo @@ -49,9 +51,10 @@ plugin. +available and the asset must be reviewed manually when output changes. -![](repository-owned-asset-path) +![]() +--> ## Requirements @@ -73,7 +76,8 @@ plugin capability, not merely an alternative spelling of the basic load. --> ### Other plugin managers +section compact and do not compare competing projects' feature sets. Remove +this subsection entirely when no additional manager has verified support.> ## Configuration From 5a0cb33f9f8a9ade9c7e9e24c51b4e4c271b319f Mon Sep 17 00:00:00 2001 From: Sall Date: Sat, 20 Jun 2026 21:26:09 +0100 Subject: [PATCH 5/5] docs(readme): harden template accessibility --- templates/readme/zsh-plugin.md | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/templates/readme/zsh-plugin.md b/templates/readme/zsh-plugin.md index 783c518b2..388694afd 100644 --- a/templates/readme/zsh-plugin.md +++ b/templates/readme/zsh-plugin.md @@ -1,5 +1,4 @@ - - -