Voice Consistency & Example Format Checker

Voice Consistency & Example Format Checker

Automated quality assurance tool for Claude Code skills that enforces imperative voice and consistent example formatting across the skills library.

Quick Start

# Check all skills
python scripts/check_voice_consistency.py

# Check specific directory
python scripts/check_voice_consistency.py --path universal/

# Check single file
python scripts/check_voice_consistency.py --path path/to/SKILL.md

# Verbose output
python scripts/check_voice_consistency.py --verbose

# CI mode (strict, exit 1 on warnings or errors)
python scripts/check_voice_consistency.py --ci

Features

Voice Consistency Checks

Detects:

• ✅ Second-person pronouns ("you", "your", "you're", "yourself")
• ✅ Passive voice patterns ("is done", "was created", "are processed")
• ✅ Non-imperative mood ("should", "would", "could", "might")
• ✅ Conversational tone ("let's", "we can", "I recommend")

Enforces:

• Imperative voice throughout ("Use X", "Apply Y", "Configure Z")
• Active voice for clarity ("X validates Y" not "Y is validated")
• Direct commands starting with verbs

Example Format Validation

Checks:

• ✅/❌ example pattern usage
• Code block presence after example markers
• Balanced correct/incorrect examples
• Complete anti-pattern documentation

Anti-Pattern Documentation

Verifies:

• Skills document common mistakes
• Best practices are clearly stated
• What NOT to do is explained

Command-Line Interface

Basic Usage

# Default: Check all source SKILL.md files (toolchains/, universal/, examples/)
python scripts/check_voice_consistency.py

# Output:
# ================================================================================
# VOICE CONSISTENCY & EXAMPLE FORMAT REPORT
# ================================================================================
# Files checked: N
# Files with violations: 12
#
# Violations by severity:
#   Errors:      8  (critical, blocks CI)
#   Warnings:   24  (should fix)
#   Info:       15  (suggestions)
#   Total:      47

Path Options

# Check specific directory
python scripts/check_voice_consistency.py --path universal/

# Check single file
python scripts/check_voice_consistency.py --path toolchains/python/tooling/mypy/SKILL.md

# Check multiple toolchain categories
python scripts/check_voice_consistency.py --path toolchains/python/

Output Formats

# Text format (default, human-readable)
python scripts/check_voice_consistency.py --format text

# JSON format (for CI/CD integration)
python scripts/check_voice_consistency.py --format json > report.json

# Markdown format (for documentation)
python scripts/check_voice_consistency.py --format markdown > report.md

Verbosity

# Standard output (summary + top violations)
python scripts/check_voice_consistency.py

# Verbose output (includes line context)
python scripts/check_voice_consistency.py --verbose

# Limit violations shown per file
python scripts/check_voice_consistency.py --max-violations 5

Report Generation

# Generate markdown report file
python scripts/check_voice_consistency.py --report quality-report.md

# Generate and view
python scripts/check_voice_consistency.py --report report.md && open report.md

CI/CD Mode

# Strict mode: exit 1 on any warnings or errors
python scripts/check_voice_consistency.py --ci

# Exit codes:
#   0 = No warnings or errors
#   1 = Warnings or errors found (blocks merge)

Violation Severity Levels

🔴 ERROR (Critical, Blocks CI)

Second-person voice violations:

❌ You should use mypy for type checking.
✅ Use mypy for type checking.

❌ You can install it with pip.
✅ Install with pip.

❌ Your code must have type hints.
✅ Code must have type hints.

Why ERROR: Second-person voice violates the fundamental requirement for imperative voice. These must be fixed before merging.

🟡 WARNING (Should Fix; Blocks --ci)

Passive voice:

❌ Data is validated by the service.
✅ The service validates data.

❌ Tests are run by pytest.
✅ pytest runs tests.

Non-imperative mood:

❌ Should implement validation.
✅ Implement validation.

❌ Consider adding type hints.
✅ Add type hints.

Missing code blocks:

❌ ✅ **Correct usage**
   (no code block follows)

✅ ✅ **Correct usage**
   ```python
   code_example()

**Why WARNING**: These degrade quality but don't violate core requirements. Fix when possible.

### 🔵 INFO (Suggestions)

**Conversational tone:**
```markdown
❌ Let's create a function.
✅ Create a function.

❌ We should validate input.
✅ Validate input.

❌ I recommend using Pydantic.
✅ Recommended: Use Pydantic.

Imbalanced examples:

⚠️  Only ✅ examples found, consider adding ❌ anti-patterns
⚠️  Only ❌ examples found, consider adding ✅ correct patterns

