| # Contributing |
|
|
| ## Repo layout |
|
|
| This repository **is** the skill — `SKILL.md` sits at the root, per the |
| [Agent Skills spec](https://agentskills.io/specification). The skill activates when |
| an agent's task matches the `description` in `SKILL.md`'s frontmatter. |
|
|
| ## The ontology is generated, not hand-edited |
|
|
| `ontology/` (the `index.yaml` + per-node files + `_axis.yaml`) was generated from |
| the upstream per-node draft YAMLs in `09_full_layer_a_implementation/`. **Do not |
| edit `ontology/` files by hand** — update the source drafts and regenerate using the |
| build script in that folder. |
|
|
| ## Validate before you push |
|
|
| Use the agentskills reference validator to check the frontmatter and conventions. |
| Run it from the **parent** directory and pass the skill's folder name — not `.`, |
| which resolves to an empty basename and fails the directory-name check: |
|
|
| ```bash |
| cd .. |
| skills-ref validate humanitarian-data-analyst |
| ``` |
|
|
| CI runs this on every push and PR (see `.github/workflows/validate.yml`). |
|
|
| ## Implementing a step (currently Step 4 — Analysis is a stub) |
|
|
| Steps 1–3 are implemented; Step 4 (Analysis) is a stub. To implement it (or to |
| extend an earlier step): |
|
|
| 1. Replace the relevant `references/step_*.md` stub (e.g. `references/analysis.md`) |
| with the real guide. |
| 2. For a data-bearing step (like the Step 2 catalog), mirror the Step 1 framework |
| pattern: a compact `index.yaml` routing surface + per-item files loaded on demand. |
| Keep `SKILL.md` thin — it conducts; the heavy material lives in resource files |
| loaded only when that step runs. |
| 3. Flip the step's status marker in `SKILL.md` from 🚧 to ✅. |
|
|
| ## Provenance |
|
|
| Cite sources for any data you add. The Step 1 framework cites HumSet — see |
| `references/SOURCES.md`. |
|
|
