refactor(agents): move worked scenarios out of frontmatter descriptions

[patterson-ai]

Why

Agent description fields are loaded into context for every session so the orchestrator can match delegation targets. Agent bodies load only when the agent actually runs.

All twelve agents carried three <example> blocks inside description:

12 agents · ~223 words of frontmatter each
= 2,679 words ≈ 3,570 tokens resident in every session

That is a permanent context tax to answer a question one sentence answers.

What changed

Each description is now one or two sentences ending in a delegation cue plus See "When to invoke" in the agent body for worked scenarios. The three scenarios move to a ## When to invoke body section, rewritten as prose (bold lead sentence + why this agent fits), with none dropped or invented.

Frontmatter: ~3,570 → ~1,010 tokens. Longest description is 373 chars, well inside the Agent Skills spec's 1024 limit.

Also fixed: what would have regenerated the pattern

The convention propagated from the agent generator, so the generator was updated too:

File	Change
skills/agent-development/SKILL.md	Format template, description field guidance, quick reference, and DO/DON'T list now teach the body-section shape
skills/agent-development/references/triggering-examples.md	Reframed: the judgment it teaches still applies, but scenarios go in the body
agents/agent-creator.md	Generates the new shape
agents/plugin-validator.md	Self-check no longer requires <example> in descriptions
scripts/validate-agent.sh	Warns on <example> in a description, and on a missing ## When to invoke section

references/agent-creation-system-prompt.md is deliberately left verbatim — it is a faithful copy of Claude Code's own generation prompt, and editing it would falsify that record and complicate the re-sync obligation in ADR 0001. It carries a divergence note instead; adaptation happens at the documented conversion step.

Notes

• Four descriptions contain : in their summary text and are therefore YAML-quoted. That is required syntax, not a text change — do not normalize them to plain scalars, it produces invalid YAML.
• This is not a spec-mandated change. <example> in a description was never a documented format; it is undocumented, still functional, and still shipped upstream. The argument here is context cost, not validity.

Test plan

• sh scripts/verify-all.sh → VERIFY-ALL: PASS
• claude plugin validate . → passes
• All 12 frontmatters parse as YAML, are ≤1024 chars, carry the pointer, and contain no <example>
• validate-agent.sh clean on all 12 against the new checks

Stacked on #3; retarget to main after it merges.

[claude]

This check can never fire on the shape it exists to catch. $DESCRIPTION only ever holds the text on the description: line itself:

actdata-plugins/plugins/act-plugin-dev/skills/agent-development/scripts/validate-agent.sh

Lines 90 to 92 in c0c568b

	# Check description field
	DESCRIPTION=$(echo "$FRONTMATTER" | grep '^description:' | sed 's/description: *//')

grep '^description:' is anchored at column 0, so for a YAML block scalar (description: | followed by indented continuation lines) it matches only the header line and sed reduces it to the single character |. The <example> blocks live on the continuation lines and never reach $DESCRIPTION:

$ printf 'name: x\ndescription: |\n  Reviews stuff.\n\n  <example>\n  Context: foo\n  </example>\n' \
    | grep '^description:' | sed 's/description: *//'
|

Block scalar is exactly the shape all twelve agents used before this PR, and the warning text ("move them to a ## When to invoke body section") is remediation advice aimed at precisely that legacy shape — so the check is inert for its only realistic input. Inverting the grep sense from the old if ! ... grep -q is correct in itself; it turns an always-false-positive into an always-false-negative because the extraction was left unchanged.

Two knock-on effects from the same extraction, on any block-scalar description: desc_length is 1, so the "description too short" warning at L100 fires spuriously, and the delegation-cue check at L116 fires spuriously too.

Fix: extract the full description including block-scalar continuation lines before these checks run — e.g. awk over $FRONTMATTER taking the description: line plus subsequent indented lines up to the next top-level key. That one change also clears both spurious warnings. The ## When to invoke check at L122 greps the file directly and is unaffected.

[claude]

The **Must include:** and **Format:** blocks of this ### description (required) section were rewritten to teach the new shape, but the **Best practices:** list two lines below still teaches the old one:

actdata-plugins/plugins/act-plugin-dev/skills/agent-development/SKILL.md

Lines 99 to 109 in c0c568b

	Keep it to one or two sentences. This field is resident in context for every session, so length
	here is paid continuously; the worked scenarios belong in the body's `## When to invoke` section,
	which loads only when the agent runs. See `references/triggering-examples.md` for how to write
	those scenarios well.
	**Best practices:**
	- Include 2-4 concrete examples
	- Show proactive and reactive triggering
	- Cover different phrasings of same intent
	- Explain reasoning in commentary
	- Be specific about when NOT to use the agent

• - Include 2-4 concrete examples (L105) directly contradicts L99-L102 in the same section: "Keep it to one or two sentences ... the worked scenarios belong in the body's ## When to invoke section".
• - Explain reasoning in commentary (L108) refers to the <commentary> blocks this PR deletes from the format template.

Three other passages in this file assert the same abolished convention and were also missed:

• L418 6. Include 2-4 triggering examples in description — the most explicit one, and it sits immediately above 7. Validate with scripts/validate-agent.sh, the validator this PR changes to warn on exactly that.
• L282-283 **Must include:** Triggering conditions and examples / **Best:** 200-1,000 characters with 2-4 examples — the ### Description Validation block, which duplicates the L88-91 list that was updated.
• L257 2. Write description with examples — under ### Method 2: Manual Creation; the parallel step in Method 1 was updated to "Include 2-3 worked scenarios showing when to use".

These are unchanged lines, but the contradiction is created by this PR: before it, they were consistent with the rest of the file. Since the PR body's stated scope for this file is "Format template, description field guidance, quick reference, and DO/DON'T list now teach the body-section shape", leaving these four behind means anything following the workflow at L418 or the validation rule at L282 still generates the description shape the new validate-agent.sh check and agent-creator.md now reject.