human-voice

Human Voice Skill

Detect, prevent, and correct AI-generated writing patterns to ensure authentic, professional human voice in all content.

Purpose

Ensure all published content reads as authentic human writing through:

1. Detecting AI-telltale characters and patterns
2. Identifying language-level AI indicators
3. Correcting structural and stylistic issues
4. Guiding content creation with human voice principles

Multi-Tier Analysis Framework

Tier 1: Character-Level Patterns (Automated)

Run automated character detection first. These patterns are strong AI indicators:

• Em dashes, en dashes, smart quotes
• Horizontal ellipsis, bullet characters
• Emojis and special Unicode characters

Execute validation:

node ${CLAUDE_PLUGIN_ROOT}/skills/human-voice/scripts/validate-character-restrictions.js <directory>

Auto-fix detected issues:

node ${CLAUDE_PLUGIN_ROOT}/skills/human-voice/scripts/fix-character-restrictions.js <directory>

For complete character patterns table, see references/character-patterns.md.

Tier 2: Language-Level Patterns (Manual Review)

Search for AI buzzwords and hedging phrases:

grep -rn -i -E "delve|realm|pivotal|harness|revolutionize|seamlessly" <directory>
grep -rn -i -E "it's worth noting|generally speaking|at the end of the day" <directory>

Key categories to check:

• Hedging phrases: "It's worth noting", "Generally speaking", "Arguably"
• AI buzzwords: delve, realm, pivotal, harness, revolutionize, seamlessly
• Filler phrases: "In order to", "Due to the fact that", "At this point in time"
• Excessive transitions: Furthermore, Moreover, Additionally, Consequently

For complete language patterns tables, see references/language-patterns.md.

Tier 3: Structural Patterns

Review content for these AI structural patterns:

• List addiction: AI formats everything as bullet lists when prose works better
• Rule of three overuse: AI over-applies rhetorical threes, making content predictable
• "From X to Y" construction: "From beginners to experts", "From setup to deployment"
• Monotonous sentence structure: Similar length and structure throughout
• Over-balanced perspectives: "On one hand... on the other hand" for everything

For detailed structural patterns with examples, see references/structural-patterns.md.

Tier 4: Voice and Style

Check for voice issues:

• Passive voice overuse: "The feature was implemented" instead of "The team shipped"
• Generic analogies: "Like a Swiss Army knife for developers"
• Meta-commentary: "In this article, we will discuss..."
• Perfect grammar with shallow insights: Well-formed sentences that say nothing specific

For voice patterns and fixes, see references/voice-patterns.md.

Review Workflow

Step 1: Automated Character Check

# Run validation on content directories
node ${CLAUDE_PLUGIN_ROOT}/skills/human-voice/scripts/validate-character-restrictions.js _posts content _docs

# Auto-fix detected issues
node ${CLAUDE_PLUGIN_ROOT}/skills/human-voice/scripts/fix-character-restrictions.js _posts content _docs

Step 2: Language Pattern Scan

# AI buzzword search
grep -rn -i -E \
  "delve|realm|pivotal|harness|revolutionize|seamlessly|cutting-edge|game-chang" \
  _posts/ content/ _docs/

# Hedging and filler search
grep -rn -i \
  "it's worth noting\|generally speaking\|in order to\|due to the fact" \
  _posts/ content/ _docs/

Step 3: Structural Review

Apply the structural review checklist:

• Content doesn't over-rely on bullet lists
• Sentence lengths vary naturally
• No "rule of three" in every paragraph
• Perspectives aren't artificially balanced
• No "From X to Y" constructions
• Paragraphs vary in length

Step 4: Voice Review

Apply the voice review checklist:

• Opening hooks the reader (no meta-commentary)
• Specific examples replace generic claims
• Personal experience or perspective included
• Honest about tradeoffs and limitations
• Varied rhythm (short and long sentences)
• Active voice predominates
• Numbers and specifics over vague claims

Writing Guidelines

Human Voice Principles

1. Start with specifics: "I spent three weeks debugging this" not "Many developers face challenges"
2. Use active voice: "The team shipped" not "The feature was shipped"
3. Vary sentence length: Mix short punchy statements with longer explanatory ones
4. Be opinionated: "This tool is better" not "This tool may be considered preferable"
5. Include personal perspective: "In my experience" backed by actual experience
6. Acknowledge tradeoffs: Real tools have real limitations
7. Use concrete numbers: "50ms" not "extremely fast"
8. Write naturally: Read content aloud. Rewrite anything that sounds robotic
9. Be direct: Say what you mean without qualifiers
10. Show, don't tell: Examples over descriptions

