# ai-writing-skill
A Claude Code skill that writes articles, blog posts, and tutorials that read like a human wrote them — not a language model.
Built by [@ContractorKeith](https://github.com/ContractorKeith) | [contractorkeith.com](https://contractorkeith.com)
## What this does
This skill encodes **dozens of known AI writing tells** — catalogued by Wikipedia editors, computational linguists, and AI detection researchers — as negative constraints that Claude actively avoids. The result is prose that is specific, grounded, and stylistically human.
It was built using an **autoresearch optimization loop** (inspired by [Karpathy's autoresearch](https://github.com/karpathy/autoresearch)) to iteratively test and improve the skill instructions against binary evaluation criteria until the output consistently passed at 90%+.
## What it catches
The skill addresses AI writing patterns across five categories:
- **Vocabulary** — Avoids the ~40 most statistically overused AI words (delve, foster, pivotal, tapestry, etc.)
- **Structure** — No "Challenges and Future Outlook" endings, no dictionary-entry openings, no formulaic parallelisms
- **Grammar** — Prevents copula avoidance ("serves as" replacing "is"), trailing participle analysis, rule-of-three defaults
- **Formatting** — Sentence-case headings, limited em dashes, no emoji decoration, no unnecessary tables
- **Content quality** — Requires concrete specificity (names, numbers, dates), first-person voice, and calibrated hedging
The anti-pattern reference is derived from [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), cross-referenced with research from Kobak et al. (2025), Geng & Trotta (2025), Juzek & Ward (2026), and Merrill et al. (2025).
## Install
### Claude Code (CLI)
```bash
claude skill install ContractorKeith/ai-writing-skill
```
### Manual install
Copy the `ai-writing-skill/` folder into your skills directory:
```bash
# Personal skills (available in all projects)
cp -r ai-writing-skill/ ~/.claude/skills/ai-writing/
# Project-level skills (shared with collaborators)
cp -r ai-writing-skill/ .claude/skills/ai-writing/
```
## Usage
Once installed, the skill triggers automatically when you ask Claude Code to write articles, blog posts, tutorials, or long-form content. You can also invoke it directly:
```
/ai-writing Write a blog post about getting started with fence estimating
```
Or in natural language:
```
Write me an article about why 2-door Jeeps are underrated for overlanding.
Make it sound like a real person wrote it, not AI.
```
## Repo structure
```
ai-writing-skill/
├── SKILL.md # The skill (install this)
├── references/
│ └── ai-writing-antipatterns.md # Full anti-pattern catalogue
├── evals/
│ └── eval-criteria.md # Binary evaluation criteria
├── tests/
│ └── test-prompts.json # Test cases for optimization
├── program.md # Autoresearch loop instructions
├── results.tsv # Optimization run log (after running)
└── README.md
```
## Optimize it yourself
This skill was designed to be improved using the autoresearch methodology. To run the optimization loop:
1. Clone this repo
2. Open Claude Code in the repo directory
3. Tell Claude: `Read program.md and use the autoresearch convention to optimize SKILL.md. The eval criteria are in evals/eval-criteria.md and the test prompts are in tests/test-prompts.json. Run autonomously.`
4. Walk away. Check back in an hour.
The agent will establish a baseline, iterate on the SKILL.md, and log every experiment to `results.tsv`. It keeps only improvements and discards regressions via git reset.
**Customize the test prompts:** The included test prompts in `tests/test-prompts.json` are general-purpose. For best results, replace or supplement them with prompts specific to your domain, audience, and writing style. The autoresearch loop works best when the test prompts match the kind of articles you actually write.
See `program.md` for the full loop specification.
## Eval criteria (summary)
The skill is evaluated on 6 binary (yes/no) assertions:
1. **No banned vocabulary** — Zero AI-overused words in figurative sense
2. **No formulaic structure** — No "Challenges/Future Outlook" or dictionary openings
3. **Concrete specificity** — At least 3 named people, numbers, dates, or anecdotes
4. **No trailing participle analysis** — No "...highlighting the importance of X" endings
5. **Sentence variety** — Mix of short punches, long complex sentences, and fragments
6. **Sentence-case headings** — No Title Case unless proper nouns
Target: 27/30 (90%) across 5 outputs x 6 criteria.
## Source material
This skill draws from:
- [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) — The authoritative catalogue of AI writing patterns, maintained by Wikipedia editors
- [Karpathy's autoresearch](https://github.com/karpathy/autoresearch) — The autonomous optimization methodology adapted for skill improvement
- [Stop Fixing Your Claude Skills (YouTube)](https://www.youtube.com/watch?v=qKU-e0x2EmE) — Practical walkthrough of applying autoresearch to Claude Code skills
## How it was built
Read the full writeup: [How I built a self-improving AI writing skill](https://contractorkeith.com/blog/ai-writing-skill) *(link pending)*
Short version: I took the Wikipedia "Signs of AI Writing" article (1,600 lines of documented AI tells with real examples), distilled it into actionable writing rules, packaged it as a Claude Code skill, and then used Karpathy's autoresearch loop to autonomously test and improve the skill until it consistently scored 90%+ on binary evaluations.
## Contributing
PRs welcome. If you've found AI writing patterns not covered here, or if you've run the autoresearch loop and found improvements, open a PR with your `results.tsv` diff and the improved `SKILL.md`.
## License
MIT