SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsvalidate-cc

validate-cc

Deployment & operations

View repository

Updated 10-16 07:32

About this skill

validate-cc -- CC Configuration Quality Validation

Corresponding rules: docs/specs/rule-writing.md, docs/specs/skill-design.md, docs/specs/agent-design.md, docs/specs/settings-design.md

Purpose

Validates only the items that exist in the project. Categories that do not exist are automatically omitted from the report. For categories that do exist, provides PASS/FAIL results and statistics per category.

Input

  • Target directory: current project root (auto-detected)
  • No additional input required

Verification criteria

Categories whose target directory does not exist (e.g., .claude/agents/ missing) are automatically omitted from the report.

1. CLAUDE.md

Item Verification method Evidence type
Existence (EXISTS) CLAUDE.md file present CC_OFFICIAL
Structure (STRUCTURE) includes Tech Stack or Architecture patterns EMPIRICAL
Technical depth (DEPTH) 3 or more ## sections EMPIRICAL
  • EXISTS: CC automatically loads CLAUDE.md into context at session start (CC_OFFICIAL)
  • STRUCTURE: Tech Stack/Architecture sections prevent Claude from guessing the tech stack (EMPIRICAL)
  • DEPTH: 3 or more sections provide sufficient project orientation (EMPIRICAL)

2. Rules

Item Verification method Evidence type
Directory (DIR) .claude/rules/ present CC_OFFICIAL
File count (FILES) 2 or more .md files EMPIRICAL
WHY/CONSTRAINT (META) ratio of rules that contain WHY or CONSTRAINT EMPIRICAL
Scoping (SCOPING) paths: or scope: or applicable-scope specified EMPIRICAL
  • DIR: CC auto-loads .md files from the rules/ directory (CC_OFFICIAL)
  • FILES: a meaningful rule system requires at least 2 files (EMPIRICAL)
  • META: WHY/CONSTRAINT enable rule-priority judgment and awareness of violation severity (EMPIRICAL)
  • SCOPING: explicit scope prevents indiscriminate rule application (EMPIRICAL)

3. Skills

Item Verification method Evidence type
Directory (DIR) .claude/skills/ present CC_OFFICIAL
Frontmatter (FRONTMATTER) SKILL.md has YAML frontmatter (name, description) CC_OFFICIAL
Rule-Skill ratio (RULE_SKILL_RATIO) ratio of skill directories to rule files EMPIRICAL
Gate (GATE) SKILL.md contains "Do not proceed" or "Mandatory Output" or "Pre-Output Checklist" EMPIRICAL
  • DIR: CC recognizes SKILL.md in the skills/ directory (CC_OFFICIAL)
  • FRONTMATTER: without frontmatter, CC cannot recognize the skill (CC_OFFICIAL)
  • RULE_SKILL_RATIO: Rules without a Skill cannot be automatically validated (EMPIRICAL)
  • GATE: skills without execution gates allow the AI to skip verification depth (EMPIRICAL)
  • Methodology rule exception: Rules marked [M] (methodology rules such as c-suite-analysis, question-principles, research) are excluded from the Rule-Skill ratio calculation. These rules define analysis/research methodologies consumed by skills like /discovery, not CC behavior constraints requiring a dedicated validation skill.

4. Agents

Item Verification method Evidence type
Directory (DIR) .claude/agents/ present CC_OFFICIAL
File count (FILES) 1 or more .md files EMPIRICAL
Allowed Tools (ALLOWED_TOOLS) agent defines allowed_tools or allowed-tools CC_OFFICIAL
  • DIR: CC recognizes agent definitions in the agents/ directory (CC_OFFICIAL)
  • FILES: at least 1 agent is required for automated code review/analysis (EMPIRICAL)
  • ALLOWED_TOOLS: allowed_tools restricts the agent's tool scope (CC_OFFICIAL)

5. Settings

Item Verification method Evidence type
Existence (EXISTS) .claude/settings.json present CC_OFFICIAL
Deny (DENY) deny key + contains .env or rm -rf CC_OFFICIAL
Hook (HOOK) PreToolUse or PostToolUse present CC_OFFICIAL
  • EXISTS: settings.json controls tool permissions and hooks (CC_OFFICIAL)
  • DENY: deny takes precedence over allow, reliably blocking dangerous operations (CC_OFFICIAL)
  • HOOK: PreToolUse/PostToolUse hooks automate verification before and after tool execution (CC_OFFICIAL)

6. README.md

Item Verification method Evidence type
Existence (EXISTS) README.md file present INDUSTRY_STD
Content (CONTENT) 3 or more ## sections INDUSTRY_STD
  • EXISTS: README.md is the project entry point providing installation/run guidance (INDUSTRY_STD)
  • CONTENT: at least 3 sections are required to cover basic guidance such as install, run, and test (INDUSTRY_STD)

7. Commands

Item Verification method Evidence type
Directory (DIR) .claude/commands/ present CC_OFFICIAL
Naming (NAMING) self-descriptive name (warn on abbreviations, "and") EMPIRICAL
Single action (SINGLE_ACTION) no branching/looping logic (if/else, for each) EMPIRICAL
  • DIR: CC recognizes commands in the commands/ directory (CC_OFFICIAL)
  • NAMING: the action should be immediately inferable from the name alone (EMPIRICAL)
  • SINGLE_ACTION: with branching/looping present, conversion to a skill is recommended (EMPIRICAL)

