agentleFS
vlad-ryzhkovvlad-ryzhkov/ai-context-engineering-for-frontend/.claude/skills/agents-checker/SKILL.md

agents-checker

Skill2 starsChanged 8 months agoUnlicenseView on GitHub

Verifies structural integrity and compliance of .claude/agents/ and .claude/frontend_agent.md against init-agent standards. Use after modifying agent files or adding new agents. Do not use for code quality audits — use /frontend-code-review instead.

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 6 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    After manually editing frontend_agent.md or any file in .claude/agents/

    line 26
  2. Distinctive:

    After adding a new agent

    line 27
  3. Distinctive:

    Check each required file is present:

    line 51
  4. Very specific:

    Verify frontend_agent.md contains all required sections:

    line 63
  5. Very specific:

    Verify the referenced file exists under .claude/agents/

    line 99
  6. Very specific:

    Check for content in .claude/agents/*.md that duplicates frontend_agent.md verbatim or near-verbatim.

    line 104
  7. Very specific:

    Read all files in .claude/agents/ and .claude/frontend_agent.md

    line 108
  8. Distinctive:

    Before finalizing the audit:

    line 158
  9. Very specific:

    Gardener Protocol: Call .claude/protocols/gardener.md.

    line 166
  10. Very specific:

    Write the full report to audit/agents-checker-report_{agent}_{YYYYMMDD_HHMMSS}.md using the Write tool.

    line 180
  11. Distinctive:

    All-pass shortcut: If all files pass with ✅ PASS and cross-refs are clean → replace the 4-row status table with a single line:

    line 224
  12. Distinctive:

    Only expand the status table when ≥1 file has ⚠️ WARNINGS or ❌ FAIL.

    line 230
  13. Distinctive:

    All 3 required files confirmed present (frontend_agent.md, engineer.md, auditor.md)

    line 255

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/agents-checker — AI Agent Setup Validator

SILENT MODE: Execute all validation phases silently. Do not output intermediate findings or progress per file. Only the final audit report and SKILL COMPLETE block go to chat.

Status Reporting: After Phase 2 (frontend_agent.md checks) and Phase 3 (each agent file), emit a single-line JSON progress: {"phase": N, "files_scanned": N, "issues_found": N}

Type: Audit Utility Category: Frontend Setup / Compliance

Checks that the project's Claude agent files comply with the standards produced by /init-agent. Validates structure, required sections, cross-references, and absence of stale placeholders.

When to Use

  • After manually editing frontend_agent.md or any file in .claude/agents/
  • After adding a new agent
  • Before running /update-ai-setup
  • As a pre-flight check in the development pipeline

Scope

TargetPath
Frontend Lead profile.claude/frontend_agent.md
Agent files.claude/agents/*.md
Skill cross-refs.claude/skills/*/SKILL.md frontmatter

Input Parameters

ParameterRequiredDefaultDescription
auto_fixNotrueWhen true, auto-repairs safe deterministic issues after full audit and logs each change with rationale. Unsafe issues (missing files, role-specific content) are always flagged only.

Workflow

Phase 1: File Existence

Check each required file is present:

  • .claude/frontend_agent.md
  • .claude/agents/engineer.md
  • .claude/agents/auditor.md

If any file is missing → 🔴 CRITICAL. Stop and report. Do not proceed to Phase 2.

Phase 2: frontend_agent.md Structure

Load .claude/skills/init-agent/references/qa-agent-template.md as the reference standard (orchestrator structure).

Verify frontend_agent.md contains all required sections:

CheckRuleSeverity
## Core Mindset presentMust have 3–5 principles listed🔴 CRITICAL
## Anti-Patterns (BANNED) presentTable with ≥ 3 rows🔴 CRITICAL
## Quality Gates presentMust contain Start + Generate + Review gates🟠 MAJOR
## Skills Matrix presentMust reference all 10 skills with owners🟠 MAJOR
No placeholdersGrep for [xxx] pattern — none allowed🟠 MAJOR
Anti-patterns match rolefrontend_agent.md is an Orchestrator — anti-patterns must cover orchestration failures (e.g. micro-management, blind approval, silent looping). Code-level patterns belong in agent files, NOT here.🟡 MINOR

Phase 3: Agent File Validation

For each .md file in .claude/agents/:

