flawless

Flawless

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.

Installation

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.

Automatic Installation

Use one of the automatic installation paths supported by your agent host.

Claude Code Marketplace

Add the GitHub-backed marketplace, install the plugin, then reload plugins:

/plugin marketplace add zhoux77899/flawless
/plugin install flawless@zhoux77899-flawless

Codex Marketplace

Add the marketplace source, then open the plugin browser and install flawless:

codex plugin marketplace add zhoux77899/flawless
codex

npx Installer

Install Flawless into the current project:

npx codex-marketplace add zhoux77899/flawless --plugin --project # inferred from Codex Marketplace CLI

Or install it globally for Codex:

npx codex-marketplace add zhoux77899/flawless --plugin --global # inferred from Codex Marketplace CLI

The 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/".

Manual Installation

Clone this repository into the local plugin directory used by your agent host:

git clone https://github.com/zhoux77899/flawless.git <plugin-directory>/flawless

Then load or refresh local plugins in the host. The host should read the matching plugin manifest and discover skills from ./skills/.

Available Skills

readme-writing

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.

How It Works

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.md and 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.

Supported Agents

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.

Repository Structure

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

Development and Validation

Run the tests in the tests/ directory:

python -m unittest discover -s tests # inferred from tests directory

License

The plugin manifests declare this project as MIT licensed.