# Validate Chalk

> Validate chalk.json schema and docs completeness — check that project context is sufficient for skills to operate

- Skill: `majiayu000/validate-chalk` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/validate-chalk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/validate-chalk/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/validate-chalk

---


Audit the `.chalk/` directory to verify that `chalk.json` and PROFILE docs are complete, correct, and sufficient for skills to operate. Reports gaps and optionally fixes them.

## When to Use

- Before running skills that depend on project context (capture-pr-visuals, create-pr, etc.)
- After initial setup to verify completeness
- Periodically to detect stale docs
- In CI to enforce chalk quality

## Workflow

### Step 1: Check chalk.json exists and is valid

1. Read `.chalk/chalk.json`
2. Validate required fields:
   - `version` — must be `"1.0"`
   - `project.name` — must exist and be non-empty
3. Check recommended fields and report if missing:
   - `project.description`, `project.language`, `project.framework`, `project.type`
   - `dev.command`, `dev.port`, `dev.url`
   - `test.command`
   - `build.command`
   - `routes` — at least one route
   - `sourceLayout.root`
4. Validate field values make sense:
   - `dev.port` is a valid port number (1-65535)
   - `dev.url` starts with `http`
   - `routes[].path` and `routes[].name` are non-empty
   - `sourceLayout` paths exist on disk

### Step 2: Check PROFILE docs exist

Verify these files exist:
- `.chalk/docs/product/PROFILE.md`
- `.chalk/docs/engineering/PROFILE.md`
- `.chalk/docs/engineering/coding-style.md`
- `.chalk/docs/ai/PROFILE.md`
- `.chalk/docs/design/PROFILE.md`

For each file:
- Check it exists
- Check it has more than 20 lines of content (not just stubs)
- Check it doesn't contain `<!-- STUB -->` markers
- Check it has a `Last updated:` line

### Step 3: Check for v1 legacy structure

Detect old numbered files that should have been migrated:
- `0_PRODUCT_PROFILE.md`, `0_ENGINEERING_PROFILE.md`, `1_architecture.md`, `3_techstack.md`, etc.
- If found, warn that migration is needed and suggest running `/setup-chalk` with migration

### Step 4: Cross-validate chalk.json against docs

- If `chalk.json` lists routes, check that `engineering/PROFILE.md` mentions them
- If `chalk.json` lists a framework, check that `engineering/PROFILE.md` documents it
- If `chalk.json` has `sourceLayout`, verify the directories actually exist on disk

### Step 5: Report

Print a summary:

```
Chalk Validation Report
=======================

chalk.json:
  ✓ version: 1.0
  ✓ project.name: my-app
  ✓ project.framework: next
  ✗ routes: missing (run /setup-docs to detect)
  ✗ test.command: missing

Docs:
  ✓ product/PROFILE.md (142 lines, updated 2026-03-10)
  ✓ engineering/PROFILE.md (298 lines, updated 2026-03-10)
  ✗ engineering/coding-style.md: MISSING
  ✓ ai/PROFILE.md (87 lines, updated 2026-03-10)
  ⚠ design/PROFILE.md: contains STUB markers

Legacy:
  ⚠ Found 0_ENGINEERING_PROFILE.md — migration needed

Score: 7/11 checks passed
```

### Step 6: Auto-fix (if `fix` argument provided)

If the user passed `fix` as an argument:
- Run `/setup-docs` to populate missing PROFILE docs
- Run route detection to fill `chalk.json` routes
- Run source layout detection to fill `chalk.json` sourceLayout
- Migrate v1 files if found (with user confirmation)

## Rules

- Never modify files without the `fix` argument — report-only by default
- Don't fail on missing optional fields — just warn
- Required fields that cause failure: `chalk.json` must exist, `version` and `project.name` must be present
- Be specific about what's missing and how to fix it