CheckRuleSeverity
Role heading present## Identity or # [Name] Agent🔴 CRITICAL
## Core Mindset presentAt least 3 principles🔴 CRITICAL
## Anti-Patterns (BANNED) presentTable with ≥ 3 rows🟠 MAJOR
## Verbosity Protocol presentMust define output format🟠 MAJOR
## Quality Gates presentAt least Commit + Review gates🟠 MAJOR
Skills list defined## Skills section lists at least 1 skill🟠 MAJOR
## Output Contract presentDefines artifact format🟡 MINOR
No placeholdersGrep for [xxx] — none allowed🟠 MAJOR

Phase 4: Cross-Reference Integrity

  1. Skills referenced in agent files exist:
    • Extract all /skill-name mentions from each agent file
    • For each: check .claude/skills/{skill-name}/SKILL.md exists
    • Missing skill → 🟠 MAJOR
  2. Agent references in SKILL.md frontmatter are valid:
    • Glob all .claude/skills/*/SKILL.md
    • Extract agent: field from frontmatter (if present)
    • Verify the referenced file exists under .claude/agents/
    • Broken reference → 🟠 MAJOR

Phase 5: Agent File Duplication

Check for content in .claude/agents/*.md that duplicates frontend_agent.md verbatim or near-verbatim.

Algorithm:

  1. Read all files in .claude/agents/ and .claude/frontend_agent.md
  2. LLM step: for each agent file, compare each section against the corresponding section in frontend_agent.md. Flag content that is duplicated word-for-word or with only minor rephrasing
  3. Severity: WARNING — "Content in agents/{file}.md § {section} duplicates frontend_agent.md § {section}. Canonical location: frontend_agent.md. Consider removing from agent file and adding → see frontend_agent.md."
  4. Exception: ## Anti-Patterns (BANNED) may intentionally contain agent-specific rules — flag only exact/verbatim copies, not agent-specific content

Not fixable via auto_fix — removing content requires understanding of intent; always flag for manual review.


Phase 6: Self-Healing (auto_fix=true)

Skipped if auto_fix=false. Runs after Phase 4 only if audit found fixable issues.

Fixable issues — safe to auto-repair:

FindingFix ActionRationale
Placeholder patterns ([Profile], [Framework], [Actor], [xxx]) in any agent fileRemove the containing line via EditPlaceholders are unfilled template slots — they add noise and confuse the AI reading the file
## Anti-Patterns (BANNED) missing in frontend_agent.mdAppend section verbatim from init-agent/references/qa-agent-template.mdSection is fully standardized in the template; copying it is deterministic and safe
## Skills Matrix missing in frontend_agent.mdFlag only — content is project-specificCannot fabricate skill ownership without context
Broken agent: reference in SKILL.md frontmatter (target file missing)Remove the agent: line from frontmatterA broken ref causes skill routing errors; removing it degrades to default gracefully

NOT fixable — always flagged, never auto-repaired:

IssueReason
Required file missing (frontend_agent.md, engineer.md, auditor.md)Cannot fabricate role-specific content
## Core Mindset missingContent is role-specific — wrong defaults are worse than absence
## Identity / Role heading missing in agent fileRequires understanding of agent purpose
Skill cross-references to non-existent skillsMay be intentional (planned future skill)

After fixes: Re-run Phases 2–3 on modified files to confirm healing was effective. Report delta.


Anti-Patterns

Anti-PatternWhy It BreaksFix
Agent file missing ## Identity headingAI doesn't know which agent this is; routing failsAdd explicit role heading: ## Identity with Role + Authority
Identical content in agent file and frontend_agent.md (verbatim copy)Duplication wastes tokens; conflicting updatesKeep canonical content in frontend_agent.md; use reference in agent file if needed
Placeholder text [Profile], [Framework], [xxx] left unfilledTemplate cruft confuses the AI; treated as actual rulesRemove all placeholder lines after initial setup
Broken agent: reference in SKILL.mdSkill cannot find its agent profile; falls back to defaultsVerify agent file exists at .claude/agents/{name}.md
## Anti-Patterns table with < 3 rowsInsufficient guidance for that roleAdd role-specific patterns from the agent's domain
Missing ## Verbosity Protocol in agent fileAI outputs verbose intermediate findings; wastes tokensAdd protocol section explaining output format

Quality Gate (Self-Review)

Before finalizing the audit:

  • All 3 required files scanned (frontend_agent.md + all agents/*.md)
  • Phases 1–5 completed without early exit
  • No critical issues left unflagged or auto-repaired unsafely
  • Report artifact generated with timestamp
  • JSON progress emitted after Phases 2–3

Gardener Protocol: Call .claude/protocols/gardener.md. If you identified missing rules or inefficiencies during this run, output a brief proposal table. Otherwise: 🌱 Gardener: No updates needed.


Output Format

Derive the {agent} slug from the skill argument:

  • Specific agent file (e.g., agents/engineer.md) → basename without extension: engineer
  • Directory or multiple targets (e.g., .claude/agents, all) → all
  • Sanitize: replace /, spaces, and dots with -, lowercase

Obtain timestamp via date +%Y%m%d_%H%M%S. Use it as the suffix. Write the full report to audit/agents-checker-report_{agent}_{YYYYMMDD_HHMMSS}.md using the Write tool. Do NOT output the full report body to chat — only the summary block and completion block go to chat.

File structure (audit/agents-checker-report_{agent}_{YYYYMMDD_HHMMSS}.md):

# Agent Setup Audit Report
Date: {YYYY-MM-DD}

## Summary
| File | Status |
|------|--------|
| frontend_agent.md | ✅ PASS / ⚠️ WARNINGS / ❌ FAIL |
| engineer.md       | ✅ PASS / ⚠️ WARNINGS / ❌ FAIL |
| auditor.md        | ✅ PASS / ⚠️ WARNINGS / ❌ FAIL |
| Cross-refs        | ✅ PASS / ⚠️ N broken refs      |

## Findings

| # | Severity | File | Issue | Rule |
|---|----------|------|-------|------|
| 1 | 🔴 CRITICAL | .claude/frontend_agent.md | Missing ## Anti-Patterns table | init-agent template |
| 2 | 🟠 MAJOR | .claude/agents/auditor.md | /health-check skill not found | Phase 4 cross-ref |
| 3 | 🟡 MINOR | .claude/agents/engineer.md | ## Output Contract missing | Phase 3 check |

## Auto-Fix Log
- .claude/frontend_agent.md — Appended ## Anti-Patterns from template
  → Reason: ...

## Recommendations (Manual Fix Required)

### 1. [🟠] .claude/frontend_agent.md — <issue title>
**What:** ...
**How to fix:** ...

### 2. [🟡] .claude/agents/auditor.md — <issue title>
**What:** ...
**How to fix:** ...

## Decision
📝 [APPROVE / PASS WITH WARNINGS / ACTION RECOMMENDED]

Chat output (summary only):

All-pass shortcut: If all files pass with ✅ PASS and cross-refs are clean → replace the 4-row status table with a single line:

✅ All files compliant (frontend_agent.md, engineer.md, auditor.md, cross-refs)

Only expand the status table when ≥1 file has ⚠️ WARNINGS or ❌ FAIL.

🛡️ AGENT SETUP AUDIT
├─ frontend_agent.md: [✅ PASS / ⚠️ WARNINGS / ❌ FAIL]
├─ engineer.md:       [✅ PASS / ⚠️ WARNINGS / ❌ FAIL]
├─ auditor.md:        [✅ PASS / ⚠️ WARNINGS / ❌ FAIL]
└─ Cross-refs:        [✅ PASS / ⚠️ N broken refs]

📝 Decision: [APPROVE / PASS WITH WARNINGS / ACTION RECOMMENDED]
→ Full report: audit/agents-checker-report_{agent}_{YYYYMMDD_HHMMSS}.md

Finish with the standard completion block:

✅ SKILL COMPLETE: /agents-checker
├─ Artifacts: audit/agents-checker-report_{agent}_{YYYYMMDD_HHMMSS}.md
├─ Compilation: N/A
├─ Upstream: .claude/skills/init-agent/references/qa-agent-template.md
└─ Coverage: [X/Y checks passed]

Definition of Done

  • All 3 required files confirmed present (frontend_agent.md, engineer.md, auditor.md)
  • frontend_agent.md contains all required sections (Core Mindset, Anti-Patterns, Quality Gates, Skills Matrix)
  • Each agent file contains Identity + Mindset + Anti-Patterns + Quality Gates + Skills
  • Zero broken cross-references to non-existent skills
  • No [placeholder] text in any agent file
  • Agent file duplication check completed: verbatim duplicates of frontend_agent.md content flagged
  • auto_fix=true: all safe issues repaired with logged rationale; re-validation passes; non-fixable issues remain in report with manual fix required label

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.