Why INFO: Suggestions for improvement, not blockers. Optional but recommended.

Output Formats

Text Format (Default)

================================================================================
VOICE CONSISTENCY & EXAMPLE FORMAT REPORT
================================================================================
Files checked: N
Files with violations: 12

Violations by severity:
  Errors:      8  (critical, blocks CI)
  Warnings:   24  (should fix)
  Info:       15  (suggestions)
  Total:      47

Quality metrics:
  Files with ✅/❌ examples: X/N
  Files with anti-patterns:  Y/N
================================================================================

📄 toolchains/python/tooling/mypy/SKILL.md
   3 errors, 5 warnings, 2 info
--------------------------------------------------------------------------------

  Second Person Voice (3):
    🔴 Line 42: Second-person voice detected (use imperative)
       Matched: "you should"
       Fix: Replace with imperative: 'Use X' or 'Apply Y'
       Context: You should configure mypy.ini for strict mode.

  Passive Voice (5):
    🟡 Line 108: Passive voice detected
       Matched: "is validated"
       Fix: Consider active voice: 'X validates Y'

JSON Format (CI/CD)

{
  "summary": {
    "total_files": 110,
    "files_with_violations": 12,
    "total_errors": 8,
    "total_warnings": 24,
    "total_info": 15
  },
  "files": [
    {
      "path": "toolchains/python/tooling/mypy/SKILL.md",
      "violations": [
        {
          "file": "toolchains/python/tooling/mypy/SKILL.md",
          "line": 42,
          "content": "You should configure mypy.ini for strict mode.",
          "type": "second_person_voice",
          "severity": "error",
          "message": "Second-person voice detected (use imperative)",
          "suggestion": "Replace with imperative: 'Use X' or 'Apply Y'",
          "matched_text": "you should"
        }
      ],
      "error_count": 3,
      "warning_count": 5,
      "info_count": 2
    }
  ]
}

Markdown Format (Documentation)

# Voice Consistency & Example Format Report

## Summary

- **Files checked:** N
- **Files with violations:** 12
- **Errors:** 8 (critical)
- **Warnings:** 24
- **Info:** 15

## Violations by File

### toolchains/python/tooling/mypy/SKILL.md

**3** errors, **5** warnings, **2** info

#### Second Person Voice

- 🔴 **Line 42:** Second-person voice detected (use imperative)
  - *Fix:* Replace with imperative: 'Use X' or 'Apply Y'

#### Passive Voice

- 🟡 **Line 108:** Passive voice detected
  - *Fix:* Consider active voice: 'X validates Y'

CI/CD Integration

GitHub Actions

The tool integrates with GitHub Actions via .github/workflows/skill-quality.yml:

Features:

• ✅ Runs automatically on PRs
• ✅ Posts violation summary as PR comment
• ✅ Blocks merge on critical errors
• ✅ Uploads detailed reports as artifacts

PR Comment Example:

## 📊 Skill Quality Report

### Summary
- **Files checked:** N
- **Files with violations:** 12
- 🔴 **Errors:** 8 (critical)
- 🟡 **Warnings:** 24
- 🔵 **Info:** 15

❌ **Critical violations found.** Please fix before merging.

### Violations by File

#### `toolchains/python/tooling/mypy/SKILL.md`
3 errors, 5 warnings, 2 info

**Top Errors:**
- Line 42: Second-person voice detected (use imperative)
  - *Fix:* Replace with imperative: 'Use X' or 'Apply Y'

Pre-Commit Hook

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: skill-quality
        name: Skill Quality Checks
        entry: python scripts/check_voice_consistency.py --ci
        language: python
        pass_filenames: false
        files: '\.md$'

# Install and run
pre-commit install
pre-commit run skill-quality --all-files

Make Integration

Add to Makefile:

.PHONY: check-quality
check-quality:
	@echo "Checking skill quality..."
	@python scripts/check_voice_consistency.py

.PHONY: check-quality-ci
check-quality-ci:
	@python scripts/check_voice_consistency.py --ci

.PHONY: quality-report
quality-report:
	@python scripts/check_voice_consistency.py --report quality-report.md
	@echo "Report saved to quality-report.md"

.PHONY: fix-quality
fix-quality:
	@echo "Auto-fix not yet implemented. Manual fixes required."
	@python scripts/check_voice_consistency.py

Performance

Benchmarks (on the full skills set, ~50k lines total):

Initial run (cold):     2.3s
Subsequent runs:        1.8s
Single file:            0.05s
CI mode (all checks):   2.5s

Optimization features:

