---
name: skill-creation-update
description: Creates, validates and versions VFX Agent Skills against the skill constitution using template scripts (create_skill, validate_skill, test_skill). Use when creating or updating a skill, checking compliance, or bumping a skill version.
allowed-tools: Read,Write,Edit
---

# skill-creation-update

**Skill Version:** 1.3.1
**Last Updated:** 2026-10-09
**Dependencies:** Python 3.12+, VFX_SKILL_CONSTITUTION.md (v2.0.0+)
**Status:** Production-ready

---

## Quick Start

### Create New Skill
```bash
python .claude\skills\skill-creation-update\scripts\create_skill.py houdini-hda-export \
  --description "Export Houdini Digital Assets for Unreal Engine" \
  --triggers "hda export,houdini to unreal" \
  --dependencies "Houdini 20+,UE 5.5+" \
  --model sonnet
```

### Validate Skill Compliance
```bash
# Validate Claude Code skill
python .claude\skills\skill-creation-update\scripts\validate_skill.py unreal-vfx-automation
# Output: Article I: [OK] PASS, Article III: [OK] PASS (470 lines), Overall: [OK] PASS

# Validate Agent OS standard
python .claude\skills\skill-creation-update\scripts\validate_skill.py unreal-engine-standards --agent-os
# Output: Agent OS Headers: [OK] PASS, Article III: [OK] PASS (414 lines), Overall: [OK] PASS
```

### Test with Multiple Targets (Article I)
```bash
python .claude\skills\skill-creation-update\scripts\test_skill.py unreal-vfx-automation \
  --targets Shot001,Shot002,Shot003
# Output: 3/3 passed [OK], Article I: [OK] VALIDATED
```

### Update Skill Version
```bash
python .claude\skills\skill-creation-update\scripts\update_skill.py unreal-vfx-automation \
  --version 1.1.0 \
  --changes "Added Sequencer integration"
# Output: [OK] Updated to 1.1.0, [OK] Compliance maintained
```

---

## Standard Workflows

### Workflow 1: Create New Skill from Template

**Steps:**
1. **Plan scope:** Identify repeatable workflow, verify 3+ projects can use it
2. **Run create_skill.py:**
   ```bash
   python .claude\skills\skill-creation-update\scripts\create_skill.py SKILL_NAME \
     --description "What + When + Triggers (Article VIII)" \
     --triggers "trigger1,trigger2,trigger3" \
     --dependencies "Required software" \
     --model sonnet
   ```
3. **Verify structure:**
   ```bash
   ls .claude/skills/SKILL_NAME/
   # Expected: SKILL.md, reference/, scripts/
   ```
4. **Fill SKILL.md sections:** Quick Start, Workflows (3-5), Troubleshooting (4-5 issues)
5. **Create reference docs:** Move detailed content to `reference/*.md`
6. **Validate line count:**
   ```bash
   wc -l .claude/skills/SKILL_NAME/SKILL.md
   # Must be <500 lines
   ```

**Output:** Complete skill directory with template populated

---

### Workflow 2: Validate Constitutional Compliance

**Steps:**
1. **Run validate_skill.py:**
   ```bash
   python .claude\skills\skill-creation-update\scripts\validate_skill.py SKILL_NAME
   ```
   **Pass the skill NAME, never a path.** Given a path it cannot find the
   skill and still prints `[OK] PASS (0/0 automated checks)` - a vacuous
   pass (2026-08-22). Also known: Article VIII enforces the retired
   emoji-template section list (Quick Start, Dependencies, Last Updated...),
   so current-style skills such as `wrap-session` FAIL it; treat an
   Article VIII-only failure as instrument drift, not a defect, until the
   validator is updated.
