Ga naar hoofdinhoud

Skill Patterns & Subfolder Guide

Proven, reusable building blocks for Claude Code skills. These are L3 patterns — apply them consistently across skills. For the full maturity framework, see writing-skills.md.

Description Writing Guide​

The description is the single most important line in your skill. It determines auto-triggering reliability (L2).

# Structure: [Action verb] [what] — [key detail or when to use]

# Good examples:
description: Create a Pull Request from the current branch — runs local checks, picks target branch, and opens the PR on GitHub
description: Run automated browser tests for a Nextcloud app — single agent or multi-perspective parallel testing
description: Archive a completed change in the experimental workflow

# Bad examples:
description: Helps with PRs                          # too vague, no trigger terms
description: This skill creates pull requests for you  # first person, wastes chars
description: A useful tool for managing code reviews   # passive, no specificity

Subfolder Guide​

templates/​

Files with {PLACEHOLDER} variables that Claude fills in at runtime. Claude reads the file, substitutes values, and either writes the result to the user's project or injects it into a sub-agent.

Use for:

  • JSON/YAML/Markdown documents Claude writes to disk (e.g. app-config.json, CHANGELOG.md)
  • Sub-agent prompts with variable substitution
  • PR/issue body formats Claude fills in before creating
  • Spec or design document scaffolds

Do not use for: documents Claude reads without modifying, or fixed reference material.

In SKILL.md, reference with:

Write the file using the template in `templates/architecture-template.md`.

references/​

Static content Claude reads to inform decisions — no placeholder variables, never written to the user's project. This is a key subfolder for L4 personalization — business-specific standards, architecture docs, and domain knowledge live here.

Use for:

  • Standards documents (Dutch government guidelines, GEMMA/ZGW compliance, coding standards)
  • Architecture guidelines and conventions
  • Spec excerpts or capability descriptions
  • Multi-page guides Claude consults during a step

Do not use for: templates, examples, or binary files.

In SKILL.md, reference with:

Follow the standards in `references/dutch-gov-backend-standards.md`.

examples/​

Worked demonstrations showing what expected output looks like. Used for few-shot guidance — Claude sees a concrete example and produces output in the same pattern. Critical for L3 (proven patterns).

Use for:

  • Output format blocks (e.g. "Archive Complete", "Implementation Paused")
  • Worked conflict resolution or decision examples
  • Sample report sections showing expected structure

Do not use for: templates with placeholders (those go in templates/), or static reference docs.

In SKILL.md, reference with:

For the expected output format, see `examples/output-templates.md`.

assets/​

Non-markdown static files that get copied as-is to the user's project or used by the skill tooling.

Use for:

  • SVG illustrations or placeholder images
  • JavaScript/TypeScript config stubs (webpack.config.js, docusaurus.config.js)
  • YAML/JSON configuration stubs copied verbatim

Do not use for: markdown files (even if they're config-like — those go in templates/).

evals/ (L5+)​

Evaluation scenarios and benchmark results for measured skills.

Use for:

  • evals.json — test scenarios, trigger_tests (should/should-not-trigger examples), and last_validated (date of last eval run; required for L5 green circle)
  • timing.json — token usage and duration per eval run
  • grading.json — assertion pass/fail results with evidence

See skill-evals.md for format details.

Common Patterns​

Model guard (for heavy reasoning skills)​

Place at the top of SKILL.md when the skill needs Sonnet or Opus:

**Check the active model** from your system context.

- **On Haiku**: stop immediately — this skill requires Sonnet or Opus.
  Switch with `/model sonnet` and re-run.
- **On Sonnet or Opus**: proceed normally.

User input​

Always use the AskUserQuestion tool — never assume or auto-select:

Use **AskUserQuestion** to ask:

> "Which change should I archive?"

Options:

- **change-a** — description
- **change-b** — description

For multi-select prompts:

Use **AskUserQuestion** with `multiSelect: true` to let the user choose.

Destructive action confirmation​

Before any irreversible action, show what will happen and ask for explicit confirmation:

Show a preview of the changes, then use **AskUserQuestion**:

> "Create these issues in `owner/repo`?"

Options:

- **Yes, proceed** — continue
- **Cancel** — end without changes

Referencing subfolders​

Use relative markdown links — Claude resolves them relative to the skill folder:

Use the template in `templates/architecture-template.md`.
Follow the standards in `references/dutch-gov-backend-standards.md`.
For output examples, see `examples/output-templates.md`.

PHP quality checks (for skills that trigger implementation)​

After code changes, run the quality suite and block on failures:

Run `composer check:strict` from the app directory.
If it fails, fix all issues before continuing — do not skip.

Capture learnings step (L6+)​

Add as the final step in skills that should self-improve:

**Capture learnings**

After execution, review what happened and append new observations to
`learnings.md` under the appropriate section:

- **Patterns That Work** — approaches that produced good results
- **Mistakes to Avoid** — errors encountered and how they were resolved
- **Domain Knowledge** — facts discovered during this run
- **Open Questions** — unresolved items for future investigation

Each entry must include today's date. One insight per bullet. Skip if nothing new was learned.

Next steps handoff (L7)​

For skills that are part of a workflow chain:

**Next steps**

Suggest the logical next action:

- If tasks remain → "Run `/opsx-apply` to implement"
- If implementation done → "Run `/opsx-verify` to validate"
- If verified → "Run `/opsx-archive` to complete"

Verify subagent load-bearing claims (L5+)​

Skills that delegate deep analysis to subagents (Agent tool) must verify high-impact claims at the orchestrator level BEFORE acting on them. Subagents are good at semantic analysis but their findings can occasionally be confidently wrong — the classic failure mode is a claim like "file X is not imported anywhere" that turns out to be false because the file loads via a PHP Util::addStyle call the subagent's grep didn't cover.

Rule: for any subagent finding of severity blocker (🔴 in review skills, or "must-do" in other verticals), the orchestrator MUST re-verify the underlying claim with a targeted grep or read before posting / committing / merging. The verify step is cheap (one bash call) and catches false alarms that would otherwise ship as public review comments.

Recipe:

## Step N.5 — Verify subagent load-bearing claims

For each `findings[].severity === "blocker"` returned by the subagent:

1. Extract the load-bearing factual claim (e.g. "css/main.css is orphan — not imported anywhere").
2. Run the orthogonal verifier (grep across the repo, read the file's PHP loader, check `Util::addStyle` calls, check templates/).
3. If verification refutes the claim → downgrade the finding to a concern or drop it entirely.
4. Log the verification result in the skill's activity trace so future reviewers see the check happened.

Reference case: opencatalogi PR #80 round-2 review — subagent claimed css/main.css was orphan and posted it as a 🔴 blocker. Orchestrator caught the false alarm before posting by grepping templates/*.php for Util::addStyle('opencatalogi', 'main') — found the loader on line 14 of templates/index.php. Blocker downgraded to no-op; the ~15 minutes saved on the correction email were the value of the verify step.

The pattern applies to any skill that delegates factual analysis to a subagent — not just review-pr. If your skill lets a subagent make claims that will drive user-visible actions, add a mandatory verify step.