@cleocode/skills 2.0.0

package/skills/ct-skill-validator/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: ct-skill-validator
+description: Validates an existing skill folder against the full CLEO standard and ecosystem. Use when auditing skills for structural compliance, verifying a skill fits into the CLEO ecosystem and constitution, running quality A/B evals, or preparing a skill for distribution. Runs a 3-phase validation loop — structural, ecosystem fit, and quality eval — then presents all findings as an HTML report opened in the user's browser. Iterates until all required phases pass.
+disable-model-invocation: true
+allowed-tools: Bash(python *)
+---
+
+# CLEO Skill Validator
+
+Full 3-phase validation loop for CLEO skills. Every phase must reach PASS before the skill
+is considered ecosystem-ready. Run the phases in order and iterate on failures.
+
+**Always end with the HTML report** — the final deliverable to the user is the combined report
+opened in their browser, not terminal output.
+
+---
+
+## Phase 1: Structural Compliance (Iterate to Zero Errors)
+
+Run `validate.py` until the result is `PASS` or `PASS (with warnings)` with 0 errors.
+Warnings are acceptable; errors are not. Fix errors and re-run.
+
+```bash
+# Full gauntlet — text output
+python ${CLAUDE_SKILL_DIR}/scripts/validate.py <skill-dir>
+
+# With manifest checks (Tier 4):
+python ${CLAUDE_SKILL_DIR}/scripts/validate.py <skill-dir> \
+  --manifest <manifest.json> --dispatch-config <dispatch-config.json>
+
+# JSON output (for scripting):
+python ${CLAUDE_SKILL_DIR}/scripts/validate.py <skill-dir> --json
+
+# Deep body quality audit (optional, run alongside validate.py):
+python ${CLAUDE_SKILL_DIR}/scripts/audit_body.py <skill-dir>
+
+# Manifest alignment check:
+python ${CLAUDE_SKILL_DIR}/scripts/check_manifest.py <skill-dir> <manifest.json>
+```
+
+**Iteration rule**: If errors > 0, fix them in the skill's SKILL.md, re-run `validate.py`.
+Repeat until errors = 0. Do not proceed to Phase 2 while errors remain.
+
+**Validation tiers:**
+- Tier 1 — Structure: SKILL.md exists, frontmatter parseable, no CLEO-only fields
+- Tier 2 — Frontmatter Quality: name matches dir, description has trigger indicators
+- Tier 3 — Body Quality: length, no placeholder text, file references exist on disk
+- Tier 4 — CLEO Integration: manifest and dispatch-config alignment (optional)
+- Tier 5 — Provider Compatibility: provider-skills-map check (optional)
+
+See [references/validation-rules.md](references/validation-rules.md) for full rule set.
+
+---
+
+## Phase 2: CLEO Ecosystem Compliance (Iterate to PASS)
+
+Checks whether the skill's intent and purpose fit into the CLEO ecosystem — the 10 canonical
+domains, canonical verbs, RCASD-IVTR+C lifecycle, and the CLEO Operation Constitution.
+
+**Step 1: Extract skill context**
+```bash
+python ${CLAUDE_SKILL_DIR}/scripts/check_ecosystem.py <skill-dir> --output context.json
+```
+
+This extracts: CLEO operations referenced, domains mentioned, lifecycle stages, deprecated
+verb usage, and direct data manipulation patterns.
+
+**Step 2: Run the ecosystem-checker agent**
+
+Invoke the ecosystem-checker agent with the context package:
+
+```
+Inputs:
+  - context.json (from Step 1)
+  - references/cleo-ecosystem-rules.md (the 8 rules)
+  - The skill's SKILL.md (for full body reading)
+
+Agent file: ${CLAUDE_SKILL_DIR}/agents/ecosystem-checker.md
+
+Output: ecosystem-check.json
+```
+
+The checker evaluates 8 rules from [references/cleo-ecosystem-rules.md](references/cleo-ecosystem-rules.md):
+
+1. **Domain Fit** — Does the skill serve at least one of the 10 canonical CLEO domains?
+2. **MCP Operation Syntax** — Are CLEO operations referenced with valid `domain.operation` format?
+3. **Canonical Verb Compliance** — No deprecated verbs (create, get, search as verb)
+4. **Non-Duplication** — Skill isn't a thin wrapper over a single existing CLEO operation
+5. **Data Integrity** — No direct `.cleo/` file editing instructions
+6. **Lifecycle Alignment** — Skill aligns with relevant RCASD-IVTR+C stages
+7. **Purpose Clarity** — Skill has a specific, bounded, genuinely useful purpose
+8. **Tools Alignment** — `allowed-tools` matches what the skill actually needs
+
+**Iteration rule**: If ecosystem-check.json contains `"verdict": "FAIL"`, address each ERROR-severity
+rule finding, fix the skill content, re-run check_ecosystem.py, re-run the ecosystem-checker agent.
+Repeat until verdict is `PASS` or `PASS_WITH_WARNINGS`. WARN is acceptable; ERROR is not.
+
+---
+
+## Phase 3: Quality A/B Eval
+
+Tests whether the skill actually improves agent output quality vs. no skill context.
+Uses the eval infrastructure from ct-skill-creator.
+
+**Trigger accuracy** — does the skill description trigger correctly?
+```bash
+python ${CLAUDE_SKILL_DIR}/../ct-skill-creator/scripts/run_eval.py \
+  --eval-set ${CLAUDE_SKILL_DIR}/evals/eval_set.json \
+  --skill-path ${CLAUDE_SKILL_DIR}
+```
+
+**Optimize description** (if trigger accuracy < 80%):
+```bash
+python ${CLAUDE_SKILL_DIR}/../ct-skill-creator/scripts/run_loop.py \
+  --eval-set ${CLAUDE_SKILL_DIR}/evals/eval_set.json \
+  --skill-path ${CLAUDE_SKILL_DIR} \
+  --model claude-sonnet-4-6 \
+  --max-iterations 5
+```
+`run_loop.py` opens a live HTML accuracy report in the browser automatically.
+
+**Quality eval** (with/without skill A/B):
+1. Spawn two agents in the SAME turn: one WITH skill context loaded, one WITHOUT (baseline)
+2. Give both the same task prompt from [evals/evals.json](evals/evals.json)
+3. Grade each with the grader agent → `grading.json`:
+   `${CLAUDE_SKILL_DIR}/../ct-skill-creator/agents/grader.md`
+4. Blind A/B comparison with the comparator agent → `comparison.json`:
+   `${CLAUDE_SKILL_DIR}/../ct-skill-creator/agents/comparator.md`
+5. Post-hoc analysis with the analyzer agent → `analysis.json`:
+   `${CLAUDE_SKILL_DIR}/../ct-skill-creator/agents/analyzer.md`
+6. Serve the full eval review:
+   `python ${CLAUDE_SKILL_DIR}/../ct-skill-creator/eval-viewer/generate_review.py <workspace-dir>`
+   (Opens browser at localhost:3117)
+
+See [references/validation-rules.md](references/validation-rules.md) and
+`${CLAUDE_SKILL_DIR}/../ct-skill-creator/references/schemas.md` for JSON output schemas.
+
+---
+
+## Final: Generate and Present HTML Report
+
+After completing all phases, generate the unified report and open it in the browser.
+
+```bash
+# Minimum — Phase 1 only:
+python ${CLAUDE_SKILL_DIR}/scripts/generate_validation_report.py <skill-dir> --no-open --output report.html
+
+# With ecosystem check:
+python ${CLAUDE_SKILL_DIR}/scripts/generate_validation_report.py <skill-dir> \
+  --ecosystem-check ecosystem-check.json --no-open --output report.html
+
+# Full 3-phase report:
+python ${CLAUDE_SKILL_DIR}/scripts/generate_validation_report.py <skill-dir> \
+  --ecosystem-check ecosystem-check.json \
+  --grading grading.json \
+  --comparison comparison.json \
+  --audit \
+  --output report.html
+```
+
+**Tell the user:**
+- The path to report.html (so they can revisit or share it)
+- The Phase 1/2/3 verdict for each phase
+- Which specific errors or warnings remain
+- What to fix if any phase is FAIL
+
+Open the report in the browser: omit `--no-open` (default behaviour opens browser automatically).
+
+---
+
+## Self-Validation
+
+This skill validates itself. To validate ct-skill-validator:
+
+```bash
+python ${CLAUDE_SKILL_DIR}/scripts/validate.py ${CLAUDE_SKILL_DIR}
+python ${CLAUDE_SKILL_DIR}/scripts/check_ecosystem.py ${CLAUDE_SKILL_DIR} | cat
+```

