workshop-air-pollution-monitoring

SKILL.md — Skill Registry & Execution Contract

This document is the canonical registry documentation for the workshop-air-pollution-monitoring skill. It explains how skills, tools, and hooks are registered, resolved, executed, and validated, including the input/output JSON-Schema contracts that bind every component.

It is read by:

• contributors who add or modify a skill/tool/hook;
• the runtime (tools/skill_registry.py, tools/tool_registry.py, tools/hooks.py) which loads and validates the registry;
• the orchestrator (skills/main.md) which dispatches sub-skills by name.

The machine-readable companion is assets/registry.json; every entry there validates against assets/schemas/registry-entry.schema.json.

---

1. Architecture at a glance

USER QUERY
   │
   ▼
[pre_flight hooks]  language · context budget · registry validate
   │
   ▼
[skills/main.md]  orchestrator + quality gate
   │
   ▼
[skills/sub-router.md]  chain-of-thought → plan
   │
   ▼
[skills/sub-*.md]  intake → evidence → core-analysis → knowledge → advisor
   │   (each powered by tools/* via the tool registry, grounded by references/*)
   ▼
[pre_delivery hook]  enforce U1–U6 + G1–G4
   │
   ▼
[final report]  conforms to assets/schemas/report.schema.json
   │
   ▼
[post_delivery hook]  queue gaps · metrics · structured log

See assets/diagrams/system-architecture.md for the full diagram and assets/registry.json for the manifest.

---

2. Skill registry

2.1 Registration

A skill is a Markdown file in skills/ with YAML frontmatter and the required sections. To register a new skill:

1. Create skills/sub-<name>.md with frontmatter name + description.
2. Include the required sections: Role & Persona, Workflow, Output Format, Quality Gates (sub-skills) — and additionally Sub-skills Available, Quality Gates table, Graceful Degradation, Output Format (orchestrator).
3. Add an entry to assets/registry.json under skills[] with type = sub_skill (or orchestrator / router), the path, phase, depends_on, inputs, outputs, and output_schema (a URI to a schema in assets/schemas/).
4. If the skill emits structured data, author the schema in assets/schemas/ and reference it from output_schema.
5. Re-run python scripts/validate_project.py — it asserts the file exists, the frontmatter is valid, the required sections are present, and the registry.json entry validates.