AI Anti-Patterns to Avoid

1. Don't hedge everything: Pick a position
2. Don't use buzzwords: Say what you mean plainly
3. Don't list everything: Prose often works better
4. Don't balance artificially: Not every point needs a counterpoint
5. Don't meta-comment: Don't say "In this article, we will discuss"
6. Don't overuse transitions: Let ideas flow naturally
7. Don't genericize: "The tool" should be "swagger-php"
8. Don't claim without evidence: Show the improvement with numbers
9. Don't over-explain: Trust your reader
10. Don't use em dashes: Use colons, commas, or periods

Content Generation Constraints

When using AI for content creation, include these constraints in prompts:

MANDATORY CONSTRAINTS:
- No em dashes (use colons or commas)
- No smart quotes (use straight ASCII quotes)
- No emojis
- No buzzwords: delve, realm, pivotal, harness, revolutionize, seamlessly,
  cutting-edge, game-changing, robust, leverage, utilize, facilitate,
  synergy, paradigm, holistic, ecosystem, innovative, transformative
- No hedging: "it's worth noting", "generally speaking", "arguably"
- No filler: "in order to", "due to the fact", "at the end of the day"
- No meta-commentary: "In this article", "Let's dive in", "As mentioned"
- Use active voice
- Include specific examples with numbers
- Vary sentence length
- Be direct and opinionated
- Start with the content, not context-setting

Configuration

Configuration is stored in ~/.human-voice/config.json. Run /human-voice:voice-setup or edit directly. Example settings:

---
extensions:
  - .md
  - .mdx
content_directories:
  - _posts
  - content
  - _docs
  - docs
---

Additional Resources

Reference Files

For detailed patterns and examples:

• references/character-patterns.md - Complete character restriction table with Unicode codes
• references/language-patterns.md - Hedging phrases, buzzwords, filler, transitions
• references/structural-patterns.md - Structural patterns with code examples
• references/voice-patterns.md - Voice and style issues with fixes

Example Files

• examples/before-after.md - Before/after transformation examples

Scripts

• ${CLAUDE_PLUGIN_ROOT}/skills/human-voice/scripts/validate-character-restrictions.js - Detect character violations
• ${CLAUDE_PLUGIN_ROOT}/skills/human-voice/scripts/fix-character-restrictions.js - Auto-fix character issues

Memory Integration (Optional)

When Subcog MCP server is available, enhance the workflow with persistent memory:

Before Analysis

Recall existing voice decisions and patterns:

subcog_recall: query="voice patterns OR voice decisions", filter="ns:decisions ns:patterns", limit=5

This surfaces:

• Project-specific voice exceptions (e.g., "README allows emojis")
• Previously identified patterns to watch for
• Configuration preferences from past sessions

After Analysis

Capture significant findings for future sessions:

subcog_capture:
  namespace: learnings
  content: "[Description of finding]"
  tags: [human-voice, voice-pattern, project-name]
  source: [file path]

Capture voice decisions when made:

subcog_capture:
  namespace: decisions
  content: "[Decision and rationale]"
  tags: [human-voice, voice-decision]

Graceful Degradation

All skill functionality works without Subcog. Memory integration is additive:

• If Subcog unavailable, skip recall/capture steps
• Core detection and fixing always works
• Configuration via config.json is the primary method

Voice Observer Protocol

This protocol runs passively via the SessionStart hook. It does not require manual invocation.

When the user authors content during a session, silently observe their writing and compare against the voice profile at ~/.human-voice/voice-prompt.txt. Only observe text the user composed (not pasted external text, not AI-generated text). See ~/.human-voice/observer-protocol.md for the full observation rules.

Note: All profiles, sessions, and config live under ~/.human-voice/. This is the single canonical location regardless of which Claude account or plugin runtime is active.

Use /human-voice:voice-drift to report accumulated observations and drift from the profile.

Related Skills

• documentation-review:documentation-standards - Documentation quality standards
• documentation-review:changelog - Changelog maintenance