chore: improve usability (#20)

* chore: improve consumer scripts

* chore: trim it down to nx skills

* update docs around skills

Author: mishraomp

.github/pull_request_template.md

@@ -14,7 +14,6 @@
 ## Checklist
 
 - [ ] Followed [spec/SKILL_SPEC.md](../spec/SKILL_SPEC.md) (7 sections, ≤500 lines, kebab-case name, flat resource dirs).
-- [ ] Bumped the skill's `version` in `skills/<name>/package.json` (semver — patch / minor / major).
 - [ ] Updated `SKILL.md` when behaviour changed (description, Use When, Workflow, Examples).
 - [ ] Ran `make validate` (or `uv run python scripts/validate_skill.py skills/<name>/SKILL.md`) locally and it passed.
 - [ ] Ran `make format` and `make lint` if Python under `scripts/` or `tests/` changed.

.github/scripts/check-version-bumps.sh

@@ -12,30 +12,30 @@ description: Scaffolds a new skill profile in this repo and fills in the require
 
 ## Don't Use When
 - The user wants to check an existing skill against the spec → use `skill-validator`.
-- The user wants to bump a version or publish → use `skill-release`.
 - The user is editing prose in an existing, already-structured skill.
 
 ## Workflow
-1. Pick a kebab-case `<skill-name>` and create `skills/<skill-name>/`.
-2. Copy `templates/SKILL.md` and `templates/package.json` into that folder.
-3. Fill the frontmatter (`name`, `description`) and write the H1 title line.
-4. Complete all seven sections: Use When, Don't Use When, Workflow, Rules, Examples, Edge Cases, References.
-5. Set the package `name` to `@bcgov/<skill-name>` (matching the manifest `name`) and `version` to `0.1.0` in `package.json`.
+1. Before scaffolding, confirm no upstream catalogue already covers this use case. Search [The Agent Skills Directory](https://www.skills.sh/), the [Microsoft Agent Skills catalog](https://microsoft.github.io/skills/#agents), [`anthropics/skills`](https://github.com/anthropics/skills), and [`github/awesome-copilot`](https://github.com/github/awesome-copilot). If an upstream skill covers it, point the user there instead of scaffolding a duplicate; only proceed when the skill is genuinely BC Gov–specific (encodes BC Gov policies, internal services, regulatory requirements, or org-specific workflows).
+2. Pick a kebab-case `<skill-name>` and create `skills/<skill-name>/`.
+3. Copy `templates/SKILL.md` into that folder.
+4. Fill the frontmatter (`name`, `description`) and write the H1 title line.
+5. Complete all seven sections: Use When, Don't Use When, Workflow, Rules, Examples, Edge Cases, References.
 6. Run `uv run python scripts/validate_skill.py skills/<skill-name>/SKILL.md` and fix any errors.
 
 ## Rules
-- Always set the new skill's starting `version` to `0.1.0` in `package.json`, never in the `SKILL.md` frontmatter. (Why: version lives only in package.json to avoid drift between two sources of truth.)
-- Always keep the package `name` as `@bcgov/<skill-name>` — same as the folder and the manifest `name`. (Why: consumers wire skills into their agent by folder name; matching keeps `node_modules/@bcgov/<name>/` usable as-is with no rename step.)
+- Always run the upstream-catalogue check in Workflow step 1 before scaffolding. (Why: this repo is for BC Gov–specific skills; duplicating an upstream skill fragments the ecosystem, doubles the maintenance burden, and makes it ambiguous which one consumers should install. Reviewers will ask for the result of this check in the PR description.)
 - Never invent a new section order or rename a section. (Why: the validator matches the seven section titles exactly and the PR check will fail.)
 - Always keep `## Use When` as situational triggers (when to reach for this skill at all) and `## Workflow` as the numbered procedure (how to do the work). Never let a Use When bullet paraphrase a Workflow step — if a bullet starts with "Always ship…", "Set X to Y", or restates a procedural detail, it belongs in Workflow, not Use When. (Why: the two sections serve different reader intents — routing vs. execution — and duplicating content between them bloats the agent's context, makes routing fuzzier, and drifts out of sync on every edit.)
 
 ## Examples
 - "I want to add a skill for looking up land parcels" → scaffold `skills/parcel-lookup/`, fill the template, validate.
-- "How do I start a new skill profile?" → copy the templates into a new skill dir and walk through the seven sections.
+- "How do I start a new skill profile?" → copy the template into a new skill dir and walk through the seven sections.
 
 ## Edge Cases
 - If a `skills/<skill-name>/` folder already exists → confirm whether to edit it (route to the author flow on the existing files) rather than overwriting.
 - If the user hasn't named the skill → propose a kebab-case name from the described purpose before scaffolding.
 
 ## References
+For the upstream-catalogue check in step 1, search [The Agent Skills Directory](https://www.skills.sh/), [Microsoft Agent Skills](https://microsoft.github.io/skills/#agents), [`anthropics/skills`](https://github.com/anthropics/skills), and [`github/awesome-copilot`](https://github.com/github/awesome-copilot); the "Before adding a new skill" section of [CONTRIBUTING.md](../../../CONTRIBUTING.md) explains the policy in full.
+
 See [spec/SKILL_SPEC.md](../../../spec/SKILL_SPEC.md) for the authoritative manifest spec and [templates/SKILL.md](../../../templates/SKILL.md) for the starting point.

.github/scripts/publish-changed-skills.sh

@@ -12,19 +12,17 @@ description: Validates skill profiles against the spec and explains how to fix f
 
 ## Don't Use When
 - The user wants to create a new skill from scratch → use `skill-author`.
-- The user wants to bump a version or publish → use `skill-release`.
 - The failure is a Python/tooling error unrelated to a skill's contents.
 
 ## Workflow
 1. For one skill, run `uv run python scripts/validate_skill.py skills/<name>/SKILL.md`.
 2. For everything, run `uv run python scripts/validate_skill.py --all`.
 3. To mirror CI on a branch, run `uv run python scripts/validate_skill.py --base origin/main`.
 4. Read each `- <message>` line under a failing file and map it to the offending section or field.
-5. Edit the `SKILL.md` or `package.json` to fix it, then re-run until the file shows `✓`.
+5. Edit the `SKILL.md` to fix it, then re-run until the file shows `✓`.
 
 ## Rules
 - Always re-run the validator after each fix rather than batching guesses. (Why: one fix can reveal or mask another, and the validator is fast.)
-- Always check both the `SKILL.md` and the sibling `package.json` on a failure. (Why: the validator reports manifest and package errors together for the same skill.)
 - Never edit `scripts/validate_skill.py` to make a skill pass. (Why: the spec is the contract; loosening the validator weakens every skill in the catalogue.)
 
 ## Examples
@@ -34,7 +32,7 @@ description: Validates skill profiles against the spec and explains how to fix f
 
 ## Edge Cases
 - If `--base` finds no changed skills → report that nothing changed; there is nothing to validate.
-- If the error is `missing package.json` → create one from `templates/package.json` beside the manifest before re-running.
+- If the error names a missing or empty section → add the section heading (verbatim) with at least one bullet of content and re-run.
 
 ## References
 See [spec/SKILL_SPEC.md](../../../spec/SKILL_SPEC.md) for what each check enforces and [CONTRIBUTING.md](../../../CONTRIBUTING.md) for the PR-check summary.

.github/skills/skill-author/SKILL.md

@@ -6,9 +6,8 @@ name: PR
 #   2. lint-tests — formats, lints, and unit-tests the tooling that produces
 #      skills (scripts/, tests/, pyproject.toml). Runs after fork-gate: if the
 #      generator is broken, validating skill output is meaningless.
-#   3. skills     — validates the SKILL.md profiles the PR changed and
-#      enforces that every changed publishable skill has its package.json
-#      version bumped. Gated on lint-tests passing.
+#   3. skills     — validates the SKILL.md profiles the PR changed. Gated on
+#      lint-tests passing.
 #   4. results    — always runs (`if: always()`), needs every other job, and
 #      fails if any of them failed or was cancelled. This is the SINGLE
 #      required status check on `main`, so we can add or rename jobs in this
@@ -89,11 +88,6 @@ jobs:
       - name: Validate changed skills
         run: uv run python scripts/validate_skill.py --base "origin/${{ github.base_ref }}"
 
-      - name: Check version bumps on changed skills
-        env:
-          BASE_REF: origin/${{ github.base_ref }}
-        run: bash .github/scripts/check-version-bumps.sh
-
   # 3. Aggregator. Always runs (even if upstream jobs failed or were cancelled)
   #    and fails if any required job failed or was cancelled. Branch protection
   #    only needs to require THIS one check — adding or renaming jobs above