package/skills/ct-skill-validator/agents/ecosystem-checker.md

@@ -0,0 +1,151 @@
+# CLEO Ecosystem Compliance Checker
+
+Evaluate whether a skill fits into and properly uses the CLEO ecosystem.
+
+## Role
+
+You are an ecosystem compliance auditor for CLEO skills. You receive a structured context
+package describing a skill's content and usage patterns. You evaluate the skill against the
+CLEO ecosystem rules and produce a structured compliance report.
+
+You MUST be specific: cite exact text from the skill when flagging issues, and cite the exact
+rule number being violated. Vague findings are useless.
+
+## Inputs
+
+You receive a JSON context package (from `check_ecosystem.py`) with:
+
+- `skill_name`: The skill's directory name
+- `frontmatter`: Parsed frontmatter fields
+- `description`: The skill's trigger description
+- `body`: The full SKILL.md body text
+- `allowed_tools`: The allowed-tools field value
+- `cleo_operations_referenced`: List of detected CLEO operations (domain.operation strings)
+- `domains_mentioned`: Canonical domain names found in body
+- `lifecycle_stages_mentioned`: RCASD-IVTR+C stage names found in body
+- `deprecated_verbs_found`: Any deprecated verb patterns found
+- `body_line_count`: Number of body lines
+
+You also MUST read `references/cleo-ecosystem-rules.md` for the full rule definitions.
+
+## Process
+
+### Step 1: Read the Rules
+
+Read `${CLAUDE_SKILL_DIR}/references/cleo-ecosystem-rules.md` in full.
+
+### Step 2: Evaluate Each Rule
+
+For each rule (1 through 8), determine: OK, WARN, ERROR, or SKIP.
+
+**Rule 1 — Domain Fit:**
+- Look at `domains_mentioned`, `description`, and `body` for domain signals
+- Classify the skill's primary domain(s)
+- ERROR if no domain connection; WARN if too scattered
+
+**Rule 2 — MCP Operation Syntax:**
+- Check each entry in `cleo_operations_referenced`
+- Validate against the known valid operations in cleo-ecosystem-rules.md §Rule 2
+- ERROR for any invalid domain.operation reference
+- SKIP if no CLEO operations are referenced
+
+**Rule 3 — Canonical Verb Compliance:**
+- Check `deprecated_verbs_found` and scan `body` text for deprecated verb usage when describing CLEO operations
+- WARN (not ERROR) for deprecated verb usage
+
+**Rule 4 — Non-Duplication:**
+- Read the `description` and `body` to understand what the skill does
+- Compare against CLEO's built-in capabilities
+- ERROR if skill is purely a thin wrapper over a single existing operation
+- Use judgment — most skills are fine
+
+**Rule 5 — Data Integrity:**
+- Scan `body` for direct `.cleo/` file path editing instructions
+- Look for patterns like "edit tasks.db", "modify .cleo/config.json directly", "open brain.db"
+- ERROR if found
+
+**Rule 6 — RCASD-IVTR+C Lifecycle Alignment:**
+- Check if skill touches pipeline/lifecycle operations
+- Verify it references the relevant lifecycle stages
+- WARN (not ERROR) if alignment is missing
+
+**Rule 7 — Purpose Clarity:**
+- Evaluate the `description` and `body` for clarity and boundedness
+- Is the scope specific? Is the value proposition clear?
+- ERROR if purpose is contradictory or completely undefined
+- WARN if scope is too broad
+
+**Rule 8 — Tools Alignment:**
+- Compare `allowed_tools` against what the skill's body actually needs
+- WARN if mismatched
+
+### Step 3: Compute Overall Verdict
+
+- `PASS` — No ERROR rules
+- `PASS_WITH_WARNINGS` — No ERROR rules, but 1+ WARN rules
+- `FAIL` — 1+ ERROR rules
+
+### Step 4: Write ecosystem-check.json
+
+Save to the path specified in your prompt (default: `ecosystem-check.json` in the workspace).
+
+## Output Format
+
+```json
+{
+  "skill_name": "ct-skill-validator",
+  "verdict": "PASS|PASS_WITH_WARNINGS|FAIL",
+  "rules": [
+    {
+      "rule_id": 1,
+      "rule_name": "Domain Fit",
+      "status": "OK|WARN|ERROR|SKIP",
+      "finding": "Skill clearly serves the 'tools' and 'check' domains — its purpose is validating skill structure and ecosystem compliance.",
+      "evidence": "Body references 'tools.skill.verify', description mentions auditing skills, references validation rules."
+    },
+    {
+      "rule_id": 2,
+      "rule_name": "MCP Operation Syntax",
+      "status": "ERROR",
+      "finding": "Skill references 'tools.skill.validate' which is not a valid CLEO operation. The correct operation is 'tools.skill.verify'.",
+      "evidence": "Line: 'Run `query tools.skill.validate <skill-name>`'"
+    }
+  ],
+  "summary": {
+    "errors": 1,
+    "warnings": 0,
+    "skipped": 2,
+    "passed": 5
+  },
+  "primary_domain": "tools",
+  "lifecycle_stages_served": ["Validation"],
+  "recommendations": [
+    "Replace 'tools.skill.validate' with 'tools.skill.verify' throughout the body",
+    "Add explicit mention of which lifecycle stage this skill supports"
+  ]
+}
+```
+
+## Field Descriptions
+
+- **verdict**: Overall compliance result
+- **rules[]**: One entry per rule evaluated (1-8)
+  - **rule_id**: Integer 1-8
+  - **rule_name**: Short rule name
+  - **status**: OK / WARN / ERROR / SKIP
+  - **finding**: What you found (specific, actionable)
+  - **evidence**: Exact text quoted from the skill that supports the finding
+- **summary**: Count of each status
+- **primary_domain**: The main CLEO domain this skill serves
+- **lifecycle_stages_served**: Which RCASD-IVTR+C stages this skill touches
+- **recommendations**: Ordered list of fixes, most important first
+
+## Guidelines
+
+- **Be specific**: Quote the exact text that is problematic. "The body mentions X" is not enough.
+- **One finding per rule**: Don't split a single rule into multiple entries.
+- **Distinguish ERROR from WARN**: ERROR means the skill cannot be deployed as-is. WARN means it should be improved but is not blocking.
+- **Give credit**: If a skill does something well, say so in the `finding` for that rule.
+- **No false positives**: Only flag real violations. A skill that doesn't use CLEO operations
+  at all should get SKIP on Rule 2, not ERROR.
+- **Actionable recommendations**: Every ERROR must have a concrete fix in recommendations.

