readme-writing

Name: readme-writing
Author: easyzoom

22stars2forks

How to install readme-writing?

easyzoom/aix-skills/readme-writing

$npx -y skills add easyzoom/aix-skills --skill readme-writing

Installs into the current project.

Summary

Use when creating, rewriting, or improving README files for public repositories

Files · 1

View on GitHub

SKILL.md

1	# README Writing
2
3	## Overview
4
5	Write README files that help a visitor understand the project in the first screen, trust it within one minute, and try it without guessing. A good README is a landing page, setup guide, and trust signal at the same time.
6
7	## When To Use
8
9	Use this skill when:
10
11	- Creating a new `README.md`.
12	- Rewriting a README for a public repository.
13	- Improving a README's clarity, structure, visuals, or quickstart.
14	- Adding badges, screenshots, diagrams, language links, or contribution sections.
15	- Making a repository more attractive for GitHub readers.
16
17	Do not use it for long-form product docs, API references, or internal-only runbooks unless the user specifically wants a README-style entry page.
18
19	## Workflow
20
21	1. Identify the primary reader.
22	Decide whether the README is for users, developers, contributors, evaluators, or agents. Put the most important reader first.
23
24	2. Write the first screen.
25	Include project name, one-sentence value proposition, optional language links, visual banner or screenshot, and trust badges.
26
27	3. Explain the project quickly.
28	State what it does, who it is for, and why it is different. Avoid marketing fluff that does not help someone decide whether to continue.
29
30	4. Show the fastest path to value.
31	Provide a short quickstart with commands that can be copied. Include expected output when it reduces uncertainty.
32
33	5. Show structure and capabilities.
34	List key directories, features, or modules. Use tables for scanability when comparing multiple items.
35
36	6. Add proof.
37	Include screenshots, SVG diagrams, badges, test commands, examples, or links to demos. Prefer local assets for long-lived public repos.
38
39	7. Cover contribution and license.
40	Link to contribution docs, issue templates, validation commands, and license.
41
42	8. Verify the README.
43	Check links, commands, image paths, and consistency with the actual repository.
44
45	## Recommended Structure
46
47	```markdown
48	# Project Name
49
50	Language links, badges, and hero image.
51
52	One-sentence value proposition.
53
54	## Why This Exists
55	## Features
56	## Quickstart
57	## Examples
58	## Project Structure
59	## Contributing
60	## License
61	```
62
63	Adjust the sections to the project. Keep the README useful, not ceremonial.
64
65	## Visual Guidelines
66
67	- Use a hero image, product screenshot, or architecture diagram when it helps visitors understand the project faster.
68	- Prefer local assets under `docs/assets/` for stability.
69	- Use badges sparingly: license, tests, package version, or public readiness are usually enough.
70	- Add alt text for images.
71	- Avoid huge images that push all useful text below the fold.
72
73	## Multilingual README Pattern
74
75	For multilingual repositories:
76
77	- Keep `README.md` as the default language most GitHub visitors should see.
78	- Add language links near the top.
79	- Use files like `README.zh-CN.md` for full translations.
80	- Keep shared sections such as features, quickstart, and skill lists consistent across languages.
81
82	## Verification
83
84	Before claiming completion:
85
86	- Confirm every referenced file path exists.
87	- Confirm links point to the right local files or public URLs.
88	- Run repository validation or tests if README commands mention them.
89	- Check that badges and images render from valid URLs or local files.
90	- Re-read the first screen and verify it answers: what is this, why care, how do I start?
91
92	## Common Failures
93
94	- Starting with a long backstory instead of a clear value proposition.
95	- Including installation commands that do not match the repository.
96	- Adding badges that look impressive but do not communicate useful trust.
97	- Using screenshots or diagrams without alt text.
98	- Letting translated READMEs drift from the main README.
99	- Hiding the quickstart below too much explanation.
100
101	## Example
102
103	User:
104
105	```text
106	Make this repository README more attractive for GitHub.
107	```
108
109	Agent:
110
111	1. Reads the project structure and existing README.
112	2. Identifies the target reader and primary use case.
113	3. Adds a strong first screen with badges and a local hero image.
114	4. Adds a short quickstart and capability table.
115	5. Verifies image paths, links, and commands before reporting completion.

People who liked this also viewed

6 picks

Type

