existential-birds/beagle / plugins/beagle-docs/skills/humanize-beagle
humanize-beagle
VerifiedRewrite AI-generated developer text to sound human — fix inflated language, filler, tautological docs, and robotic tone. Use after review-ai-writing identifies issues.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.2 KB |
| references/developer-voice.md | markdown | 1.3 KB |
| references/fix-strategies.md | markdown | 7.2 KB |
| references/vocabulary-swaps.md | markdown | 2.5 KB |
SKILL.md
View on GitHub---
name: humanize-beagle
description: Rewrite AI-generated developer text to sound human — fix inflated language, filler, tautological docs, and robotic tone. Use after review-ai-writing identifies issues.
disable-model-invocation: true
user-invocable: true
---
# Humanize
Apply fixes from a previous [review-ai-writing](../review-ai-writing/SKILL.md) run with automatic safe/risky classification. Builds on the writing principles in [docs-style](../docs-style/SKILL.md).
## Usage
Invoke the **humanize-beagle** skill with optional flags: `humanize-beagle [--dry-run] [--all] [--category <name>]`.
**Flags:**
- `--dry-run` - Show what would be fixed without changing files
- `--all` - Fix entire codebase (runs review with --all first)
- `--category <name>` - Only fix specific category: `content|vocabulary|formatting|communication|filler|code_docs`
## Instructions
### Hard gates
Advance past destructive or evidence-bound steps only when each **PASS** is true (commands and artifacts—not “I checked mentally”):
1. **G1 — Safe to edit files** — **PASS:** `git status --porcelain` is empty, **or** `git stash push -u -m "beagle-docs: pre-humanize backup"` exits 0.
2. **G2 — Review input is real JSON with expected shape** — **PASS:** `.beagle/ai-writing-review.json` exists **and** the file parses as JSON with a `git_head` key and a `findings` value that is an array (possibly empty). Use the `jq -e` command in step 3, or the same checks with `json.load` in Python. If this fails, stop with a parse/validation error—do not apply fixes.
3. **G3 — References before rewrites** — **PASS:** For each finding you will edit, the `references/*.md` files required by step 4 for that category/type are read in this session before you change text.
4. **G4 — Per-file validation** — **PASS:** Every modified file passes the step 8 check for its type; otherwise run `git checkout -- "$file"` for that file and do not list it as OK in the summary.
5. **G5 — Delete review file only on full success** — **PASS:** Run `rm .beagle/ai-writing-review.json` only when G4 holds for all files you are keeping unchanged from validation failures (aligns with step 10).
### 1. Parse Arguments
Extract flags from `$ARGUMENTS`:
- `--dry-run` - Preview mode only
- `--all` - Full codebase scan
- `--category <name>` - Filter to specific category
### 2. Pre-flight Safety Checks
```bash
# Check for uncommitted changes
git status --porcelain
```
If working directory is dirty, warn:
```text
Warning: You have uncommitted changes. Creating a git stash before proceeding.
Run `git stash pop` to restore if needed.
```
Create stash if dirty:
```bash
git stash push -u -m "beagle-docs: pre-humanize backup"
```
**G1 PASS:** Either the working tree was already clean, or the stash command exited 0.
### 3. Load Review Results
Check for existing review file:
```bash
cat .beagle/ai-writing-review.json 2>/dev/null
```
**If file missing:**
- If `--all` flag: Invoke the **[review-ai-writing](../review-ai-writing/SKILL.md)** skill with `--all` first
- Otherwise: Fail with: "No review results found. Invoke the review-ai-writing skill first."
**If file exists, validate JSON and freshness (G2):**
```bash
# Required shape: parseable JSON with git_head and findings array (may be empty)
jq -e 'has("git_head") and ((.findings // []) | type == "array")' .beagle/ai-writing-review.json >/dev/null 2>&1 \
|| { echo "Invalid or incompatible ai-writing-review.json"; exit 1; }
# Get stored git HEAD from JSON
stored_head=$(jq -r '.git_head' .beagle/ai-writing-review.json)
current_head=$(git rev-parse HEAD)
if [ "$stored_head" != "$current_head" ]; then
echo "Warning: Review was run at commit $stored_head, but HEAD is now $current_head"
fi
```
If stale, prompt: "Review results are stale. Re-run review? (y/n)"
### 4. Load Reference Material
Read the appropriate reference files based on the findings being fixed:
- Read `references/vocabulary-swaps.md` when applying `ai_vocabulary_high` or `ai_vocabulary_low` fixes
- Read `references/fix-strategies.md` for strategy details and before/after examples for any category
- Read `references/developer-voice.md` for tone/register guidance when rewriting prose
Only load what you need — if fixing only vocabulary, skip the voice guide.
### 5. Filter Findings
If `--category` is set, filter findings to that category only.
Partition remaining findings by `fix_safety`:
**Safe Fixes** (auto-apply):
- `chat_leak` - Delete conversational artifacts
- `cutoff_disclaimer` - Delete knowledge cutoff references
- `filler_phrase` - Delete filler phrases
- `heading_restatement` - Delete restating first sentence
- `emoji_decoration` - Remove emoji from technical text
- `boldface_overuse` - Remove excessive bold formatting
- `ai_vocabulary_high` - Swap high-signal AI words
- `narrating_obvious` - Delete obvious code comments
- `synthetic_opener` - Delete "In today's..." openers
- `sycophantic_tone` - Delete or neutralize praise
- `vague_authority` - Delete unattributed claims
- `excessive_hedging` - Remove qualifiers
- `generic_conclusion` - Delete summary padding
- `copula_avoidance` - Use "is/are" naturally
- `rhetorical_device` - Delete rhetorical questions
- `em_dash_overuse` - Replace formulaic em dashes with commas, parentheses, or colons
- `thematic_break` - Remove horizontal rules before headings
- `title_case_heading` - Convert AI title-case headings to sentence case
- `curly_quotes` - Normalize curly quotes/apostrophes to straight
- `negative_parallelism` - Delete "Not just X, but also Y" filler constructions
- `challenges_and_prospects` - Delete "Despite its... faces challenges..." formulaic wrappers
**Needs Review Fixes** (require confirmation):
- `promotional_language` - Rewrite with specifics
- `formulaic_structure` - Restructure sections
- `synonym_cycling` - Pick consistent term
- `commit_inflation` - Rewrite commit scope
- `tautological_docstring` - Rewrite or delete docstring
- `exhaustive_enumeration` - Trim parameter docs
- `this_noun_verbs` - Rewrite docstring voice
- `ai_vocabulary_low` - Reduce cluster density
- `apologetic_error` - Rewrite error message
- `rule_of_three` - Simplify three-item lists used as filler comprehensiveness
- `inline_header_list` - Restructure boldfaced inline-header vertical lists
- `unnecessary_table` - Convert small tables to prose
- `regression_to_mean` - Restore specific facts replaced by vague praise
### 6. Apply Safe Fixes
If `--dry-run`:
```markdown
## Safe Fixes (would apply automatically)
| # | File | Line | Type | Action |
|---|------|------|------|--------|
| 1 | README.md | 3 | synthetic_opener | Delete "In today's rapidly evolving..." |
| 2 | src/auth.py | 15 | narrating_obvious | Delete "# Check if user exists" |
| 3 | README.md | 42 | ai_vocabulary_high | Replace "utilize" with "use" |
...
```
Otherwise, apply fixes grouped by file to minimize file I/O:
1. Sort findings by file, then by line number (descending, to avoid offset drift)
2. For each file, apply all safe fixes in reverse line order
3. For git artifacts (`git:commit:*`, `git:pr:*`), skip — these can't be auto-fixed. Report them for manual attention.
### 7. Handle Needs Review Fixes
If `--dry-run`, list them:
```markdown
## Needs Review Fixes (would prompt interactively)
| # | File | Line | Type | Original | Suggested |
|---|------|------|------|----------|-----------|
| 4 | README.md | 8 | promotional_language | "powerful, enterprise-grade solution" | "authentication library" |
...
```
Otherwise, for each fix, prompt interactively:
```text
[README.md:8] Promotional language: "powerful, enterprise-grade solution"
Suggested: "authentication library"
(y)es / (n)o / (e)dit / (s)kip all:
```
Track user choices:
- `y` - Apply this fix as suggested
- `n` - Skip this fix
- `e` - User provides custom replacement
- `s` - Skip all remaining interactive fixes
### 8. Validate Results
For each modified markdown file, verify basic validity:
```bash
# Check for broken markdown (unclosed code blocks, broken links)
# Simple check: matching ``` pairs
grep -c '```' "$file" | awk '{print ($1 % 2 == 0) ? "OK" : "WARNING: odd number of code fences"}'
```
For modified source files, check syntax is still valid:
**Python:**
```bash
python3 -c "import ast; ast.parse(open('$file').read())"
```
**TypeScript/JavaScript:**
```bash
npx -y acorn --ecma2020 "$file" > /dev/null 2>&1
```
If validation fails for any file, revert that file:
```bash
git checkout -- "$file"
echo "Reverted $file due to validation failure"
```
### 9. Report Results
```markdown
## Humanize Summary
### Applied Fixes
- [x] README.md:3 - Deleted synthetic opener
- [x] README.md:42 - Replaced "utilize" with "use"
- [x] src/auth.py:15 - Deleted obvious comment
### Interactive Fixes
- [x] README.md:8 - Rewrote promotional language (user approved)
- [ ] docs/guide.md:22 - Skipped by user
### Skipped (Git Artifacts)
- [ ] git:commit:abc1234 - Chat leak in commit message (amend manually)
### Validation
- README.md: OK
- src/auth.py: OK
### Diff Summary
```
```bash
git diff --stat
```
### 10. Cleanup
On successful completion (all validations pass):
```bash
rm .beagle/ai-writing-review.json
```
If any validation fails, keep the file and report:
```text
Review file preserved at .beagle/ai-writing-review.json
Fix issues and re-run, or restore with: git stash pop
```
## Core Principles
1. **Delete first, rewrite second.** Most AI patterns are padding. Removing them improves the text.
2. **Use simple words.** Replace "utilize" with "use", "facilitate" with "help", "implement" with "add".
3. **Keep sentences short.** Break compound sentences. One idea per sentence.
4. **Preserve meaning.** Never change what the text says, only how it says it.
5. **Match the register.** Commit messages are terse. READMEs are conversational. API docs are precise. Read `references/developer-voice.md` for the full register guide.
6. **Don't overcorrect.** A slightly formal sentence is fine. Only fix patterns that read as obviously AI-generated.
7. **Understand regression to the mean.** LLMs produce the most statistically likely output. Specific, unusual facts get replaced with generic, positive descriptions. When humanizing, restore specificity — replace vague praise with concrete details.
8. **Score density, not individual words.** AI vocabulary words co-occur. One or two may be coincidental; a cluster of 3+ is a strong AI tell.
## Example
Invoke the **humanize-beagle** skill with flags:
- `--dry-run` — preview all fixes without applying
- `--category vocabulary` — fix only vocabulary issues
- `--all` — full codebase scan and fix
- `--category filler --dry-run` — preview filler fixes only
## Rules
- Always load reference material before applying fixes (step 4); satisfy **G3** per finding
- Never modify files without a clean working tree or a successful stash (**G1**)
- Apply safe fixes in reverse line order to avoid offset drift
- Never auto-fix git artifacts (commits, PRs) — report them for manual action
- Validate every modified file before considering it done (**G4**)
- Revert files that fail validation
- Do not present the step 9 summary as “complete” until step 8 validation has passed for every file you are keeping
- Remove `.beagle/ai-writing-review.json` only after full success (**G5**); if validation failed partway, keep the file and follow step 10
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |