# Validate Cc

> Validates CC configuration quality based on discovery (PASS/FAIL + statistics)

- Skill: `ww-w-ai/validate-cc` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ww-w-ai/validate-cc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ww-w-ai/validate-cc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: ww-w-ai (https://skillmd.com/u/ww-w-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ww-w-ai/validate-cc

---


# 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`