claude-dev-env 1.0.0

package/skills/rule-audit/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: rule-audit
+description: Audit AGENTS.md, rules, hooks, and docs across user and project layers for enforcement gaps, duplication, and compliance
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Rule Audit
+
+Full enforcement audit of AGENTS.md, `.Codex/rules/`, hooks (settings.json), and referenced docs.
+
+Works across **two layers** — user-global (`~/.Codex/`) and project-local (cwd). Detects cross-layer duplication where project rules restate user rules, wasting instruction budget.
+
+Produces a scored report with corrective actions.
+
+## Phase 0: Layer Detection
+
+Before launching agents, detect which layers exist:
+
+```
+User layer (always present):
+  ~/.Codex/AGENTS.md
+  ~/.Codex/rules/*.md
+  ~/.Codex/settings.json (hooks)
+  ~/.Codex/docs/*.md
+
+Project layer (check cwd):
+  <cwd>/AGENTS.md
+  <cwd>/.Codex/AGENTS.md
+  <cwd>/.Codex/rules/*.md
+  <cwd>/.Codex/settings.json (project hooks)
+
+If cwd == ~ (home directory), skip project layer (same as user layer).
+If no project-layer files exist, report "single-layer audit (user only)".
+If project-layer files exist, report "dual-layer audit (user + project)".
+```
+
+## Phase 1: Inventory (Parallel Discovery)
+
+Launch 3 agents in parallel to inventory the full enforcement landscape.
+
+If dual-layer: each agent inventories BOTH layers, tagging each file with its layer (`user` or `project`).
+
+### Agent 1: Rules & AGENTS.md Inventory
+
+Read and catalog every advisory-layer file:
+
+```
+User layer:
+  ~/.Codex/AGENTS.md
+  ~/.Codex/rules/*.md
+
+Project layer (if exists):
+  <cwd>/AGENTS.md
+  <cwd>/.Codex/AGENTS.md
+  <cwd>/.Codex/rules/*.md
+
+For EACH file, extract:
+  - file_path
+  - layer (user | project)
+  - line_count
+  - purpose (1-sentence summary of what this file tries to enforce)
+  - rules (list of individual rules/instructions, one per line)
+  - framing (count of negative rules using "never/don't/do not/no" vs positive rules)
+  - has_rationale (does each rule explain WHY?)
+  - has_code_examples (are commands in code fences?)
+  - duplicates (rules that appear in multiple files -- list which files AND which layers)
+```
+
+Output as structured markdown to the conversation.
+
+### Agent 2: Hook Inventory
+
+Read settings.json hooks config and each referenced hook script:
+
+```
+User hooks:
+  ~/.Codex/settings.json
+  ~/.Codex/hooks/**/*.py
+
+Project hooks (if <cwd>/.Codex/settings.json exists):
+  <cwd>/.Codex/settings.json
+  <cwd>/.Codex/hooks/**/*.py
+
+For EACH hook entry in settings.json (both layers):
+  - layer (user | project)
+  - event (PreToolUse, PostToolUse, SessionStart, etc.)
+  - matcher
+  - hook_script_path (extract from the command string after the last quote)
+  - Read the actual script file
+  - purpose (what rule does this hook enforce?)
+  - enforcement_type: "blocking" (exit 2 / permissionDecision deny) | "advisory" (stdout message) | "validation" (post-check)
+  - method: "exit_code_2" (deprecated) | "permissionDecision" (current) | "stdout" | "other"
+  - which_rule_file (which .Codex/rules/*.md or AGENTS.md rule does this correspond to?)
+  - orphaned (hook exists on disk but NOT in settings.json?)
+```
+
+Also check for hook scripts on disk that are NOT referenced in settings.json (orphaned hooks).
+
+### Agent 3: Docs Inventory
+
+Read referenced documentation files:
+
+```
+User docs:
+  ~/.Codex/docs/*.md (glob to discover all)
+
+Project docs (if exists):
+  <cwd>/.Codex/docs/*.md
+
+For EACH file:
+  - file_path
+  - layer (user | project)
+  - line_count
+  - purpose
+  - loaded_when (is this always loaded, or on-demand via reference?)
+  - overlaps_with (which rules/*.md files cover the same topics?)
+  - hook_enforced (which rules in this doc are enforced by hooks vs purely advisory?)
+```
+
+## Phase 2: Cross-Reference Analysis
+
+After all 3 agents return, analyze the combined inventory:
+
+### 2A: Duplication Map
+
+Build a matrix of where each concept appears:
+
+```
+| Rule/Concept | AGENTS.md | rules/*.md | docs/*.md | hooks | Count |
+|---|---|---|---|---|---|
+| TDD first | line 52, 92 | tdd.md | - | tdd-enforcer.py | 3 advisory + 1 hook |
+| No magic values | - | code-standards.md | CODE_RULES.md:49 | code-rules-enforcer.py | 2 advisory + 1 hook |
+| ... | ... | ... | ... | ... | ... |
+```
+
+Flag any concept appearing 3+ times across advisory files (duplication tax on instruction budget).
+
+### 2B: Enforcement Gap Analysis
+
+For each rule/concept, classify its enforcement level:
+
+```
+| Level | Description | Example |
+|---|---|---|
+| ENFORCED | Hook blocks the action deterministically | destructive-command-blocker.py |
+| VALIDATED | PostToolUse checks after the fact | mypy_validator.py, auto-formatter.py |
+| ADVISORY | In AGENTS.md/rules but no hook backs it | most rules |
+| REDUNDANT | Codex already does this by default | "write clean code" |
+| ORPHANED | Hook exists but no corresponding rule | hook with no rule backing |
+```
+
+### 2C: Formatting Compliance Score
+
+Score each rule file against research-backed criteria:
+
+```
+| Criterion | Weight | Description |
+|---|---|---|
+| Positive framing | 25% | % of rules using positive "do X" vs negative "don't X" |
+| Rationale included | 20% | % of rules with WHY explanation |
+| Actionable | 20% | % of rules an agent could execute without interpretation |
+| Concise | 15% | Line count relative to unique rule count (lower = better) |
+| Code fences | 10% | Commands in code fences vs prose |
+| No duplication | 10% | % of rules NOT duplicated elsewhere |
+```
+
+Score: 0-100 per file. Weight by instruction count contribution.
+
+### 2D: Cross-Layer Duplication (dual-layer only)
+
+If both user and project layers exist, compare them:
+
+```
+| Rule/Concept | User Layer File | Project Layer File | Verdict |
+|---|---|---|---|
+| TDD first | code-standards.md | AGENTS.md line 5 | DUPLICATE — remove from project |
+| No magic values | code-standards.md | rules/code-quality.md | DUPLICATE — remove from project |
+| Use pytest fixtures | (not present) | rules/testing.md | PROJECT-ONLY — keep |
+| Django migrations | docs/DJANGO_PATTERNS.md | AGENTS.md line 22 | DUPLICATE — remove from project |
+```
+
+Verdicts:
+- **DUPLICATE**: Rule exists in both layers. Project copy wastes budget. Remove from project unless it narrows/overrides the user rule.
+- **OVERRIDE**: Project rule intentionally changes a user rule (e.g., user says "use pytest", project says "use unittest"). Keep and document.
+- **PROJECT-ONLY**: Rule exists only in project layer. Keep — it's project-specific.
+- **USER-ONLY**: Rule exists only in user layer. Expected for cross-cutting rules.
+
+### 2E: Combined Budget Analysis
+
+Calculate the total instruction count across all loaded files from BOTH layers:
+
+```
+User layer:
+  ~/.Codex/AGENTS.md:         ~X instructions
+  ~/.Codex/rules/*.md total:  ~Y instructions
+  ~/.Codex/docs (if loaded):  ~Z instructions
+
+Project layer (if exists):
+  <cwd>/AGENTS.md:             ~A instructions
+  <cwd>/.Codex/AGENTS.md:     ~B instructions
+  <cwd>/.Codex/rules/*.md:    ~C instructions
+
+COMBINED TOTAL:                ~N instructions
+Cross-layer duplicates:        ~D instructions (wasted)
+Effective total:               ~(N - D) instructions
+
+Research ceiling:  150 instructions (compliance degrades beyond this) [Source 1]
+Budget remaining:  150 - (N - D) = deficit/surplus
+```
+
+## Phase 3: Corrective Action Plan
+
+Generate a priority-ordered action plan:
+
+### Priority 1: Cut (Remove or Merge)
+
+Items that waste instruction budget:
+- Rules Codex already follows by default (REDUNDANT)
+- Rules duplicated 3+ times across files (consolidate to ONE location)
+- Rules in AGENTS.md that belong in scoped rules/*.md files
+- Docs content that duplicates rules content
+
+### Priority 2: Rewrite (Improve Formatting)
+
+Items scored below 60/100 in formatting compliance:
+- Flip negative rules to positive framing
+- Add rationale where missing
+- Put commands in code fences
+- Make vague rules actionable
+
+### Priority 3: Promote (Advisory -> Enforced)
+
+Rules that SHOULD have hook enforcement but don't:
+- High-violation rules that Codex repeatedly ignores
+- Rules with deterministic criteria (can be pattern-matched)
+- Safety-critical rules where violation has real cost
+
+For each, specify:
+- Which hook event (PreToolUse, PostToolUse, Stop)
+- Blocking vs advisory
+- Pattern to match
+- Estimated implementation effort
+
+### Priority 4: Demote (Enforced -> Removed)
+
+Hooks that add latency without value:
+- Hooks that never fire (check if the pattern is too narrow)
+- Advisory hooks that could be rules instead
+- Hooks using deprecated methods (exit code 2 instead of permissionDecision)
+
+### Priority 5: Deduplicate Across Layers (dual-layer only)
+
+For each DUPLICATE from 2D:
+- If project rule is identical to user rule: delete from project
+- If project rule narrows user rule: keep in project, add comment referencing user rule
+- If project rule conflicts with user rule: flag for user decision (OVERRIDE vs mistake)
+
+### Priority 6: Restructure
+
+Optimal placement recommendations:
+- What stays in AGENTS.md (critical, cross-cutting, <50 lines target)
+- What moves to rules/*.md (domain-specific, scopable)
+- What moves to skills (on-demand workflows, not always relevant)
+- What becomes a hook (deterministic enforcement)
+
+## Phase 4: Output
+
+Write the audit report to the Obsidian vault:
+
+**Path:** `sessions/[Project] Rule Audit [date].md`
+
+**Format:**
+
+```markdown
+---
+tags: [audit, rules, enforcement, Codex]
+date: YYYY-MM-DD
+type: rule-audit
+---
+
+## Rule Audit Report -- [Date]
+
+### Inventory Summary
+[File counts, total instruction count, budget analysis]
+
+### Duplication Map
+[Table from 2A]
+
+### Enforcement Gaps
+[Table from 2B -- sorted by risk level]
+
+### Formatting Scores
+[Table from 2C -- sorted by score ascending]
+
+### Corrective Actions
+[Numbered list from Phase 3, grouped by priority]
+
+### Implementation Checklist
+[ ] Priority 1 items (with specific file edits)
+[ ] Priority 2 items (with before/after examples)
+[ ] Priority 3 items (with hook specifications)
+[ ] Priority 4 items (with removal justification)
+[ ] Priority 5 items (with move-from/move-to)
+```
+
+Present the report to the user and ask which priorities to tackle first.

package/skills/rule-creator/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: rule-creator
+description: "Creates or hardens Codex rules in .Codex/rules/*.md. Analyzes behavioral patterns and converts them into persistent, enforceable rule files. Triggers: 'create rule', 'add rule', 'harden rule', 'enforce rule', 'new rule'."
+---
+
+# Rule Creator
+
+## Overview
+
+Creates well-structured `.Codex/rules/*.md` files that Codex loads into every session.
+
+**Core principle:** Rules encode "always true" behaviors. A rule eliminates repeated manual prompting by making the instruction persistent and automatic.
+
+**Announce at start:** "I'm using the rule-creator skill to [create/harden] a rule."
+
+**Context:** Rules are loaded at session start. They complement AGENTS.md (high-level project instructions) and skills (on-demand workflows). Use rules for behavioral constraints that must always be active.
+
+## The Process
+
+### Step 1: Understand the Need
+
+Before writing, clarify:
+
+1. **What behavior** should this rule enforce or prevent?
+2. **Why** is it needed? (What goes wrong without it? What do you manually correct?)
+3. **Scope** — all projects (`~/.Codex/rules/`) or project-specific (`.Codex/rules/`)?
+4. **Path-scoped?** — does it only apply to certain file types?
+
+### Step 2: Check for Overlap
+
+Search existing rules before creating a new one:
+
+1. Read `~/.Codex/rules/*.md` and `.Codex/rules/*.md`
+2. Read AGENTS.md for related instructions
+3. If overlap exists: **harden the existing rule** instead of creating a duplicate
+
+### Step 3: Write the Rule
+
+Follow these principles from Anthropic's prompting best practices and Codex docs:
+
+**Structure:**
+- Optional YAML frontmatter (only if path-scoped or needs `alwaysApply`)
+- Markdown with headers and bullets
+- Target under 50 lines per rule file (rules are loaded every session — token cost matters)
+
+**Writing principles (source: [Anthropic Prompting Best Practices](https://platform.Codex.com/docs/en/build-with-Codex/prompt-engineering/Codex-prompting-best-practices)):**
+
+1. **Tell what TO do, not what NOT to do.** Positive instructions outperform negative ones.
+   - Instead of: "Do not guess CSS selectors"
+   - Write: "Read the actual HTML source before writing any CSS selector"
+
+2. **Add context/motivation (WHY).** Codex generalizes from explanations.
+   - Instead of: "NEVER use ellipses"
+   - Write: "Never use ellipses because the text-to-speech engine cannot pronounce them"
+
+3. **Be specific enough to verify.** Vague rules get ignored.
+   - Instead of: "Write clean code"
+   - Write: "Use 2-space indentation, no trailing whitespace"
+
+4. **Use XML tags for critical constraints.** Wrap non-negotiable rules in semantic tags.
+   ```
+   <investigate_before_answering>
+   Read referenced files before making claims about their contents.
+   </investigate_before_answering>
+   ```
+
+5. **Dial back aggressive language for the current model.** The model overtriggers on "CRITICAL", "MUST", "ALWAYS" — use normal prompting unless enforcement truly requires it.
+
+**Frontmatter reference:**
+```yaml
+# Path-scoped rule (loads only when matching files are opened):
+---
+paths:
+  - "src/api/**/*.ts"
+---
+
+# Always-apply rule (loads every session, no conditions):
+# Simply omit frontmatter entirely — rules without frontmatter load unconditionally.
+
+# AVOID using alwaysApply: false — it makes the rule load-on-demand only,
+# which means it may never activate unless Codex happens to read matching files.
+```
+
+### Step 4: Choose Filename
+
+- Lowercase, hyphens only: `investigate-first.md`, `parallel-tools.md`
+- Descriptive of the behavior: name after what the rule DOES, not the problem it prevents
+- Match naming convention of existing rules in the target directory
+
+### Step 5: Validate
+
+Before writing the file:
+
+- [ ] Under 50 lines (concise enough to load every session without waste)
+- [ ] Positive instructions (tells what TO do)
+- [ ] Includes WHY context where non-obvious
+- [ ] Specific enough to verify compliance
+- [ ] No overlap with existing rules or AGENTS.md
+- [ ] No frontmatter if it should always load (omit = unconditional)
+- [ ] Path-scoped frontmatter only if genuinely file-type-specific
+
+### Step 6: Write and Confirm
+
+1. Write the rule to the target directory
+2. Show the user the final content for review
+3. Note: rules take effect on the NEXT session (Codex caches at startup)
+
+## Hardening Existing Rules
+
+When a rule exists but isn't being followed:
+
+1. **Check frontmatter** — `alwaysApply: false` prevents auto-loading. Remove it.
+2. **Check for conflicts** — contradictory rules in other files cause arbitrary behavior
+3. **Add WHY context** — unexplained rules get lower adherence
+4. **Reframe as positive** — convert "NEVER do X" to "Always do Y instead"
+5. **Add XML wrapper** — for critical rules, semantic tags improve parsing:
+   ```xml
+   <rule_name>
+   Instruction here.
+   </rule_name>
+   ```
+6. **Reduce aggressive language** — the current model overtriggers on "CRITICAL/MUST/ALWAYS". Use direct, normal language unless the rule truly requires absolute enforcement.
+
+## Red Flags — STOP
+
+- Rule duplicates something already in AGENTS.md or another rule
+- Rule is over 50 lines (split it or move details to a referenced doc)
+- Rule uses only negative instructions ("NEVER", "DON'T") without positive alternatives
+- Rule has `alwaysApply: false` for something that should always be active
+- Rule is too vague to verify ("write good code")
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "This is already in AGENTS.md" | If it's not being followed, it needs a dedicated rule with WHY context |
+| "The rule is short enough, no WHY needed" | WHY context improves adherence even for short rules — Codex generalizes from explanations |
+| "I'll use CRITICAL/MUST to make it stronger" | the current model overtriggers on aggressive language. Direct, calm instructions work better. |
+| "alwaysApply: false is fine, Codex will find it" | On-demand loading means the rule may never activate. Omit frontmatter for always-on rules. |
+
+## Remember
+
+- Omit frontmatter = always loads (this is what you want for most rules)
+- `alwaysApply: false` = on-demand only (use sparingly)
+- `paths:` frontmatter = loads when matching files are opened
+- Positive instructions > negative instructions
+- WHY context > bare commands
+- Under 50 lines per rule file
+- One behavior per rule file
+- Rules take effect next session

package/skills/skill-writer/REFERENCE.md

@@ -0,0 +1,246 @@
+# Skill Writer Reference
+
+## Table of Contents
+
+1. [Complete Frontmatter Fields](#complete-frontmatter-fields)
+2. [Progressive Disclosure Architecture](#progressive-disclosure-architecture)
+3. [Content Templates by Degree of Freedom](#content-templates)
+4. [Validation Checklist](#validation-checklist)
+
+---
+
+## Complete Frontmatter Fields
+
+Source: [Claude Code Skills](https://platform.claude.com/docs/en/claude-code/skills)
+
+### Required Fields
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `name` | string | Lowercase, hyphens, numbers. Max 64 chars. No `anthropic` or `claude`. | Must match directory name. Prefer gerund form. |
+| `description` | string | Max 1024 chars. Third person. No XML tags. | What it does + when to use it + trigger phrases. |
+
+### Optional Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `allowed-tools` | string | (all tools) | Tools permitted without asking. E.g., `Read, Grep, Bash(python *)` |
+| `context` | string | (inline) | Set to `fork` to run in isolated subagent (no conversation history) |
+| `agent` | string | (default) | Subagent type when `context: fork` is set |
+| `model` | string | (inherits) | Model override when skill is active |
+| `effort` | string | (inherits) | `low`, `medium`, `high`, or `max` (Opus only) |
+| `user-invocable` | boolean | `true` | Set `false` to hide from `/` menu (background knowledge only) |
+| `disable-model-invocation` | boolean | `false` | Set `true` for manual-only via `/name` |
+| `paths` | string/list | (all files) | Glob patterns limiting activation. E.g., `"*.py"` or `["*.ts", "*.tsx"]` |
+| `argument-hint` | string | (none) | Autocomplete hint. E.g., `[filename] [format]` |
+| `shell` | string | `bash` | Shell for `!`command`` blocks. `bash` or `powershell` |
+| `hooks` | object | (none) | Hooks scoped to this skill's lifecycle |
+
+### String Substitutions (available in SKILL.md body)
+
+| Variable | Description |
+|----------|-------------|
+| `$ARGUMENTS` | All arguments passed when invoking |
+| `$ARGUMENTS[N]` | Specific argument by 0-based index |
+| `$N` | Shorthand for `$ARGUMENTS[N]` (e.g., `$0`, `$1`) |
+| `${CLAUDE_SESSION_ID}` | Current session ID |
+| `${CLAUDE_SKILL_DIR}` | Directory containing SKILL.md |
+| `` !`command` `` | Dynamic context injection - shell command runs before Claude sees content |
+
+### Permission Syntax
+
+```
+Skill(name)        # Allow exact skill
+Skill(name *)      # Allow skill with any arguments
+```
+
+---
+
+## Progressive Disclosure Architecture
+
+Source: [Agent Skills Overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
+
+Skills load in three levels to minimize context usage:
+
+| Level | What Loads | Token Cost | When |
+|-------|-----------|------------|------|
+| **1. Metadata** | `name` and `description` from frontmatter | ~100 tokens | Always (system prompt) |
+| **2. Instructions** | SKILL.md body | <5k tokens | When triggered by matching request |
+| **3. Resources** | Additional files, scripts, schemas | Unlimited | When referenced from instructions |
+
+### Key implications:
+- You can install many skills with minimal context cost (~100 tokens each)
+- SKILL.md body should stay under 500 lines
+- Scripts execute via bash - their code never enters context, only output does
+- Reference files load only when Claude reads them
+
+---
+
+## Content Templates
+
+### High Freedom (Advisory)
+
+Best for guidance where multiple approaches are valid.
+
+```markdown
+---
+name: analyzing-data
+description: "Analyzes datasets and generates statistical summaries. Use when working with CSV or Excel data requiring descriptive statistics, correlations, or visualizations."
+---
+
+# Analyzing Data
+
+## Overview
+
+Performs statistical analysis on tabular datasets.
+
+**Announce at start:** "I'm using the analyzing-data skill."
+
+## Instructions
+
+1. Load and inspect the data structure
+2. Generate descriptive statistics
+3. Identify correlations and patterns
+4. Produce visualizations if requested
+
+## Examples
+
+**Input:** "Analyze sales_2024.csv for trends"
+**Output:** Summary statistics, monthly trend chart, top performers
+
+## Best Practices
+
+- Always show data shape and types before analysis
+- Handle missing values explicitly
+- Use appropriate chart types for the data
+```
+
+### Medium Freedom (Structured Workflow)
+
+Best for preferred patterns with some variation allowed.
+
+```markdown
+---
+name: reviewing-plans
+description: "Validates implementation plans against code standards, TDD compliance, and right-sized engineering. Use after writing plans and before executing them. Triggers: 'review plan', 'validate plan', 'check plan'."
+---
+
+# Reviewing Plans
+
+## Overview
+
+**Core principle:** Bad plans produce bad code. Review before you execute.
+
+**Announce at start:** "I'm using the reviewing-plans skill to validate this plan."
+
+**Context:** Use after write-plan and before plan-executor. Quality gate between planning and implementation.
+
+## The Process
+
+### Step 1: Identify Plan Files
+Locate plan files in `.planning/phases/` or `docs/plans/`.
+
+### Step 2: Review Dimensions
+Check structure, TDD compliance, code quality, right-sized engineering, task granularity.
+
+### Step 3: Report Verdict
+READY or NEEDS REVISION with specific issues.
+
+## Output Format
+
+| Dimension | Status |
+|-----------|--------|
+| Structure | PASS/FAIL |
+| TDD | PASS/FAIL |
+| Code quality | PASS/FAIL |
+
+## Red Flags - STOP
+
+- Any placeholder text ("implement later")
+- Missing TDD steps for production code
+- Magic values in code blocks
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "The plan is high-level" | Plans without complete code produce inconsistent implementations |
+| "TDD makes it too long" | TDD in plan prevents skipping TDD during execution |
+```
+
+### Low Freedom (Critical/Exact)
+
+Best for fragile operations where consistency is critical.
+
+```markdown
+---
+name: filling-pdf-forms
+description: "Fills PDF forms using pdf-lib JavaScript library with exact field mapping. Use when populating PDF forms programmatically. Triggers: 'fill PDF form', 'populate form', 'form filling'."
+allowed-tools: Bash(node *), Read
+---
+
+# Filling PDF Forms
+
+## MANDATORY PROTOCOL
+
+Before filling ANY form:
+1. [ ] Read `${CLAUDE_SKILL_DIR}/FORMS.md` for field mapping reference
+2. [ ] Extract field names: `node ${CLAUDE_SKILL_DIR}/scripts/extract_fields.js input.pdf`
+3. [ ] Match extracted fields against the mapping
+
+## Workflow
+
+### Step 1: Extract Fields
+```bash
+node ${CLAUDE_SKILL_DIR}/scripts/extract_fields.js "$0"
+```
+
+### Step 2: Generate Fill Script
+Use the field mapping from FORMS.md. Every field must be explicitly set.
+
+### Step 3: Execute and Validate
+```bash
+node fill_script.js && node ${CLAUDE_SKILL_DIR}/scripts/validate_fill.js output.pdf
+```
+
+### Feedback Loop
+If validation fails -> read error output -> fix field mapping -> re-execute -> re-validate.
+
+## Critical Rules
+
+**NEVER guess field names.** Always extract first.
+**WHY:** Wrong field names silently produce empty forms.
+```
+
+---
+
+## Validation Checklist
+
+Source: [Best Practices Checklist](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+
+### Core Quality
+- [ ] Description is specific, includes key terms, and is in **third person**
+- [ ] Description includes both what the Skill does and when to use it
+- [ ] SKILL.md body is **under 500 lines**
+- [ ] Additional details are in separate files (if needed)
+- [ ] No time-sensitive information (or clearly marked as legacy)
+- [ ] Consistent terminology throughout
+- [ ] Examples are concrete, not abstract
+- [ ] File references are **one level deep** from SKILL.md
+- [ ] Files >100 lines have a **table of contents**
+- [ ] Workflows have clear steps
+- [ ] All file paths use **forward slashes**
+
+### Code and Scripts
+- [ ] Scripts solve problems rather than punt to Claude
+- [ ] Error handling is explicit and helpful
+- [ ] No "voodoo constants" (all values justified)
+- [ ] Required packages listed and verified as available
+- [ ] MCP tools use **fully qualified names** (`ServerName:tool_name`)
+- [ ] Validation/verification steps for critical operations
+- [ ] Feedback loops included for quality-critical tasks
+
+### Testing
+- [ ] At least 3 evaluation scenarios created
+- [ ] Tested with representative real tasks
+- [ ] If multi-model: tested with Haiku, Sonnet, and Opus