Agent Validation Linter Skill

Purpose: Enforces validation pattern compliance across all 21+ agent profiles, preventing validation anti-patterns and ensuring security best practices (CVSS 8.2 injection prevention).

Benefits:

• ✅ Automated compliance detection
• ✅ Auto-fix capability for common violations
• ✅ CI/CD integration support
• ✅ Prevents validation anti-patterns
• ✅ 100% compliance enforcement

---

Quick Start

Check All Agents

./.claude/skills/agent-validation-linter/lint-agents.sh

Summary Only

./.claude/skills/agent-validation-linter/lint-agents.sh --summary

Auto-Fix Violations

./.claude/skills/agent-validation-linter/lint-agents.sh --fix

Strict Mode (CI/CD)

# Fails with exit code 1 if violations found
./.claude/skills/agent-validation-linter/lint-agents.sh --strict

---

Command Reference

Usage

./.claude/skills/agent-validation-linter/lint-agents.sh [OPTIONS]

Options

Option	Description	Default
--fix	Auto-fix agents that can be automatically corrected	false
--strict	Fail on any violations (exit code 1)	false
--summary	Show summary only (no detailed output)	false
--agent <path>	Lint specific agent file	All agents
--help	Show help message	-

---

Validation Checks

Check 1: Centralized Validation Skill Source ✅ Auto-Fixable

Required Pattern:

source .claude/skills/json-validation/validate-success-criteria.sh

Violation: Agent missing centralized validation skill source.

Auto-Fix: Injects source statement after "### 1. Read Success Criteria" section.

---

Check 2: validate_success_criteria() Call ✅ Auto-Fixable

Required Pattern:

validate_success_criteria || exit 1

Violation: Agent sources validation skill but doesn't call validation function.

Auto-Fix: Adds validation call immediately after source statement.

---

Check 3: No Inline Validation Code ⚠️ Manual Review Required

Anti-Pattern:

# Old inline validation (deprecated)
if ! echo "$AGENT_SUCCESS_CRITERIA" | jq -e '.' >/dev/null 2>&1; then
    echo "❌ Invalid JSON" >&2
    exit 1
fi

Violation: Agent contains inline validation code instead of using centralized skill.

Fix: Manual refactoring required - remove inline code, use centralized skill.

Reason: Requires careful review to ensure no custom validation logic is lost.

---

Check 4: Provider Configuration ✅ Auto-Fixable

Required Pattern:

<!-- PROVIDER_PARAMETERS
provider: zai
model: glm-4.6
-->

Violation: Agent missing provider configuration block.

Auto-Fix: Injects default provider configuration (zai + glm-4.6) after YAML frontmatter.

---

Output Formats

Detailed Output (Default)

Agent Validation Linter
=======================

Scanning: .claude/agents/cfn-dev-team/**/*.md

✓ database-architect
✓ backend-developer
✗ root-cause-analyst
  ⚠  Missing centralized validation skill source
  ⚠  Missing validate_success_criteria() call
  ⚠  Missing provider configuration (PROVIDER_PARAMETERS)
✓ integration-tester
...

=======================
Summary
=======================
Total agents scanned:  21
Compliant:             18
Non-compliant:         3
Total violations:      9
Compliance rate:       85.7%

⚠ Violations found (use --fix to auto-correct)

Summary Only (--summary)

Agent Validation Linter
=======================

Scanning: .claude/agents/cfn-dev-team/**/*.md

=======================
Summary
=======================
Total agents scanned:  21
Compliant:             18
Non-compliant:         3
Total violations:      9
Compliance rate:       85.7%

⚠ Violations found (use --fix to auto-correct)

With Auto-Fix (--fix)

✗ root-cause-analyst
  ⚠  Missing centralized validation skill source
  ⚠  Missing validate_success_criteria() call
  ⚠  Missing provider configuration (PROVIDER_PARAMETERS)
  🔧  Auto-fixing...
  ✓  Fixed root-cause-analyst.md