2. **Review report:**
   - Article I: No hard-coded paths detected [OK]
   - Article III: 470 lines <500 [OK]
   - Article IV: Independent testing documented [OK]
   - Article VI: 70% context reduction [OK]
   - Article VIII: All sections present [OK]
   - **Bundled scripts (manual, not in the validator yet):** every flag shown in a
     SKILL.md example (`python <skill-dir>/scripts/X.py --flag`) must appear in
     that script's `--help`. Run the help and diff against the doc. A documented
     flag argparse rejects is doc drift: qwen-delegate shipped a phantom `--file`
     and a dead default port for weeks because nobody ran the script from the doc
     (observation #4, 2026-09-01).
   - **Shipped defaults (manual, principle 9):** grep the skill's `scripts/` for
     drive letters, usernames and version-pinned install paths inside DEFAULTS
     blocks and module constants:
     `grep -nE "[A-Za-z]:[/\]|Users|[0-9]+[.][0-9]+ ?v[0-9]" scripts/*.py`.
     Every hit moves to a config file the workflow passes explicitly (layered,
     repeatable) or to an argument, and the run must PRINT the effective value
     so a wrong one is read back instead of trusted. A default baked into a
     shipped script is always somebody's personal path on somebody else's
     machine: nuke-shot-setup shipped a dead personal OCIO path and Nuke 15 as
     built-in defaults (observation #9, 2026-09-08).
   - **Scripts that walk a share or folder tree at run time (manual, principle 10):**
     a shipped script that enumerates a share or folder tree bypasses the agent's
     drive-policy hook, because the hook sees only the command line (which names
     no drive), not what the launched program opens. The script must apply the
     policy itself: allowlisted roots or the policy's folder pattern checked
     before it opens anything, and named folders opened directly instead of
     listing the root. Review every contributed script package against a hostile
     fixture - a folder it must not read (holding a marker line that must never
     appear in the output), a misnamed file, a character outside cp1252 - not
     against the author's examples. One such fixture caught all three faults in
     a roll-up script that the author's own examples had passed (observation
     #131, 2026-10-05).
3. **Address failures:**
   - Article I: Remove hard-coded paths, add params
   - Article III: Move details to reference docs
   - Article VIII: Add missing sections
4. **Re-validate:** Run validate_skill.py again until [OK] PASS
5. **Generate report:**
   ```bash
   python .claude\skills\skill-creation-update\scripts\validate_skill.py SKILL_NAME --report
   # Saves to: ClaudeCode/development/reports/SKILL_NAME_COMPLIANCE_REPORT.md
   ```

**Output:** Compliance report with pass/fail per article

---

### Workflow 3: Test with Multiple Projects (Article I)

**Steps:**
1. **Identify 3+ test targets:** Different projects/assets (e.g., Shot001, Shot002, Shot003)
2. **Run test_skill.py:**
   ```bash
   python .claude\skills\skill-creation-update\scripts\test_skill.py SKILL_NAME \
     --targets target1,target2,target3
   ```
3. **Review results:**
   - Test 1/3: target1 [OK] PASS (487ms)
   - Test 2/3: target2 [OK] PASS (502ms)
   - Test 3/3: target3 [OK] PASS (495ms)
   - Article I: [OK] VALIDATED
4. **Address failures:** Fix script bugs if any target fails
5. **Document testing:** Add to Constitutional Compliance section

**Output:** Test report with 100% pass rate, Article I validation

---

### Workflow 4: Update Existing Skill

**Steps:**
1. **Determine version increment:**
   - MAJOR (X.0.0): Breaking changes
   - MINOR (x.Y.0): New features (backward compatible)
   - PATCH (x.y.Z): Bug fixes
2. **Run update_skill.py:**
   ```bash
   # Minor update
   python .claude\skills\skill-creation-update\scripts\update_skill.py SKILL_NAME \
     --version 1.1.0 \
     --changes "Added feature X"

   # Major update (breaking)
   python .claude\skills\skill-creation-update\scripts\update_skill.py SKILL_NAME \
     --version 2.0.0 \
     --changes "BREAKING: Removed UE 4.27 support" \
     --breaking
   ```
3. **Review changelog entry:**
   ```markdown
   **v1.1.0** (2025-10-26) - Feature Update
   - Added: Feature X
   - Fixed: Bug Y
   ```
4. **Re-validate:** Automatic compliance check during update
5. **Test updated skill:** Re-run test_skill.py to verify

**Output:** Version incremented, changelog added, compliance maintained

---

## Troubleshooting

### Issue 1: "Skill Already Exists"

**Symptom:** `[FAIL] Error: Skill 'skill-name' already exists`

**Fix:**
```bash
# Option 1: Delete and recreate
rm -rf .claude/skills/skill-name
python .claude\skills\skill-creation-update\scripts\create_skill.py skill-name ...

# Option 2: Use update instead
python .claude\skills\skill-creation-update\scripts\update_skill.py skill-name --version 1.1.0
```

---

### Issue 2: "SKILL.md >500 Lines"

**Symptom:** `Article III: [FAIL] FAIL - SKILL.md: 547 lines (>500 limit)`

**Fix:**
1. **Identify verbose sections:**
   ```bash
   grep -n "^## " .claude/skills/SKILL_NAME/SKILL.md
   ```
2. **Move detailed content to reference:**
   - Troubleshooting too long (200 lines)? -> Move to `reference/troubleshooting_guide.md`, keep 4-5 issues (50 lines)
   - Workflows too detailed (300 lines)? -> Move to `reference/detailed_workflow.md`, keep summaries (150 lines)
3. **Add references:**
   ```markdown
   **For complete troubleshooting:** See reference/troubleshooting_guide.md
   ```
4. **Re-validate:**
   ```bash
   python .claude\skills\skill-creation-update\scripts\validate_skill.py SKILL_NAME
   # Should show: Article III: [OK] PASS
   ```

---

### Issue 3: "Hard-Coded Paths Detected"

**Symptom:** `Article I: [FAIL] FAIL - Hard-coded paths in scripts/export.py`

**Fix:**
```python
# [FAIL] WRONG
project_path = "C:\\Users\\Me\\UnrealProjects\\MyProject"

# [OK] CORRECT: Parameterized
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--project-path", required=True)
args = parser.parse_args()
project_path = args.project_path

# [OK] CORRECT: Relative
import os
script_dir = os.path.dirname(__file__)
project_path = os.path.join(script_dir, "..", "..", "Projects", "MyProject")

# [OK] CORRECT: Environment variable
project_path = os.getenv("UNREAL_PROJECT_PATH", "DefaultPath")
```

---

### Issue 4: "No Script Found" (Test Fails)

**Symptom:** `[FAIL] Error: No executable script found in scripts/`

**Fix:**
- **Documentation-only skills:** Skip test_skill.py (not applicable)
- **MCP-based skills:** Create test wrapper:
  ```python
  # scripts/test_wrapper.py
  import sys
  from mcp import client

  def test(target):
      result = client.call_tool("tool_name", {"target": target})
      return result["success"]

  if __name__ == "__main__":
      sys.exit(0 if test(sys.argv[1]) else 1)
  ```
- **Validation scripts:**
  ```python
  # scripts/validate.py
  import sys, os

  skill_md = os.path.join(os.path.dirname(__file__), "..", "SKILL.md")
  if not os.path.exists(skill_md):
      print("[FAIL] SKILL.md not found")
      sys.exit(1)

  with open(skill_md) as f:
      if len(f.readlines()) > 500:
          print("[FAIL] SKILL.md >500 lines")
          sys.exit(1)

  print("[OK] Valid")
  sys.exit(0)
  ```

---

## Reference Documentation

### Detailed Guides

**skill_template_guide.md** - Template structure, placeholders, best practices
**constitutional_validation.md** - Validation logic, regex patterns, edge cases

### Python Scripts

**create_skill.py** - Create new skill from template (CLI, template copying)
**validate_skill.py** - Validate constitutional compliance (9 articles)
**test_skill.py** - Test with multiple targets (Article I validation)
**update_skill.py** - Update version and changelog (SemVer)

**Detailed workflow documentation:** See `reference/skill_template_guide.md`

---

## Constitutional Compliance

### Article I: General Purpose Scripts [OK]
- create_skill.py works for ALL skill types (tested: vfx-documentation, unreal-vfx-automation, agent-creation-update)
- validate_skill.py validates ANY skill (no hard-coded skill names)
- test_skill.py tests ANY skill with scripts
- No per-skill script generation

### Article II: MCP vs Direct [OK]
- Complex workflows -> Direct Python scripts (not MCP tools)
- Multi-step processes (creation, validation, testing)
- Skill-specific logic (constitutional rules, line counting)

### Article III: Progressive Disclosure [OK]
- SKILL.md: 465 lines (<500 limit [OK])
- Margin: 35 lines (7% buffer)
- Reference docs: 2 files (on-demand loading)

### Article IV: Test Independently [OK]
- create_skill.py tested with test-skill (deleted after)
- validate_skill.py tested against all existing skills
- test_skill.py tested with unreal-vfx-automation
- update_skill.py tested with version increments

### Article V: Follow Official Patterns [OK]
- Python argparse (Python standard)
- JSON output (industry standard)
- Semantic versioning (SemVer 2.0)
- Markdown docs (GitHub standard)

### Article VI: Context Efficiency [OK]
**Context Reduction:**
```
Before: VFX_SKILL_CONSTITUTION (862) + VFX_SKILL_TEMPLATE (350) + VFX_AGENT_SKILLS_GUIDE (500) = 1,712 lines (~8,560 tokens)
After: Metadata (12) + SKILL.md (465) + Reference avg (300) = ~777 lines (3,885 tokens)
Savings: 73% reduction [OK]
```

### Article VII: Cross-App Integration [SKIP]
Not applicable (skill management tool, not cross-app workflow)

### Article VIII: Documentation Standards [OK]
- [OK] YAML frontmatter (name, description, triggers, model)
- [OK] Version/Last Updated/Dependencies
- [OK] Quick Start (4 workflows)
- [OK] Standard Workflows (4 detailed)
- [OK] Troubleshooting (4 issues)
- [OK] Reference Documentation (2 guides)
- [OK] Constitutional Compliance (applicable articles)
- [OK] Version History (SemVer)
- [OK] Description formula: What + When + Triggers

### Article IX: Agent Versioning [SKIP]
Not applicable (this is a skill, uses directory structure)

---

## Version History

**v1.3.0** (2026-10-09) - Run-time access policy for shipped scripts
- Workflow 2 checklist: a shipped script that walks a share or folder tree at
  run time must apply the drive policy itself (the command-text hook cannot see
  what the program opens); contributed script packages are reviewed against a
  hostile fixture, not the author's examples (observation #131, principle 10)

**v1.2.0** (2026-09-10) - Catalog-budget and self-containment observations
- Description rule: put trigger phrases in the FIRST sentence, or keep the
  description well under the 1024-char cap, because some harnesses (Codex)
  budget the whole installed catalog and truncate from the end (observation #20)
- Validation checklist: a skill documents its own scripts as `<skill-dir>/...`,
  never by an absolute path
- Validation checklist: run check_skill_self_contained.py plus the team-gate
  pattern set against every new skill directory regardless of its distribution
  tier, including internal/workspace-only (observation #19)

**v1.1.0** (2025-12-03) - Agent OS Integration
- Added Agent OS standards validation support
- New `--agent-os` flag for validate_skill.py
- Constitutional header validation (YAML frontmatter)
- Context efficiency tracking for standards files
- Line count flexibility for complex standards (400-550 lines)
- Fixed Windows console encoding for Unicode emojis
- All 5 VFX standards validated successfully

**v1.0.0** (2025-10-25) - Initial Release
- create_skill.py: Automated skill creation from template
- validate_skill.py: Constitutional compliance validation (9 articles)
- test_skill.py: Multi-target testing for Article I
- update_skill.py: Semantic versioning and changelog
- Reference docs: Template guide, validation guide
- 73% context reduction vs manual process
- Full constitutional compliance (8/8 applicable articles)