README.md

# Natural writing

Natural writing is a portable Agent Skill for clear, direct prose without formulaic AI habits. It helps an agent preserve facts and the author's voice while choosing words, structure, and detail for the reader.

The skill adapts the durable guidance in the [Google Developer Documentation Style Guide](https://developers.google.com/style) for broader writing tasks. Its instructions are self-contained and do not depend on the live guide at runtime.

## See the difference

Before:

> Absolutely! This powerful and robust feature is not just a cache—it's a game-changing data acceleration layer. It is important to note that cached responses can potentially be returned much more quickly in many situations. In conclusion, the cache can improve speed by returning a stored response instead of requesting the same data again.

After:

> The cache can improve response times by returning a stored response instead of requesting the same data again.

The revision keeps the mechanism and the qualified performance claim. It removes the greeting, hype, throat-clearing, and repetition.

## What it does

- Starts with the answer, outcome, recommendation, or important condition.
- Makes actors, actions, requirements, and uncertainty explicit.
- Removes canned praise, repeated conclusions, fake quotations, and unsupported hype.
- Uses headings, lists, and tables only when they help the reader.
- Preserves facts, evidence, code, quotations, legal language, terminology, and intentional voice.
- Adjusts explanation depth to the audience instead of defaulting to a lecture.

This is a house style, not a controlled language. Technical precision, humor, regional style, literary choices, and the writer's own voice can take priority.

## Install it

The quickest route for most clients is the community [`skills`](https://github.com/vercel-labs/skills) installer:

```text
npx -y skills@latest add anotb/natural-writing -g
```

You can also install the package through a client directly.

### ChatGPT

If Skills are enabled for your account or workspace, download the portable skill ZIP from the [latest release](https://github.com/anotb/natural-writing/releases/latest). In ChatGPT, open **Plugins**, select **Skills**, then choose **Create > Upload from your computer**. Personal skills do not sync between the desktop app and web/mobile. If you use both, upload the ZIP once in each.

### Claude Code

Add the repository as a marketplace, then install the plugin:

```text
claude plugin marketplace add anotb/natural-writing
claude plugin install natural-writing@natural-writing
```

### Gemini CLI

Install the repository as an extension:

```text
gemini extensions install https://github.com/anotb/natural-writing
```

### Manual installation

The repository is available in two forms:

- The repository root is an [OpenAI plugin](https://learn.chatgpt.com/docs/build-plugins) for ChatGPT and Codex. Its manifest is [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json).
- [`skills/natural-writing`](skills/natural-writing) is the portable skill for clients that support the [Agent Skills standard](https://agentskills.io/specification).

For a standalone installation, copy the portable skill directory to the location used by your client:

| Client | Skill location |
|---|---|
| Codex | `$HOME/.agents/skills/natural-writing` |
| Claude Code | `$HOME/.claude/skills/natural-writing` |
| Gemini CLI | `$HOME/.agents/skills/natural-writing` or `$HOME/.gemini/skills/natural-writing` |

Gemini CLI can also link a local checkout:

```text
gemini skills link ./skills/natural-writing
```

## Use it

In ChatGPT:

```text
Use the natural-writing skill to edit this. Preserve my dry tone and every factual claim.
```

In Codex:

```text
Use $natural-writing to edit this. Preserve my dry tone and every factual claim.
```

In Claude Code:

```text
/natural-writing:natural-writing Rewrite this clearly without losing the technical detail.
```

In Gemini CLI or another compatible client:

```text
Use the natural-writing skill to turn these notes into a migration guide for an experienced platform engineer.
```

The OpenAI version runs only when you name it, so it does not take over code-only, machine-readable, exact-text, or literary tasks.

## Use it in project instructions

This repository does not create or modify `AGENTS.md`. To apply the skill to a project by default, add one short instruction:

```markdown
For human-facing prose, use the `natural-writing` skill. Preserve established project terminology and intentional author voice.
```

## What's inside

- [`SKILL.md`](skills/natural-writing/SKILL.md) contains the core writing guidance.
- [`technical-writing.md`](skills/natural-writing/references/technical-writing.md) covers documentation, procedures, code, interfaces, links, and accessibility.
- [`editing-patterns.md`](skills/natural-writing/references/editing-patterns.md) covers common repairs without turning them into banned-word rules.
- [`sources.md`](skills/natural-writing/references/sources.md) records the source material and changes made in this adaptation.

## License and attribution

The project is available under [CC BY 4.0](LICENSE.md). Portions are modifications based on work [created and shared by Google](https://developers.google.com/style) under that license. See [`NOTICE.md`](skills/natural-writing/NOTICE.md) for attribution and the independent-project disclaimer.