=======================
Summary
=======================
Total agents scanned:  21
Compliant:             21
Non-compliant:         0
Auto-fixed:            3
Compliance rate:       100.0%

✓ All agents compliant

---

CI/CD Integration

Git Pre-Commit Hook

Create .git/hooks/pre-commit:

#!/usr/bin/env bash
#
# Pre-commit hook: Enforce agent validation compliance

echo "Running agent validation linter..."

if ./.claude/skills/agent-validation-linter/lint-agents.sh --strict --summary; then
    echo "✓ All agents compliant"
    exit 0
else
    echo "✗ Agent validation failures detected"
    echo "  Run: ./.claude/skills/agent-validation-linter/lint-agents.sh --fix"
    exit 1
fi

Make executable:

chmod +x .git/hooks/pre-commit

GitHub Actions Workflow

name: Agent Validation

on: [push, pull_request]

jobs:
  validate-agents:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run agent validation linter
        run: |
          ./.claude/skills/agent-validation-linter/lint-agents.sh --strict

GitLab CI Pipeline

agent-validation:
  stage: test
  script:
    - ./.claude/skills/agent-validation-linter/lint-agents.sh --strict
  only:
    - merge_requests
    - main

---

Workflows

Workflow 1: Weekly Compliance Check

# Run linter
./.claude/skills/agent-validation-linter/lint-agents.sh

# Review violations
# If auto-fixable, apply fixes:
./.claude/skills/agent-validation-linter/lint-agents.sh --fix

# Verify fixes
./.claude/skills/agent-validation-linter/lint-agents.sh --summary

# Commit if changes made
git add .claude/agents/
git commit -m "fix(agents): Apply validation linter auto-fixes"

Workflow 2: Validate Specific Agent

# After creating new agent
./.claude/skills/agent-validation-linter/lint-agents.sh \
  --agent .claude/agents/cfn-dev-team/developers/new-agent.md

# If violations found, auto-fix
./.claude/skills/agent-validation-linter/lint-agents.sh \
  --agent .claude/agents/cfn-dev-team/developers/new-agent.md \
  --fix

Workflow 3: Migration to Centralized Validation

# Step 1: Check current state
./.claude/skills/agent-validation-linter/lint-agents.sh --summary

# Step 2: Auto-fix all auto-fixable violations
./.claude/skills/agent-validation-linter/lint-agents.sh --fix

# Step 3: Manually review agents with inline validation
#  (Check 3 violations - cannot auto-fix)
# For each agent with inline validation:
#   1. Review custom validation logic
#   2. Migrate to centralized skill
#   3. Remove inline code

# Step 4: Verify 100% compliance
./.claude/skills/agent-validation-linter/lint-agents.sh --strict

---

Auto-Fix Behavior

What Gets Fixed Automatically

1. Missing Source Statement:

   • Detects "## Success Criteria" section
   • Injects centralized validation skill source
   • Adds validation call
   • Location: After "### 1. Read Success Criteria" heading

2. Missing Validation Call:

   • Detects existing source statement
   • Adds validate_success_criteria || exit 1 call
   • Location: Immediately after source statement

3. Missing Provider Configuration:

   • Detects YAML frontmatter closing ---
   • Injects default provider configuration
   • Uses zai + glm-4.6 by default
   • Location: After frontmatter closing

What Requires Manual Review

1. Inline Validation Code:
   • Custom validation logic may exist
   • Side effects need review
   • Requires refactoring to centralized skill
   • Cannot safely auto-migrate

Backup Safety

• Creates .bak backup before auto-fix
• Restores from backup if fix fails
• Removes backup on successful fix
• No data loss risk

---

Exit Codes

Code	Meaning	When
0	Success	All agents compliant OR violations found but --strict not set
1	Failure	Violations found AND --strict mode enabled

---

Compliance Metrics

Target Compliance

• Production: 100% compliance required
• Development: 95%+ compliance recommended
• New Agents: 100% compliance enforced via template generator

Compliance Rate Calculation

Compliance Rate = (Compliant Agents / Total Agents) × 100

Example:

