Context

A post by @nullvoxpopuli suggested writing agent skills as statecharts.

This repo would benefit from explicit state-based logic charts so each skill flow is inspectable, reviewable, and easier to evolve safely.

Proposal

• Add Mermaid stateDiagram-v2 charts for skill workflows.
• Cover the core lifecycle for each skill (for example: trigger -> context collection -> branching decisions -> actions -> validation -> output/exit).
• Keep concise charts in SKILL.md; move detailed diagrams to references/ when needed and link back.

Acceptance Criteria

• Each public skill under skills/ includes a state-based flow chart or a direct link to one.
• Contribution guidance documents this expectation for new/updated skills.
• Validation rules enforce chart presence (or a documented exemption path for trivial skills).
• Existing skills are updated incrementally without changing runtime behavior.

Why this helps

• Makes branching/guard conditions explicit.
• Improves maintainability and onboarding.
• Reduces ambiguity during reviews and refactors.