Expand CONTRIBUTING.md with skill development template

Adds directory structure, SKILL.md frontmatter format, eval requirements,
check_output.py template, registration steps, and pattern registry format.

Author: bx33661

CONTRIBUTING.md

@@ -56,3 +56,121 @@ Before opening a PR:
 2. Update docs when commands, outputs, contracts, or release behavior changes.
 3. Update `CHANGELOG.md` for release-facing changes.
 4. Explain whether skill output behavior changed.
+
+## Creating a New Skill
+
+Use this template to add a new skill to the collection.
+
+### 1. Directory Structure
+
+```
+skills/omv-<name>/
+  SKILL.md                    — skill definition (frontmatter name must match directory)
+  references/                 — detailed guidance loaded on demand
+    patterns/<ecosystem>.md   — ecosystem-specific patterns (if applicable)
+  scripts/
+    check_output.py           — heuristic eval checker
+  evals/
+    evals.json                — eval scenarios (minimum 3)
+    golden/                   — stable golden outputs
+  contracts/                  — copies of consumed contracts
+```
+
+### 2. SKILL.md Frontmatter
+
+```yaml
+---
+name: omv-<name>
+description: |
+  One paragraph describing when to invoke this skill.
+---
+```
+
+The `name` field MUST match the directory basename exactly.
+
+### 3. Eval Requirements
+
+Every skill needs at least 3 eval scenarios covering:
+
+- **Happy path** — normal successful invocation
+- **Edge case** — boundary condition or unusual input
+- **Error/blocked path** — graceful handling of invalid or impossible requests
+
+Each eval in `evals.json` must have:
+- `id`: unique integer
+- `prompt`: the invocation string
+- `expected_output`: human-readable description
+- `files`: list of golden output paths
+- `assertions`: list of `{type, text}` pairs checked by `check_output.py`
+
+### 4. check_output.py Template
+
+```python
+#!/usr/bin/env python3
+"""Heuristic checker for omv-<name> eval outputs."""
+
+from __future__ import annotations
+import argparse, json, re, sys
+from pathlib import Path
+from typing import Any
+
+SKILL_DIR = Path(__file__).resolve().parents[1]
+
+def load_eval(evals_path: Path, eval_id: int) -> dict[str, Any]:
+    data = json.loads(evals_path.read_text(encoding="utf-8"))
+    item = next((e for e in data["evals"] if e["id"] == eval_id), None)
+    if item is None:
+        raise SystemExit(f"unknown eval id: {eval_id}")
+    return item
+
+def check(assertion_type: str, text: str) -> bool:
+    # Add assertion checks here
+    raise SystemExit(f"unknown assertion type: {assertion_type}")
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--eval-id", type=int, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--evals", type=Path, default=SKILL_DIR / "evals" / "evals.json")
+    args = parser.parse_args()
+    eval_item = load_eval(args.evals, args.eval_id)
+    output = args.output.read_text(encoding="utf-8")
+    failures = [
+        a["type"] for a in eval_item.get("assertions", [])
+        if not check(str(a["type"]), output)
+    ]
+    if failures:
+        print("FAIL: " + ", ".join(failures), file=sys.stderr)
+        raise SystemExit(1)
+    print(f"OK: eval {args.eval_id} heuristic assertions passed")
+
+if __name__ == "__main__":
+    main()
+```
+
+### 5. Registration
+
+After creating the skill:
+
+1. Run `python3 scripts/validate_skill.py skills/omv-<name>` to verify structure.
+2. Add the skill to `registry.yaml` with version, produces/consumes bindings.
+3. Run `python3 scripts/sync_skill_assets.py` to sync shared references.
+4. Run `npm test` to verify no regressions.
+
+### 6. Pattern Registry (if applicable)
+
+If your skill uses ecosystem-specific vulnerability patterns, add them to `shared/references/patterns/<ecosystem>.md` with this structure:
+
+```markdown
+## <Vuln Class>: <short description>
+
+- Source pattern: ...
+- Sink signature: ...
+- Common misuse: ...
+- Expected guard: ...
+- Evidence criteria: ...
+- False-positive checks: ...
+- CWE: CWE-XXX
+```
+
+Currently supported ecosystems: npm, python, go, rust, java, ruby, php, csharp, swift, dart, elixir, perl.