• Context map precomputation (fast exception detection)
• Single-pass violation collection
• Efficient regex compilation
• Minimal I/O operations

Exception Contexts

The checker automatically excludes these contexts from voice checks:

1. Code blocks: Content between triple backticks
2. Frontmatter: YAML between --- markers
3. Quotes: Lines starting with >
4. Tables: Lines with pipe separators |
5. Inline code: Text between single backticks
6. Comments: Lines starting with # or >

Example (all allowed):

---
description: You can use this skill for testing
---

> You should read the documentation.

| Feature | Description |
|---------|-------------|
| Type hints | You can add type annotations |

`you_can_use_snake_case`

```python
# You should configure this properly
def example():
    """You can call this function."""
    pass

## Common Fixes

### Second-Person Voice

| ❌ Before | ✅ After |
|----------|---------|
| You should use mypy | Use mypy |
| You can install with pip | Install with pip |
| You need to configure X | Configure X |
| You must have Python 3.11+ | Required: Python 3.11+ |
| Your code should follow PEP 8 | Code must follow PEP 8 |
| If you encounter errors | When errors occur |

### Passive Voice

| ❌ Before | ✅ After |
|----------|---------|
| Tests are run by pytest | pytest runs tests |
| Data is validated | Validate data |
| Files are processed | Process files |
| Configuration was updated | Updated configuration |

### Non-Imperative Mood

| ❌ Before | ✅ After |
|----------|---------|
| Should implement X | Implement X |
| Could use Y | Use Y for Z |
| Might want to add Z | Add Z |
| Consider adding validation | Add validation |

### Example Format

| ❌ Before | ✅ After |
|----------|---------|
| ✅ Good example<br>(no code) | ✅ **Correct**<br>```python<br>code()<br>``` |
| Only ✅ examples | Add ❌ anti-patterns |
| Only ❌ examples | Add ✅ correct patterns |

## Troubleshooting

### False Positives

**Q: Checker flags "you" in code examples?**

A: Ensure code is in triple-backtick blocks. Inline mentions should use single backticks: `` `you_can_use` ``.

**Q: Passive voice makes more sense in my context?**

A: Passive voice is WARNING level, not ERROR. Use judgment. If clearer, keep it (warning is acceptable).

### Performance

**Q: Checker is slow on large repository?**

A: Check specific paths during development:
```bash
# Fast: Check only changed files
python scripts/check_voice_consistency.py --path path/to/changed/

# Full check only before commit
python scripts/check_voice_consistency.py

CI/CD

Q: GitHub Action fails but local check passes?

A: Ensure same Python version (3.11+) and run with --ci flag locally:

python scripts/check_voice_consistency.py --ci

Development

Adding New Patterns

Edit scripts/check_voice_consistency.py:

# Add to SECOND_PERSON_PATTERNS
SECOND_PERSON_PATTERNS = {
    r'\bnew_pattern\b': "Suggestion for fix",
    # ...
}

# Or other pattern dictionaries:
# - PASSIVE_VOICE_PATTERNS
# - NON_IMPERATIVE_PATTERNS
# - CONVERSATIONAL_PATTERNS

Testing

# Test on sample file with violations
python scripts/check_voice_consistency.py --path /tmp/test_skill.md --verbose

# Run full check
python scripts/check_voice_consistency.py

# Test CI mode
python scripts/check_voice_consistency.py --ci
echo "Exit code: $?"

Architecture

SkillQualityChecker
├── ContextDetector
│   └── Builds exception context map (code blocks, quotes, tables)
├── VoiceConsistencyChecker
│   ├── Checks second-person voice
│   ├── Checks passive voice
│   ├── Checks non-imperative mood
│   └── Checks conversational tone
├── ExampleFormatChecker
│   ├── Validates ✅/❌ patterns
│   ├── Checks code block presence
│   └── Detects imbalanced examples
├── AntiPatternChecker
│   └── Verifies anti-pattern documentation
└── ReportGenerator
    ├── Text format
    ├── JSON format
    └── Markdown format

Related Documentation

• Voice Consistency Guide - Comprehensive style guide
• Skill Creator Guide - Skill creation workflow
• CI Workflow - GitHub Actions integration

Version History

• v1.0.0 (2025-12-03): Initial release
  • Voice consistency checks (second-person, passive, non-imperative, conversational)
  • Example format validation (✅/❌ patterns, code blocks, balance)
  • Anti-pattern documentation checks
  • Multiple output formats (text, JSON, markdown)
  • CI/CD integration
  • Comprehensive documentation

Maintained by: Claude MPM Team License: MIT Python: 3.11+