Write README Skill

A compact cross-agent skill for generating GitHub-ready project READMEs from the files already in a repository.

What It Does

• Inspects project structure, manifests, docs, examples, tests, and repository health files before writing.
• Drafts concise README.md files with install, quick-start, usage, development, contribution, security, and license sections when supported by project evidence.
• Reviews README/open-source readiness without inventing badges, commands, maintainers, compatibility promises, or license terms.
• Creates multilingual README variants when requested, while defaulting to English.
• Handles agent-skill projects by checking SKILL.md, agents/openai.yaml, and duplicated distribution layouts.

Supported Agent Targets

This repository ships the same write-readme skill in several common layouts:

Target	Path
OpenAI Codex	write-readme/
Generic Agent Skills repositories	skills/write-readme/
VS Code / GitHub Copilot Agent mode	.agents/skills/write-readme/
Claude Code project skill	.claude/skills/write-readme/
Other Agent Skills-compatible coding agents	Use skills/write-readme/ as the portable source and install through that client's skill import path

The skill content is intentionally duplicated so each client can discover the layout it expects without extra build steps. Run the validation script after any skill change to keep those copies aligned.

Install

For Codex, copy the skill folder into your Codex skills directory:

Copy-Item -Recurse .\write-readme "$env:USERPROFILE\.codex\skills\write-readme"

Or on macOS/Linux:

cp -R ./write-readme "${CODEX_HOME:-$HOME/.codex}/skills/write-readme"

For Claude Code, keep .claude/skills/write-readme/ in the project or copy it to ~/.claude/skills/write-readme/.

For VS Code/GitHub Copilot Agent Skills, keep .agents/skills/write-readme/ in the project root.

Use

Use $write-readme to inspect this project and draft a clear GitHub README.

For multiple languages:

Use $write-readme to create README.md and README.zh-TW.md for this project.

Validate

Run the repository validation script before publishing or opening a pull request:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/validate.ps1

The script checks:

• Required root project files.
• Each distributed SKILL.md file.
• Each distributed agents/openai.yaml file.
• Synchronization across the four skill copies.
• Open-source readiness checks such as MIT license presence.

GitHub Actions also runs the same validation through .github/workflows/validate.yml.

Project Structure

• write-readme/ - Codex-oriented skill package.
• skills/write-readme/ - Portable Agent Skills layout.
• .agents/skills/write-readme/ - VS Code/GitHub Copilot Agent Skills layout.
• .claude/skills/write-readme/ - Claude Code project-skill layout.
• scripts/validate.ps1 - Local validation for structure and duplicated content.
• .github/workflows/validate.yml - CI validation.
• .github/ISSUE_TEMPLATE/ - GitHub issue templates.
• .github/PULL_REQUEST_TEMPLATE.md - GitHub pull request template.
• CONTRIBUTING.md - Contribution workflow and synchronization expectations.
• SECURITY.md - Security reporting policy.
• LICENSE - MIT license text.

Open-Source Readiness

In place:

• Root README with install, usage, validation, contribution, security, and structure details.
• CONTRIBUTING.md and SECURITY.md.
• MIT LICENSE.
• .gitignore.
• CI workflow for structural validation.
• Issue and pull request templates.
• Synchronized skill copies with agents/openai.yaml metadata.

Before publishing as open source:

• Initialize or restore Git metadata before pushing from this working copy.
• Set the Git remote for the public repository.

Design Notes

This project follows the Agent Skills format: a skill is a directory with SKILL.md, YAML frontmatter, Markdown instructions, and optional scripts/, references/, and assets/ resources. The main skill file stays small so it can be loaded without spending unnecessary context.

References considered while shaping this project:

• Agent Skills specification
• Agent Skills quickstart
• Claude Code skills documentation
• Anthropic skills repository
• GitHub Docs: About READMEs
• GitHub Docs: Licensing a repository
• GitHub Docs: Contributor guidelines
• GitHub Docs: Security policy

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

This project is licensed under the MIT License. See LICENSE.