package/skills/ct-skill-validator/assets/valid-skill-example.md

@@ -0,0 +1,13 @@
+# Valid SKILL.md Example (for reference)
+
+A minimal v2-compliant SKILL.md. Use when writing test fixtures or verifying validator output.
+
+---
+name: example-skill
+description: "Does X and Y. Use when the user needs Z."
+allowed-tools: Read, Bash(python *)
+---
+
+# Example Skill
+
+Brief body. Under 400 lines. No CLEO-only fields in frontmatter.

package/skills/ct-skill-validator/evals/eval_set.json

@@ -0,0 +1,14 @@
+[
+  {"query": "validate my skill against v2 standard", "should_trigger": true},
+  {"query": "check if this skill folder is v2 compliant", "should_trigger": true},
+  {"query": "audit the skill structure and frontmatter", "should_trigger": true},
+  {"query": "run v2 compliance check on ct-skill-creator", "should_trigger": true},
+  {"query": "is my SKILL.md missing required fields", "should_trigger": true},
+  {"query": "verify skill passes all CLEO validation tiers", "should_trigger": true},
+  {"query": "prepare skill for distribution, check for issues", "should_trigger": true},
+  {"query": "create a new skill from scratch", "should_trigger": false},
+  {"query": "write a Python script to parse JSON", "should_trigger": false},
+  {"query": "run the test suite for my TypeScript project", "should_trigger": false},
+  {"query": "commit my changes to git", "should_trigger": false},
+  {"query": "help me debug this import error in my code", "should_trigger": false}
+]

