generate-standard-readme

Skill: Generate a minimal README

Purpose

Generate for any software project or documentation repositorya high information density, low redundancyhomepage document.

The single core goal: readers know within 30 seconds—

1. what this project is (in one sentence)
2. where to find key entry points
3. how to use it (the shortest executable path)

---

Scope

This skill is responsible for：

• generating a minimal README with sections trimmed by the value threshold
• project type triage (code/application repository vs documentation/specification repository)
• anti-fluff output (every claim lands on a specific path, command, behavior, or constraint)

This skill is not responsible for：

• Complete docs/ suite → handled by AgentFabric runtime or manually according to docs/ARTIFACT_NORMS.md Contraction/continuation
• AGENTS.md / agent contract files → use generate-agent-entry
• sensitive information redaction → use decontextualize-text

---

Use cases

• New repository: after project creation, homepage documentation is needed and there is no existing README.
• Asset governance: unify README style across services and improve indexability.
• Legacy systems: fill in missing documentation and cover core entry points with the minimum amount of information.
• Handover and release: ensure homepage documentation is complete before project handover or public release.

Trigger signals: the user says "help me write a README", "generate a self-description file", or directly provides the repository path.

---

Behavior

Interaction strategy

Situation	Behavior
Project type known	Generate directly, no need to ask
Project type unknown	First inspect the repository structure (whether there is package.json / pyproject.toml / Dockerfile / INDEX.md etc.) to infer the type; if the inference is confident, generate directly and explain the basis for the inference; if the inference is uncertain, ask the user
User did not provide a description	Infer the most conservative description from the repository name and file structure, label it TBD, and do not fabricate
Before writing the file	By default write directly to README.md; if the repository already has a README, first warn that it will be overwritten and wait for confirmation

Default skeleton

# <项目名> [徽章（可选）]

<一句话说明>（必须）

## <核心入口 / 如何使用>（必须）

## License（必须）

The remaining sections are kept or not according to the value threshold.

Section value threshold

Decision principle: if a section cannot provide new decision information that does not exist in other sections, delete it or merge it into the nearest section.

Section	Type	Retention condition
Title + one-sentence description	Required	Keep unconditionally
Core entry points / How to use	Required	Keep unconditionally
License	Required	Keep unconditionally, including valid links
Feature list	Optional	When there are ≥2 non-obvious features and a one-sentence description cannot cover them
Installation	Optional (code type only)	When installation steps exceed pip install / npm install Single-line case
Quick start	Optional (code type only)	When there is a minimal runnable example that can be copied and pasted
Configuration/Usage Instructions	Optional	When there are non-obvious configuration items or parameters
Contribution Guide	Optional	When the contribution process has special requirements (PR standards, testing thresholds, etc.)
Author/Acknowledgements	Optional	When there is a clear attribution requirement

Omission Rules：

• doc Type repository: by default, do not generate installation and quick start sections; use a navigation index instead
• If any section is empty or contains only TBD → omit it (do not keep empty shell sections)
• If the contribution/author section can only contain generic boilerplate → omit it

Project Type Triage

code type(code/application repository)

Identification signals: presence of package.json / pyproject.toml / Makefile / Dockerfile / main program entry file.

Output focus: installation path, minimal runnable example, key API entry points.

# MyApp

单行说明项目做什么。

## Installation

