# Pw Writing Skills

> Use when creating or improving Boost skills for ProcessWire agents to ensure optimal CSO formatting and testing requirements.

- Skill: `trk/pw-writing-skills` (Agent Skill)
- Install (CLI): `npx skillmds@latest add trk/pw-writing-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/trk/pw-writing-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: trk (https://skillmd.com/u/trk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/trk/pw-writing-skills

---


# ProcessWire Writing Skills

Create, improve, and validate agent skills for the ProcessWire Boost ecosystem.

**Writing skills IS Test-Driven Development applied to process documentation.**

## 1. The Iron Law (TDD for Skills)

```
NO SKILL WITHOUT A FAILING TEST FIRST
```

This applies to NEW skills AND EDITS to existing skills.

If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing. 

**RED -> GREEN -> REFACTOR Cycle:**
1. **RED (Baseline):** Run a pressure scenario with subagents *without* the skill. Document the exact behavior and rationalizations the agent uses to skip best practices.
2. **GREEN (Minimal Skill):** Write the specific skill addressing those rationalizations. Verify the agent now complies.
3. **REFACTOR (Close Loopholes):** If the agent finds a new workaround, add an explicit counter to the skill.

**Violating the letter of the rules is violating the spirit of the rules.**
Agents will rationalize under pressure ("It's too simple to test", "I'll test later"). Do not allow this. Add explicit anti-patterns to prevent loopholes.

## 2. When to Use & Skill Directories

- Creating a NEW skill for `resources/boost/skills/`
- Improving an EXISTING Boost skill that agents ignore
- Debugging why a skill isn't being triggered

All Boost skills live in `resources/boost/skills/<skill-name>/`:

```
resources/boost/skills/
├── pw-module-development/         # Core module scaffold & PHP patterns
│   └── SKILL.md
├── pw-pages/                      # Selectors, CRUD, page lifecycle
│   └── SKILL.md
└── pw-brainstorming/              # Design process & implementation planning
    └── SKILL.md
```

**Naming Convention:** All Boost skills MUST use the `pw-` prefix (e.g., `pw-pages`, `pw-module-development`).

## 3. YAML Frontmatter (CSO Optimization)

Every `SKILL.md` MUST start with:

```yaml
---
name: skill-name              # Must match directory name
description: "Use when..."    # Starts with 'Use when' — this is the trigger
risk: safe                    # safe | unknown | critical
source: processwire-boost     # Always processwire-boost for Boost skills
---
```

### Description Best Practices (Critical for Discovery)
The `description` field is how AI agents discover skills. **Never summarize the skill's workflow or process in the description.** Describe ONLY the triggering conditions.

```yaml
# ✅ Good — trigger-based
description: "Use when building custom Fieldtype and Inputfield modules in ProcessWire."

# ❌ Bad — summary-based / shortcut
description: "A comprehensive guide to ProcessWire Fieldtype development."
```
If your description summarizes the workflow, the AI might skip reading the file and just hallucinate the steps!

## 4. Skill Content Structure

```markdown
# ProcessWire [Skill Title]

## When to Use
- [Specific trigger condition]

## Core Concepts
- ProcessWire-specific patterns and examples
- Code samples using `wire()`, `$pages`, `$sanitizer`
- CLI commands using `vendor/bin/wire`

## Anti-Patterns & Loophole Closing
- What NOT to do (with ❌ markers)
- Explicit counters for AI rationalizations

## Related Skills
- Links to complementary pw- skills
```

## 5. Quality & Deployment Checklist

Before deploying any skill, run through this TDD-adapted checklist:

**Testing (Mandatory):**
- [ ] Created pressure scenarios for the skill
- [ ] Watched an agent fail without the skill (Baseline/RED)
- [ ] Verified an agent complies with the new skill (GREEN)
- [ ] Closed newly discovered rationalization loopholes (REFACTOR)

**Formatting:**
- [ ] `name` field matches directory name exactly
- [ ] `SKILL.md` filename is ALL CAPS
- [ ] Description starts with "Use when..." and does NOT summarize workflows
- [ ] All code examples use ProcessWire API (not Laravel/Symfony)
- [ ] PHP examples use `declare(strict_types=1)` and `namespace ProcessWire`
- [ ] CLI examples use `vendor/bin/wire` or `wire` alias
- [ ] Total SKILL.md under 500 lines (split into references/ if larger)

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Skipping the RED phase | Always test baseline behavior before writing the file |
| Laravel examples in PW skills | Use ProcessWire API equivalents |
| Description summarizes content | Use "Use when..." triggers |
| Missing anti-patterns section | Add ❌ markers to block AI shortcuts and workarounds |