Flawless is a cross-agent plugin skills repository for improving repository and code quality with reusable AI agent skills. It packages shared skill instructions in the open SKILL.md format and adds host-specific plugin metadata for Claude Code and Codex.
The repository currently centers on readme-writing, a skill that helps agents create README files from repository facts instead of generic templates. The same pattern is intended for future skills that raise documentation, repository maintenance, and code review quality across compatible agent hosts.
Flawless can be installed automatically through a host marketplace or an npx-based plugin installer. It can also be installed manually by cloning this repository into the local plugin directory used by your host.
Use one of the automatic installation paths supported by your agent host.
Add the GitHub-backed marketplace, install the plugin, then reload plugins:
/plugin marketplace add zhoux77899/flawless
/plugin install flawless@zhoux77899-flawless
Add the marketplace source, then open the plugin browser and install flawless:
codex plugin marketplace add zhoux77899/flawless
codex
Install Flawless into the current project:
npx codex-marketplace add zhoux77899/flawless --plugin --project # inferred from Codex Marketplace CLIOr install it globally for Codex:
npx codex-marketplace add zhoux77899/flawless --plugin --global # inferred from Codex Marketplace CLIThe repository provides the plugin manifests that installers should discover:
- Claude Code:
.claude-plugin/plugin.json - Codex:
.codex-plugin/plugin.json
Both manifests declare the plugin name flawless and point the host at skills: "./skills/".
Clone this repository into the local plugin directory used by your agent host:
git clone https://github.com/zhoux77899/flawless.git <plugin-directory>/flawlessThen load or refresh local plugins in the host. The host should read the matching plugin manifest and discover skills from ./skills/.
Creates or improves repository README files using repository analysis, type-specific README patterns, and optional agent-facing guidance.
The skill is implemented in skills/readme-writing/SKILL.md. It includes:
- Standard-library Python scripts for repository analysis and README validation.
- Reference guides for libraries, CLIs, applications, AI/ML projects, infrastructure, documentation repositories, plugins, and security-oriented projects.
- Audience rules that decide whether agent-facing README content should be omitted, linked to a separate agent document, or included inline.
- Codex/OpenAI display metadata in
skills/readme-writing/agents/openai.yaml.
readme-writing starts by analyzing a target repository and producing a fact sheet. It maps the detected repository type to a matching README guide, loads only the relevant references, and drafts from observed project facts.
The skill intentionally separates portable behavior from host-specific metadata:
- Shared behavior lives in
SKILL.mdand files linked from it. - Claude Code plugin discovery lives in
.claude-plugin/plugin.json. - Codex plugin discovery and interface metadata live in
.codex-plugin/plugin.json. - Codex/OpenAI skill presentation metadata lives in
skills/readme-writing/agents/openai.yaml.
Flawless currently includes plugin manifests for:
- Claude Code
- Codex
Other compatible agents may be able to use the shared SKILL.md files directly, but this repository only declares first-class plugin metadata for the hosts listed above.
flawless/
├── .claude-plugin/
│ └── plugin.json
├── .codex-plugin/
│ └── plugin.json
├── skills/
│ └── readme-writing/
│ ├── SKILL.md
│ ├── agents/
│ │ └── openai.yaml
│ ├── references/
│ │ ├── audience-policy.md
│ │ ├── index.md
│ │ ├── repo-types/
│ │ └── research/
│ └── scripts/
│ ├── analyze_repo.py
│ └── validate_readme.py
├── tests/
│ └── test_readme_writing_scripts.py
└── README.md
Run the tests in the tests/ directory:
python -m unittest discover -s tests # inferred from tests directoryThe plugin manifests declare this project as MIT licensed.