azure-diagnosticsDebug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deploySkillsJul 2026472k1.3k
systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesSkillsJul 2026197k259k
safe-debugRigor Debug / Rigor Audit skill for deep learning research work. Use when the user pastes a traceback, terminal error, CUDA OOM, checkpoint load failure, shape mismatch, NaN loss symptom, or training SkillsMay 2026161k507
explore-runRigor Improve / Rigor Explore run leaf skill for bounded exploratory evidence in deep learning research repositories. Use when the researcher explicitly authorizes exploratory runs such as small-subseSkillsMay 2026161k507
minimal-run-and-auditRigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation SkillsMay 2026161k507
insforge-debugUse when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denSkillsJul 202618k31

readme-writing

22stars2forks

View on GitHub

How to install readme-writing?

easyzoom/aix-skills/readme-writing

$npx -y skills add easyzoom/aix-skills --skill readme-writing

Installs into the current project.

Summary

Use when creating, rewriting, or improving README files for public repositories

Files · 1

View on GitHub

SKILL.md

1	# README Writing
2
3	## Overview
4
5	Write README files that help a visitor understand the project in the first screen, trust it within one minute, and try it without guessing. A good README is a landing page, setup guide, and trust signal at the same time.
6
7	## When To Use
8
9	Use this skill when:
10
11	- Creating a new `README.md`.
12	- Rewriting a README for a public repository.
13	- Improving a README's clarity, structure, visuals, or quickstart.
14	- Adding badges, screenshots, diagrams, language links, or contribution sections.
15	- Making a repository more attractive for GitHub readers.
16
17	Do not use it for long-form product docs, API references, or internal-only runbooks unless the user specifically wants a README-style entry page.
18
19	## Workflow
20
21	1. Identify the primary reader.
22	Decide whether the README is for users, developers, contributors, evaluators, or agents. Put the most important reader first.
23
24	2. Write the first screen.
25	Include project name, one-sentence value proposition, optional language links, visual banner or screenshot, and trust badges.
26
27	3. Explain the project quickly.
28	State what it does, who it is for, and why it is different. Avoid marketing fluff that does not help someone decide whether to continue.
29
30	4. Show the fastest path to value.
31	Provide a short quickstart with commands that can be copied. Include expected output when it reduces uncertainty.
32
33	5. Show structure and capabilities.
34	List key directories, features, or modules. Use tables for scanability when comparing multiple items.
35
36	6. Add proof.
37	Include screenshots, SVG diagrams, badges, test commands, examples, or links to demos. Prefer local assets for long-lived public repos.
38
39	7. Cover contribution and license.
40	Link to contribution docs, issue templates, validation commands, and license.
41
42	8. Verify the README.
43	Check links, commands, image paths, and consistency with the actual repository.
44
45	## Recommended Structure
46
47	```markdown
48	# Project Name
49
50	Language links, badges, and hero image.
51
52	One-sentence value proposition.
53
54	## Why This Exists
55	## Features
56	## Quickstart
57	## Examples
58	## Project Structure
59	## Contributing
60	## License
61	```
62
63	Adjust the sections to the project. Keep the README useful, not ceremonial.
64
65	## Visual Guidelines
66
67	- Use a hero image, product screenshot, or architecture diagram when it helps visitors understand the project faster.
68	- Prefer local assets under `docs/assets/` for stability.
69	- Use badges sparingly: license, tests, package version, or public readiness are usually enough.
70	- Add alt text for images.
71	- Avoid huge images that push all useful text below the fold.
72
73	## Multilingual README Pattern
74
75	For multilingual repositories:
76
77	- Keep `README.md` as the default language most GitHub visitors should see.
78	- Add language links near the top.
79	- Use files like `README.zh-CN.md` for full translations.
80	- Keep shared sections such as features, quickstart, and skill lists consistent across languages.
81
82	## Verification
83
84	Before claiming completion:
85
86	- Confirm every referenced file path exists.
87	- Confirm links point to the right local files or public URLs.
88	- Run repository validation or tests if README commands mention them.
89	- Check that badges and images render from valid URLs or local files.
90	- Re-read the first screen and verify it answers: what is this, why care, how do I start?
91
92	## Common Failures
93
94	- Starting with a long backstory instead of a clear value proposition.
95	- Including installation commands that do not match the repository.
96	- Adding badges that look impressive but do not communicate useful trust.
97	- Using screenshots or diagrams without alt text.
98	- Letting translated READMEs drift from the main README.
99	- Hiding the quickstart below too much explanation.
100
101	## Example
102
103	User:
104
105	```text
106	Make this repository README more attractive for GitHub.
107	```
108
109	Agent:
110
111	1. Reads the project structure and existing README.
112	2. Identifies the target reader and primary use case.
113	3. Adds a strong first screen with badges and a local hero image.
114	4. Adds a short quickstart and capability table.
115	5. Verifies image paths, links, and commands before reporting completion.

People who liked this also viewed

6 picks

Type