• Total Agents: 21
• Compliant: 18
• Non-Compliant: 3
• Compliance Rate: (18 / 21) × 100 = 85.7%

---

Examples

Example 1: Check Compliance

$ ./.claude/skills/agent-validation-linter/lint-agents.sh --summary

Agent Validation Linter
=======================

Scanning: .claude/agents/cfn-dev-team/**/*.md

=======================
Summary
=======================
Total agents scanned:  21
Compliant:             21
Non-compliant:         0
Compliance rate:       100.0%

✓ All agents compliant

Example 2: Fix Violations

$ ./.claude/skills/agent-validation-linter/lint-agents.sh --fix

Agent Validation Linter
=======================

Scanning: .claude/agents/cfn-dev-team/**/*.md

✗ root-cause-analyst
  ⚠  Missing centralized validation skill source
  ⚠  Missing validate_success_criteria() call
  🔧  Auto-fixing...
  ✓  Fixed root-cause-analyst.md

✗ analyst
  ⚠  Missing provider configuration (PROVIDER_PARAMETERS)
  🔧  Auto-fixing...
  ✓  Fixed analyst.md

=======================
Summary
=======================
Total agents scanned:  21
Compliant:             21
Non-compliant:         0
Auto-fixed:            2
Compliance rate:       100.0%

✓ All agents compliant

Example 3: Strict Mode (CI/CD)

$ ./.claude/skills/agent-validation-linter/lint-agents.sh --strict

Agent Validation Linter
=======================

Scanning: .claude/agents/cfn-dev-team/**/*.md

✗ root-cause-analyst
  ⚠  Missing centralized validation skill source

=======================
Summary
=======================
Total agents scanned:  21
Compliant:             20
Non-compliant:         1
Total violations:      1
Compliance rate:       95.2%

✗ STRICT MODE: Violations found
$ echo $?
1

Example 4: Validate Specific Agent

$ ./.claude/skills/agent-validation-linter/lint-agents.sh \
    --agent .claude/agents/cfn-dev-team/developers/new-agent.md

Agent Validation Linter
=======================

✓ new-agent

=======================
Summary
=======================
Total agents scanned:  1
Compliant:             1
Non-compliant:         0
Compliance rate:       100.0%

✓ All agents compliant

---

Integration with Other Skills

1. JSON Validation Skill

Dependency: Linter enforces usage of json-validation skill.

Check: Verifies all agents source validate-success-criteria.sh.

2. Agent Template Generator

Integration: Generated agents are automatically compliant with linter checks.

Benefit: New agents pass linter without modifications.

3. Pre-Edit Backup

Safety: Linter creates backups before auto-fixing (similar to pre-edit hook).

Rollback: Failed fixes automatically restore from backup.

---

Troubleshooting

Error: Cannot find agents directory

Cause: Running from wrong directory or agents directory missing.

Solution:

# Run from project root
cd /path/to/claude-flow-novice
./.claude/skills/agent-validation-linter/lint-agents.sh

Warning: Cannot auto-fix inline validation

Cause: Agent contains inline validation code requiring manual review.

Solution:

1. Review custom validation logic
2. Migrate to centralized skill pattern
3. Remove inline code manually

Backup files (.bak) left behind

Cause: Auto-fix encountered error during fix.

Solution:

# Review backup and original
diff agent.md agent.md.bak

# Restore if needed
mv agent.md.bak agent.md

# Or remove backups if satisfied with fixes
find .claude/agents -name "*.bak" -delete

---

Roadmap

v1.1.0 (Planned)

• Check for test-driven protocol compliance
• Validate success metrics section presence
• Check for proper completion protocol
• Warn on deprecated confidence score patterns

v2.0.0 (Future)

• JSON schema validation for YAML frontmatter
• Check for tool availability (Read, Write, etc.)
• Validate integration point documentation
• Auto-generate compliance reports

---

Status: Production-ready (v1.0.0) Coverage: 21+ agents Auto-Fix Rate: ~75% (3 of 4 checks) CI/CD Ready: ✅ Exit codes, strict mode, summary output