Mandatory output: Category verification matrix

Output the following matrix before grade calculation. Every cell must be filled. If any cell is empty, do not proceed to grading.

Category Status Items Checked Pass Warn Fail Evidence
CLAUDE.md ? ? ? ? ? {tools, files checked}
Rules ? ? ? ? ? {tools, files checked}
Skills ? ? ? ? ? {tools, files checked}
Agents ? ? ? ? ? {tools, files checked}
Settings ? ? ? ? ? {tools, files checked}
README.md ? ? ? ? ? {tools, files checked}
Commands ? ? ? ? ? {tools, files checked}

Status values: PASS (verified clean), NOT_APPLICABLE (category directory not found -- omitted from report), SKIPPED (plugin issue), SHALLOW (partial check)

Grade criteria

Condition Grade Meaning
0 failures, 0 warnings Excellent CC configuration is mature enough for consistent AI collaboration
0 failures Good basic structure is in place but some areas need reinforcement
1-2 failures Needs Improvement core configuration is lacking, AI behavior is inconsistent
3+ failures Poor CC configuration is nearly absent, AI must guess everything

Execution logic

  1. Detect current project root (search for CLAUDE.md or .claude/ via Glob)
  2. Discover existing categories (omit categories that do not exist)
  3. Verify category-specific items using Read/Glob/Grep:
    • Glob to confirm file/directory existence
    • Read to read file contents
    • Grep for pattern matching (WHY, CONSTRAINT, paths:, etc.)
  4. PASS/WARN/FAIL determination and statistics aggregation per item
  5. Determine grade
  6. Generate improvement suggestions

Output

Produce the validation report in the user's conversation language.

Output the validation results in the following format:

CC Configuration Quality Report
==================================================

[PASS] CLAUDE.md (3/3)
  [v] Existence
  [v] Structure
  [v] Technical depth

[WARN] Rules (3/4)
  [v] Directory
  [v] File count
  [!] WHY/CONSTRAINT -- 50% coverage
  [v] Scoping

[PASS] Skills (3/3)
  [v] Directory
  [v] Frontmatter
  [v] Rule-Skill ratio

[PASS] Settings (3/3)
  [v] Existence
  [v] Deny
  [v] Hook

[PASS] README.md (2/2)
  [v] Existence
  [v] Content

--------------------------------------------------
Total: 14/15 passed | 1 warning | 0 failures
Grade: Good

Improvement suggestions: 1
  - Add WHY metadata to rules

In the example above, the Agents category is automatically omitted because the .claude/agents/ directory does not exist.

Icon convention

Icon Meaning Condition
[PASS] overall pass 0 failed items
[WARN] warnings present 0 failures, 1+ warnings
[FAIL] failures present 1+ failed items
[v] item pass status == pass
[!] item warning status == warn
[x] item failure status == fail

Pre-output checklist (required before final output)

Verify every item before drafting the report. If any item is unchecked, go back and complete it.

  • Every category has a Status value assigned (no empty Status cells)
  • Every category whose Status != NOT_APPLICABLE has an Evidence value
  • Categories that do not exist have Status NOT_APPLICABLE
  • Grade calculation matches the grade criteria table
  • Report language matches the user's conversation language

Schema compliance check (required before persisting to .ww-w-ai/standards/)

Verify the JSON output before writing to .ww-w-ai/standards/validate-cc/:

  • All "required" fields in schema.json are present and non-empty
  • categories[] array length matches the number of categories checked
  • summary.total == summary.passed + summary.warnings + summary.failures

Output persistence

After generating the validation report, persist results to .ww-w-ai/standards/validate-cc/:

  1. Create the .ww-w-ai/standards/validate-cc/ directory if it does not exist
  2. Write latest.json -- structured result following templates/schema.json
  3. Write latest.md -- human-readable report following templates/report.template.md
  4. Archive to history/ -- copy latest.json to .ww-w-ai/standards/validate-cc/history/{timestamp}.json

latest.md is produced in the user's conversation language. JSON field names remain in English regardless of language. The JSON output enables machine-parseable history tracking and cross-run comparison. The history/ directory preserves prior runs for trend analysis.

Permission rationale

  • Write: restricted to .ww-w-ai/standards/ output persistence. No modification of project source.
  • Bash: restricted to read-only git/system queries. No file modification.

Notes

  • Bash is permitted for directory creation (mkdir -p .ww-w-ai/standards/validate-cc/history) and Grep pattern matching.
  • Detailed improvement guidance is provided by the /audit skill.

Spec references

Detailed verification criteria, evidence tables, examples:

  • Corresponding rule specs: ../../docs/specs/rule-writing.md, ../../docs/specs/skill-design.md, ../../docs/specs/agent-design.md, ../../docs/specs/settings-design.md, ../../docs/specs/claude-md-design.md, ../../docs/specs/readme-design.md, ../../docs/specs/commands-design.md
  • Evidence index: ../../docs/evidence/evidence-registry.md