package/skills/ct-skill-validator/evals/evals.json

@@ -0,0 +1,52 @@
+{
+  "skill_name": "ct-skill-validator",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Validate the ct-skill-creator skill against the v2 standard and show me a full report",
+      "expected_output": "A complete tier-by-tier validation report showing pass/fail/warn status for ct-skill-creator, with an HTML report opened in the browser",
+      "expectations": [
+        "Claude runs validate.py against ct-skill-creator",
+        "The output shows results for all 5 tiers",
+        "Claude runs generate_validation_report.py to produce an HTML report",
+        "Claude tells the user the report path or opens it in the browser",
+        "The report correctly identifies PASS or FAIL based on actual skill contents"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Check if this skill folder is v2 compliant: packages/ct-skills/skills/ct-orchestrator",
+      "expected_output": "Validation results for ct-orchestrator with tier breakdown, and an HTML report",
+      "expectations": [
+        "Claude validates ct-orchestrator not some other skill",
+        "Tier 1 structure check runs",
+        "Tier 2 frontmatter quality check runs",
+        "Tier 3 body quality check runs",
+        "An HTML report is generated and presented to the user"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Audit the ct-skill-validator skill itself — run all checks and give me a full findings report",
+      "expected_output": "Full self-audit of ct-skill-validator including validate gauntlet and audit_body, with HTML report",
+      "expectations": [
+        "Claude runs validate.py against ct-skill-validator",
+        "Claude runs audit_body.py for the deep body quality audit",
+        "An HTML report combining all findings is generated",
+        "Claude opens or links the HTML report for the user",
+        "The result correctly reflects ct-skill-validator's actual compliance status"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "Run the manifest alignment check for ct-skill-validator against the CLEO manifest",
+      "expected_output": "Manifest alignment results showing whether ct-skill-validator is registered correctly in manifest.json and dispatch-config.json",
+      "expectations": [
+        "Claude passes --manifest to validate.py or check_manifest.py",
+        "The manifest.json path is correctly resolved",
+        "The output shows Tier 4 CLEO Integration results",
+        "Claude reports whether the skill is found in manifest.json"
+      ]
+    }
+  ]
+}

package/skills/ct-skill-validator/manifest-entry.json

@@ -0,0 +1,20 @@
+{
+  "_comment": "CLEO-only metadata -- add to packages/ct-skills/skills/manifest.json",
+  "name": "ct-skill-validator",
+  "version": "1.0.0",
+  "tier": 2,
+  "token_budget": 6000,
+  "capabilities": {
+    "inputs": [],
+    "outputs": [],
+    "dispatch_triggers": [],
+    "compatible_subagent_types": ["general-purpose"],
+    "chains_to": [],
+    "dispatch_keywords": { "primary": [], "secondary": [] }
+  },
+  "constraints": {
+    "max_context_tokens": 60000,
+    "requires_session": false,
+    "requires_epic": false
+  }
+}

package/skills/ct-skill-validator/references/cleo-ecosystem-rules.md

@@ -0,0 +1,163 @@
+# CLEO Ecosystem Rules for Skill Compliance
+
+This reference defines the rules a skill must meet to be valid within the CLEO ecosystem.
+Used by the ecosystem-checker agent. Derived from CLEO-OPERATION-CONSTITUTION.md and CLEO-VISION.md.
+
+---
+
+## Rule 1: Domain Fit (REQUIRED)
+
+The skill must serve or extend at least one of CLEO's **10 canonical domains**:
+
+| Domain | Purpose |
+|--------|---------|
+| `tasks` | Task hierarchy, CRUD, dependencies, work tracking |
+| `session` | Session lifecycle, decisions, assumptions, context |
+| `memory` | Cognitive memory: observations, decisions, patterns, learnings (brain.db) |
+| `check` | Schema validation, protocol compliance, test execution |
+| `pipeline` | RCASD-IVTR+C lifecycle stages, manifest ledger, release management |
+| `orchestrate` | Multi-agent coordination, wave planning, parallel execution |
+| `tools` | Skills, providers, issues, CAAMP catalog |
+| `admin` | Configuration, backup, migration, diagnostics, ADRs |
+| `nexus` | Cross-project coordination, registry, dependency graph |
+| `sticky` | Ephemeral project-wide capture, quick notes |
+
+**Fail condition**: Skill has no clear connection to any canonical domain.
+**Warn condition**: Skill touches multiple domains without a clear primary domain.
+
+---
+
+## Rule 2: MCP Operation Syntax (REQUIRED if CLEO ops referenced)
+
+Any CLEO MCP operations referenced in the skill body must use canonical format:
+
+```
+query { domain: "...", operation: "..." }
+mutate { domain: "...", operation: "..." }
+```
+
+Or the abbreviated shorthand: `query tasks.show`, `mutate memory.observe`
+
+**Invalid references**: Operations not listed in the CLEO-OPERATION-CONSTITUTION.md are errors.
+
+**Common valid operations to recognize:**
+- `query tasks.show`, `query tasks.find`, `query tasks.list`, `query tasks.next`
+- `mutate tasks.add`, `mutate tasks.update`, `mutate tasks.complete`
+- `query session.status`, `mutate session.start`, `mutate session.end`
+- `query memory.find`, `query memory.timeline`, `query memory.fetch`, `mutate memory.observe`
+- `query admin.dash`, `query admin.health`, `query admin.help`
+- `query check.schema`, `mutate check.test.run`
+- `query pipeline.stage.status`, `mutate pipeline.manifest.append`
+- `query tools.skill.list`, `query tools.skill.show`
+- `query orchestrate.status`, `mutate orchestrate.spawn`
+
+**Fail condition**: Skill references a domain.operation that does not exist in the constitution.
+
+---
+
+## Rule 3: Canonical Verb Compliance (REQUIRED)
+
+Skills must use canonical verbs when describing CLEO operations or commands:
+
+**Approved verbs**: add, show, find, list, update, delete, archive, restore, complete,
+start, stop, end, status, record, resume, suspend, reset, init, enable, disable, backup,
+migrate, inject, run, link, observe, store, fetch, plan, sync, verify, validate, timeline,
+convert, unlink
+
+**Deprecated verbs** (must NOT appear when describing CLEO operations):
+- `create` → use `add`
+- `get` → use `show` or `fetch`
+- `search` → use `find`
+- `query` as a verb (e.g., "query the tasks") → use `find` or `list`
+
+**Warn condition**: Skill uses deprecated verbs in its own instructions for CLEO operations.
+
+---
+
+## Rule 4: Non-Duplication (REQUIRED)
+
+Skills must not re-implement functionality already provided by CLEO's MCP operations.
+
+**Check**: If a skill's primary function is to do something CLEO can already do via a
+single `query` or `mutate` call, that is duplication. Skills add value by composing
+multiple operations, providing domain expertise, or automating multi-step workflows.
+
+**Valid**: "Run 5 CLEO operations in sequence with business logic between them"
+**Invalid**: "Calls `tasks.show` and returns the result" (already exists as `query tasks.show`)
+
+**Fail condition**: Skill is a thin wrapper over a single existing CLEO operation with no added logic.
+
+---
+
+## Rule 5: Data Integrity (REQUIRED if touching .cleo/ data)
+
+If the skill reads or writes `.cleo/` data stores:
+- Reads must use `query` gateway
+- Writes must use `mutate` gateway
+- Direct file editing of `.cleo/*.json`, `tasks.db`, `brain.db` is NOT acceptable
+- Skills must not bypass CLEO's atomic write requirements
+
+**Fail condition**: Skill instructs direct editing of `.cleo/` data files.
+
+---
+
+## Rule 6: RCASD-IVTR+C Lifecycle Alignment (RECOMMENDED)
+
+Skills that interact with project work should align with CLEO's lifecycle pipeline stages:
+
+| Stage | Meaning |
+|-------|---------|
+| Research (R) | Gather information |
+| Consensus (C) | Validate recommendations |
+| Architecture Decision (A) | Document choices (ADRs) |
+| Specification (S) | Formal requirements |
+| Decomposition (D) | Break into tasks |
+| Implementation (I) | Write code |
+| Validation (V) | Verify implementation |
+| Testing (T) | Test coverage |
+| Release (R) | Ship with provenance |
+
+**Warn condition**: Skill that touches pipeline/lifecycle operations doesn't reference the relevant stages.
+
+---
+
+## Rule 7: Purpose Clarity (REQUIRED)
+
+The skill must have a **specific, bounded purpose** that is genuinely useful within CLEO workflows.
+
+Questions to evaluate:
+- What specific problem does this skill solve for a CLEO user?
+- Is the scope clearly bounded or is it trying to do everything?
+- Would a CLEO user know when to invoke this skill vs. using a different tool?
+- Does the skill description (frontmatter) accurately convey its purpose and trigger conditions?
+
+**Fail condition**: Skill purpose is vague, contradictory, or so broad it provides no focused value.
+**Warn condition**: Skill scope is wider than needed for its stated purpose.
+
+---
+
+## Rule 8: Tools Alignment (RECOMMENDED)
+
+The `allowed-tools` frontmatter should match the skill's actual needs:
+
+| Skill type | Expected tools |
+|-----------|----------------|
+| Read-only CLEO data | `Bash` (for `cleo` CLI) or implicit MCP query |
+| CLEO data modification | Includes write-capable tools |
+| File system operations | `Read`, `Write`, `Edit`, `Glob`, `Grep` |
+| Python scripts | `Bash(python *)` |
+| Agent orchestration | No tools, or `Agent` |
+| Validation/compliance | `Bash(python *)` for validators |
+
+**Warn condition**: `allowed-tools` is overly broad (e.g., `Bash` with no restrictions for a read-only skill).
+
+---
+
+## Severity Levels
+
+| Level | Meaning |
+|-------|---------|
+| `ERROR` | Hard failure — skill must be fixed before it is valid for CLEO ecosystem |
+| `WARN` | Non-blocking issue — skill can still be used but should be addressed |
+| `OK` | Passes this rule |
+| `SKIP` | Rule not applicable to this skill type |