\```bash
npm install myapp
\```

## Usage

\```bash
myapp --input file.csv --output result.json
\```

## License

MIT — see [LICENSE](LICENSE)

doc type(documentation/specification repository)

Identification signals: no executable entry point, main content is .md / .yaml / .json spec file, presence of INDEX.md / skills/INDEX.md。

Output focus: navigation index, reading path. Installation/quick start omitted by default.

# MySpec

单行说明规范/文档的范围和受众。

## 如何使用

- 从 [INDEX.md](INDEX.md) 开始
- 核心定义见 [docs/architecture/terminology.md](docs/architecture/terminology.md)
- 贡献规范见 [CONTRIBUTING.md](CONTRIBUTING.md)

## License

MIT — see [LICENSE](LICENSE)

Anti-Fluff Rules

The following content must not appear:

Prohibited Pattern	Example	Fix Direction
Stacking of vague adjectives	"reusable, governable, implementable"	Delete or replace with specific behavior: "register via skills/INDEX.md and self-check together with changes"
Value proposition without a subject	"improve engineering standards"	Delete or make specific: "maintain consistency between skills/INDEX.md and documentation links"
Repeating known information	Restating the content of the description section in the installation section	Merge or delete
Placeholder boilerplate	"Welcome contributions! Please submit a PR."	If there is no specific process description, omit the contribution section
Inventing commands or features	Writing docker-compose.yml when there is no docker compose up	Use TBD or omit

Every claim must be grounded in: specific file path / shell command / observable behavior / explicit constraint.

---

Input and Output

Input

Field	Required	Description
Project name	Required	Used for the title
One-sentence description	Required	Precisely explain what the project does
Project type	Recommended	code or doc; if not provided, infer from repository structure
License	Recommended	type + file path; if not provided, use TBD
Installation command	Optional	Only code used for type projects
Quick start example	Optional	Only code used by type projects
Core entry points list	Optional	Key files, directories, URLs

Fields not provided: use TBD as a placeholder or omit the section entirely; fabrication is prohibited.

Output

• README.md written to the project root directory
• The number of sections is determined by the value threshold, with a minimum of 3 sections (title + description, entry points/usage, license)
• No broken links, internal paths preferred

---

Restrictions

• No fabrication: all commands, paths, and features must come from the input or the repository's actual content; when missing, use TBD or omit
• No broken links: external links may only be used when highly stable (e.g. shields.io); internal paths must be verifiably present
• No empty-shell sections: each retained section must contain at least one piece of actionable information; if the content is empty, omit it
• Hard restrictions for doc type: doc type repositories do not generate an installation/quick start section, and if the user requests one, the reason should still be explained
• The license may not be omitted: always include a License section; when not provided, use TBD rather than omitting it
• An existing README must be confirmed: if the target directory already has README.md, the user must be prompted before overwriting

---

Self-check

After generating the README, verify item by item:

• 30-second test: can an unfamiliar reader finish reading a one-sentence description and find the usage entry point within 30 seconds?
• No vague adjectives: adjectives such as "reusable", "governable", and "professional" that are not supported by specific behavior do not appear
• No fabricated content: all commands, paths, and features come from the input or the repository's actual content
• No broken links: internal paths have been verified to exist; external links are used only when highly stable
• No empty-shell sections: each retained section contains at least one piece of actionable information
• The license section exists: includes the license type + a valid link (or TBD)
• Project type matches: doc type has no installation/quick start section; code type installation commands are actually executable
• Value threshold passed: each retained section can provide new decision information not contained in other sections

Acceptance criteria: all 8 items above pass, or there is a clear exemption reason for each item that does not pass.

---

Examples

Example 1: Code repository (concise output)

Input: name img-crush, description "batch image compression", installation pip install img-crush, usage img-crush ./images, license MIT.

Output：

# img-crush

批量压缩图片，支持 WebP / PNG / JPEG 格式。

## Installation

\```bash
pip install img-crush
\```

## Usage

\```bash
img-crush ./images          # 原地压缩
img-crush ./images -o out/  # 输出到指定目录
\```

## License

MIT — see [LICENSE](LICENSE)

---

Example 2: Documentation/specification repository (doc type)

Input: name ai-cortex, description "agent-first skill library", license MIT, core entry points skills/INDEX.md、AGENTS.md。

Output：

# ai-cortex

面向软件交付和项目治理的 agent-first 技能库。

## 如何使用

- 从 [AGENTS.md](AGENTS.md) 了解代理行为契约
- 浏览 [skills/INDEX.md](skills/INDEX.md) 查找可用技能
- 核心术语定义见 [docs/architecture/terminology.md](docs/architecture/terminology.md)

## License

MIT — see [LICENSE](LICENSE)

---

Example 3: Edge case — a legacy project with very little information

Input: name legacy-auth, no description, no feature list, installation and environment unknown.

Handling：

• One-sentence description: infer the most conservative description from the name, annotate TBD
• Installation section: omitted (no executable commands)
• Features section: omitted (no content)
• License:TBD(not omitted, content pending)

Output：

# legacy-auth

认证服务（详情待补充）。

## 如何使用

TBD — 请参阅项目内部文档。

## License

TBD

---

Example 4: Failure case—a doc-type repository generated an installation section

Symptom: generated a ## Installation section for a documentation-spec repository, with content npm install or empty TBD.

Root cause: project type was not identified, and the code template was applied.

Fix: check the repository structure → if there is no executable entry point, classify it as doc type → delete the installation/quick start section and replace it with a navigation index.