existential-birds/beagle / plugins/beagle-docs/skills/review-ai-writing
review-ai-writing
VerifiedDetect AI-generated writing patterns in developer text — docs, docstrings, commit messages, PR descriptions, and code comments. Use when reviewing any text artifact for authenticity and clarity, or when the user mentions ai writing, ai-generated or robotic writing, text that sounds like AI or ChatGPT, or writing quality. Builds on the docs-style core writing principles.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.1 KB |
| references/code-docs-patterns.md | markdown | 10.3 KB |
| references/communication-patterns.md | markdown | 4.1 KB |
| references/content-patterns.md | markdown | 5.9 KB |
| references/filler-patterns.md | markdown | 5.2 KB |
| references/formatting-patterns.md | markdown | 5.2 KB |
| references/vocabulary-patterns.md | markdown | 7.0 KB |
references/formatting-patterns.md
View on GitHub# Formatting Patterns
Detection criteria for AI-generated formatting habits in developer docs, commit messages, PR descriptions, and code comments.
## 1. Boldface Overuse
### What to Look For
AI tends to bold every key term, creating visual noise that dilutes emphasis. In developer documentation, bold should be reserved for UI element labels, key terms on first introduction, and warnings or critical notes.
### Detection Patterns
**Bolding common terms throughout a paragraph**:
```markdown
<!-- BAD - Every term is bold, nothing stands out -->
The **server** reads the **configuration file** on **startup** and
initializes the **database connection pool**. If the **connection**
fails, the **retry logic** kicks in with **exponential backoff**.
<!-- GOOD - Bold only on first introduction of a key concept -->
The server reads the configuration file on startup and initializes
the database connection pool. If the connection fails, the retry
logic kicks in with **exponential backoff** (see Retry Strategies).
```
**Bolding obvious terms in lists**:
```markdown
<!-- BAD - Bold on every list label adds nothing -->
- **Port**: 8080
- **Host**: localhost
- **Protocol**: HTTP
<!-- GOOD - Plain text when the structure already provides emphasis -->
- Port: 8080
- Host: localhost
- Protocol: HTTP
```
**Bolding in commit messages or PR descriptions**:
```markdown
<!-- BAD -->
Fix **race condition** in **connection pool** when **timeout** expires
<!-- GOOD -->
Fix race condition in connection pool when timeout expires
```
### fix_safety
Safe. Removing unnecessary bold formatting does not change meaning.
---
## 2. Emoji Decoration
### What to Look For
Gratuitous emoji in technical writing where plain text is clearer. Common in AI-generated changelogs, PR descriptions, commit messages, and documentation headings. Emoji should only appear when they serve a functional purpose (e.g., status indicators in a table).
### Detection Patterns
**Emoji in changelog or release notes**:
```markdown
<!-- BAD - Emoji adds no information -->
## What's New
- :rocket: Added streaming support for large responses
- :bug: Fixed null pointer in auth middleware
- :sparkles: New CLI flag for verbose output
- :wastebasket: Removed deprecated v1 endpoints
<!-- GOOD - Let the content speak -->
## What's New
- Added streaming support for large responses
- Fixed null pointer in auth middleware
- New CLI flag for verbose output
- Removed deprecated v1 endpoints
```
**Emoji in headings or section titles**:
```markdown
<!-- BAD -->
## :wrench: Configuration
## :book: API Reference
## :warning: Known Issues
<!-- GOOD -->
## Configuration
## API Reference
## Known Issues
```
**Emoji as bullet markers or checkmarks**:
```markdown
<!-- BAD - Emoji replacing standard list markers -->
:white_check_mark: Unit tests passing
:white_check_mark: Integration tests passing
:white_check_mark: Linting clean
<!-- GOOD - Use standard markdown -->
- [x] Unit tests passing
- [x] Integration tests passing
- [x] Linting clean
```
### fix_safety
Safe. Removing decorative emoji does not change technical meaning.
---
## 3. Heading Restatement
### What to Look For
The first sentence after a heading restates the heading in slightly different words. This is filler that delays the reader from reaching useful content. The heading already names the topic; the body should immediately provide substance.
### Detection Patterns
**Restating the heading as a definition**:
```markdown
<!-- BAD - First sentence is the heading in sentence form -->
## Error Handling
Error handling is an important aspect of building robust applications.
When an error occurs...
<!-- GOOD - Jump straight into substance -->
## Error Handling
All functions in this module return `(result, error)` tuples. Check
the error value before using the result.
```
**Restating with "This section describes..."**:
```markdown
<!-- BAD - Meta-commentary about the section itself -->
## Authentication
This section describes how authentication works in the system.
The authentication flow begins when...
<!-- GOOD - Start with what the reader needs -->
## Authentication
Clients authenticate by sending a Bearer token in the `Authorization`
header. Tokens are issued by the `/auth/token` endpoint and expire
after 24 hours.
```
**Restating in code comments**:
```python
# BAD - Comment restates the function name
def calculate_retry_delay(attempt: int) -> float:
"""Calculate the retry delay.
Calculates the delay before retrying a failed request.
"""
return min(2 ** attempt, MAX_DELAY)
# GOOD - Comment adds information the name doesn't convey
def calculate_retry_delay(attempt: int) -> float:
"""Exponential backoff capped at MAX_DELAY seconds.
Uses jitter to prevent thundering herd on service recovery.
"""
return min(2 ** attempt, MAX_DELAY)
```
### fix_safety
Needs review. The restated sentence sometimes contains useful qualifiers or scope limitations mixed in with the filler. Verify that no meaningful context is lost before removing.
---
## Review Questions
1. Does every bold term in this paragraph genuinely need emphasis, or would one or two suffice?
2. Would this changelog entry lose any meaning without the emoji?
3. Does the first sentence after this heading tell the reader something the heading did not?
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 |