feat: naming and consumer scripts (#18)

* feat: naming and consumer scripts

* bump version

Author: mishraomp

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

@@ -13,7 +13,7 @@
 #   * Skips skill@version pairs already published to the registry.
 #   * Publishes with `--tag latest` so the `latest` dist-tag always points at
 #     the just-shipped version alongside the immutable version coordinate.
-#     Consumers can then `npm install @bcgov/skill-<name>` (no version) to
+#     Consumers can then `npm install @bcgov/<name>` (no version) to
 #     track the most recent release.
 #   * Keeps going after a per-skill failure and reports them all at the end,
 #     then exits non-zero so the workflow turns red. (One bad skill should not

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

@@ -20,12 +20,12 @@ description: Scaffolds a new skill profile in this repo and fills in the require
 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-<skill-name>` and `version` to `0.1.0` in `package.json`.
+5. Set the package `name` to `@bcgov/<skill-name>` (matching the manifest `name`) and `version` to `0.1.0` in `package.json`.
 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` scoped as `@bcgov/skill-<skill-name>` matching the folder. (Why: the publish workflow derives the npm package identity from this and consumers install by it.)
+- 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.)
 - 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.)
 

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

@@ -19,20 +19,20 @@ description: Bumps a skill's version and ships it as an npm package when a contr
 1. Decide the change size: patch (fix/wording), minor (compatible capability), major (breaking).
 2. From the skill folder, run `npm version patch|minor|major` to bump `package.json`.
 3. Validate with `uv run python scripts/validate_skill.py skills/<name>/SKILL.md`.
-4. Open a PR; on merge to `main` the publish workflow reads `name` + `version` and runs `npm publish --tag latest`. The `--tag latest` keeps the `latest` dist-tag pointed at the version this run shipped, so consumers who `npm install @bcgov/skill-<name>` (no version) get the new release.
+4. Open a PR; on merge to `main` the publish workflow reads `name` + `version` and runs `npm publish --tag latest`. The `--tag latest` keeps the `latest` dist-tag pointed at the version this run shipped, so consumers who `npm install @bcgov/<name>` (no version) get the new release.
 5. Confirm the release: the workflow skips any version already published, so only a bumped version ships.
 
 ## Rules
 - Always bump the `version` in `package.json` for any release. (Why: the publish workflow skips already-published versions, so an unbumped merge ships nothing.)
 - Always choose the semver level by impact on consumers, not effort. (Why: a tiny but breaking change is still a major; consumers rely on semver ranges to upgrade safely.)
 - Never hand-edit a version to one that was already published. (Why: npm registry versions are immutable and the publish will fail.)
-- Never bypass the `--tag latest` behaviour for a normal forward release. (Why: the publish script ships every changed skill with `npm publish --tag latest`, which is what makes `npm install @bcgov/skill-<name>` resolve to the newest version. Backport publishes on an older line are the only case that wants a different dist-tag, and they belong in a follow-up `npm dist-tag` step rather than an edit to the publish script.)
+- Never bypass the `--tag latest` behaviour for a normal forward release. (Why: the publish script ships every changed skill with `npm publish --tag latest`, which is what makes `npm install @bcgov/<name>` resolve to the newest version. Backport publishes on an older line are the only case that wants a different dist-tag, and they belong in a follow-up `npm dist-tag` step rather than an edit to the publish script.)
 
 ## Examples
 - "I fixed a typo in the example skill, release it" → `npm version patch`, validate, open PR.
 - "This skill now supports a new lookup, ship it" → `npm version minor`, validate, open PR.
 - "Why didn't my merge publish anything?" → check whether `version` was bumped; an unchanged version is skipped by design.
-- "How do consumers pick up my release without pinning a version?" → `npm install @bcgov/skill-<name>` resolves to the `latest` dist-tag, which the publish workflow updates on every release.
+- "How do consumers pick up my release without pinning a version?" → `npm install @bcgov/<name>` resolves to the `latest` dist-tag, which the publish workflow updates on every release.
 
 ## Edge Cases
 - If the user is unsure of the level → ask whether existing consumers would break; if yes it's major, if it only adds it's minor, otherwise patch.

CONTRIBUTING.md

@@ -100,7 +100,7 @@ and match the skill's directory name; `description` must be ≤1024 chars with n
 angle brackets. Keep the manifest under 500 lines and any `scripts/`,
 `references/`, or `assets/` directory flat (one level deep).
 
-`package.json` holds the published package `name` (`@bcgov/skill-<name>`) and
+`package.json` holds the published package `name` (`@bcgov/<name>`) and
 the `version`. **The version lives only here — not in `SKILL.md`** — so there's
 one source of truth and no drift. See the spec for the full definition.
 

README.md

@@ -76,13 +76,17 @@ agent-skills/
 │   └── SKILL_SPEC.md               # authoritative manifest spec
 ├── templates/
 │   ├── SKILL.md                    # copy this to start a new skill
-│   └── package.json                # copy this — holds the skill's name + version
+│   ├── package.json                # copy this — holds the skill's name + version
+│   └── references/
+│       └── REFERENCE.md            # template for an optional reference doc
 │
 ├── skills/                         # contributed skills — validated AND published
 │   └── <skill>/                    # one folder per skill (browse the live site for the catalogue)
 │
 ├── scripts/
-│   └── validate_skill.py           # the spec validator (CI + local)
+│   ├── validate_skill.py           # the spec validator (CI + local)
+│   ├── install-skill.sh            # consumer installer (macOS / Linux)
+│   └── install-skill.ps1           # consumer installer (Windows / PowerShell)
 ├── tests/
 │   └── test_validate_skill.py
 │
@@ -118,6 +122,86 @@ Worth flagging about the layout above:
 Skills install like any other npm dependency, so your existing
 `npm` / `npx` / `npm update` flow already manages them, upgrades included.
 
+### Quick install (recommended)
+
+One line. The installer checks for the GitHub CLI (and installs it if missing),
+adds the `read:packages` scope, writes the project `.npmrc`, runs `npm install`,
+**and offers to wire the skill into your agent** (GitHub Copilot, Claude Code,
+or a custom location for Codex / Cursor / Cline / etc.). Re-run any time to
+install another skill or upgrade an existing one.
+
+> **Supply-chain note &mdash; pin to an immutable ref in production.**
+> The forms below default to `main`, which is mutable: the installer code can
+> change between when you read it and when you run it. For CI, scripted setup,
+> or any environment where reproducibility matters, replace `main` with a
+> 40-char commit SHA you have audited &mdash; pick the latest green commit from
+> [bcgov/agent-skills/commits/main/scripts](https://github.com/bcgov/agent-skills/commits/main/scripts).
+> This is the same advice our own [`github-actions`](skills/github-actions/SKILL.md)
+> skill gives for third-party Actions.
+
+**macOS / Linux** (interactive prompts work because of process substitution):
+
+```bash
+# Pinned (recommended) -- replace <SHA> with a 40-char commit you have reviewed:
+bash <(curl -fsSL https://raw.githubusercontent.com/bcgov/agent-skills/<SHA>/scripts/install-skill.sh)
+
+# Rolling (convenient for one-off installs -- may change without notice):
+bash <(curl -fsSL https://raw.githubusercontent.com/bcgov/agent-skills/main/scripts/install-skill.sh)
+```
+
+**Windows (PowerShell)** &mdash; works on PS 5.1 and PS 7, no `ExecutionPolicy`
+change needed (in-memory scriptblocks aren't restricted):
+
+```powershell
+# Pinned (recommended) -- replace <SHA> with a 40-char commit you have reviewed:
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/bcgov/agent-skills/<SHA>/scripts/install-skill.ps1)))
+
+# Rolling (convenient for one-off installs -- may change without notice):
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/bcgov/agent-skills/main/scripts/install-skill.ps1)))
+```
+
+Prefer to audit the script before running it? Pin to a SHA, download, read,
+then run. **When you pin to a commit SHA, GitHub serves the exact blob that
+was committed at that ref &mdash; the SHA itself is the integrity anchor; there
+is no separate published hash to compare against.** Recording a `sha256sum`
+is useful for your own change-management trail (so re-deploys can detect
+drift), not as a first-time verification step.
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/bcgov/agent-skills/<SHA>/scripts/install-skill.sh -o install-skill.sh
+less install-skill.sh                              # review the code
+sha256sum install-skill.sh                         # optional: record with your deploy ticket
+bash install-skill.sh
+```
+
+```powershell
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/bcgov/agent-skills/<SHA>/scripts/install-skill.ps1 -OutFile install-skill.ps1
+Get-Content install-skill.ps1 | more               # review the code
+Get-FileHash install-skill.ps1 -Algorithm SHA256   # optional: record with your deploy ticket
+.\install-skill.ps1
+```
+
+Non-interactive form (CI or scripted setup &mdash; passing a positional skill
+name skips the wire-up prompt automatically):
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/bcgov/agent-skills/<SHA>/scripts/install-skill.sh) azure-networking 0.1.1
+```
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/bcgov/agent-skills/<SHA>/scripts/install-skill.ps1))) -Skill azure-networking -Version 0.1.1
+```
+
+**Agent compatibility today** &mdash; only Copilot and Claude Code load `SKILL.md`
+natively via the [agentskills.io](https://agentskills.io) standard. For Codex
+CLI, Cursor, Cline, Continue.dev, and others, pick "Custom location" and the
+script symlinks the skill into the folder your tool already scans.
+
+Prefer to understand or run each step yourself? The manual flow is below.
+
+### Manual install
+
 **1. Point the `@bcgov` scope at GitHub Packages** by adding an `.npmrc` next
 to your agent's `package.json`:
 
@@ -186,27 +270,60 @@ public packages, so `NODE_AUTH_TOKEN` needs a credential with the
 **3. Install.** Pin a version for reproducible pulls:
 
 ```bash
-npm install @bcgov/skill-<name>@0.1.0
+npm install @bcgov/<name>@0.1.0
 ```
 
 Or omit the version to track the `latest` dist-tag, which the publish
 workflow updates on every release:
 
 ```bash
-npm install @bcgov/skill-<name>
+npm install @bcgov/<name>
 ```
 
-It installs to `node_modules/@bcgov/skill-<name>/` with `SKILL.md` plus
-whatever else the skill ships, exactly as it lives in this repo. Point your
-agent's skill loader at that directory; the on-disk layout is preserved, so
-there's no extra wiring.
+It installs to `node_modules/@bcgov/<name>/` with `SKILL.md` at the root
+plus whatever else the skill ships, exactly as it lives in this repo.
+
+**4. Wire it into your agent.** The SKILL.md format follows the
+[agentskills.io](https://agentskills.io) open standard, so GitHub Copilot,
+Claude Code, Cursor, and other compatible agents can all read it. Because the
+package name (`@bcgov/<name>`) already matches the manifest `name`, you have
+two options:
+
+- **Point your agent at the whole scope (recommended).** Set the skills
+  location to `node_modules/@bcgov/` once and every installed `@bcgov/*` skill
+  shows up &mdash; no per-skill wiring, new installs picked up automatically:
+
+  ```jsonc
+  // .vscode/settings.json &mdash; GitHub Copilot in VS Code
+  { "chat.agentSkillsLocations": ["node_modules/@bcgov"] }
+  ```
+
+  ```bash
+  # Claude Code (project session)
+  claude --add-dir node_modules/@bcgov
+  ```
+
+- **Symlink one skill at a time.** If your agent only scans a fixed folder
+  (`.github/skills/`, `.claude/skills/`, `.agents/skills/`), symlink each
+  installed package in. Folder name and package name match, so the link is
+  one-to-one:
+
+  ```bash
+  ln -s ../../node_modules/@bcgov/azure-networking .github/skills/azure-networking
+  ln -s ../../node_modules/@bcgov/azure-networking .claude/skills/azure-networking
+  ```
+
+For anything else, point the loader directly at
+`node_modules/@bcgov/<name>/SKILL.md`. See
+[Consume &rarr; Step 4](https://bcgov.github.io/agent-skills/consume.html#step-4-wire-up)
+for PowerShell snippets, the GitHub Actions form, and troubleshooting.
 
-**4. Upgrade.** Because skills are plain npm packages:
+**5. Upgrade.** Because skills are plain npm packages:
 
 ```bash
-npm outdated @bcgov/skill-<name>        # see what's newer
-npm update @bcgov/skill-<name>          # move within your semver range
-npm install @bcgov/skill-<name>@0.2.0   # jump to an exact version
+npm outdated @bcgov/<name>        # see what's newer
+npm update @bcgov/<name>          # move within your semver range
+npm install @bcgov/<name>@0.2.0   # jump to an exact version
 ```
 
 Use a semver range (e.g. `"^0.1.0"`) to pick up compatible updates on
@@ -228,7 +345,7 @@ Once you have access set up, the loop looks like this:
 2. **Fill in** the `SKILL.md` frontmatter and all seven sections; see
    [`spec/SKILL_SPEC.md`](spec/SKILL_SPEC.md).
 3. **Set the package name and version** in `package.json`
-   (`@bcgov/skill-<your-skill>`, starting at `0.1.0`). The published version
+   (`@bcgov/<your-skill>`, starting at `0.1.0`). The published version
    lives only here; there is no `version` field in `SKILL.md` for it to drift
    from.
 4. **Validate locally:**
@@ -259,7 +376,7 @@ When a PR merges to `main`, [`publish.yml`](.github/workflows/publish.yml):
    `npm publish --tag latest` — **unless that exact version is already
    published**, in which case it's skipped. The `--tag latest` keeps the
    `latest` dist-tag pointed at whatever this run shipped, so consumers who
-   `npm install @bcgov/skill-<name>` (no version) get the most recent release.
+   `npm install @bcgov/<name>` (no version) get the most recent release.
 
 Three things shape how this works:
 

docs/_pages/architecture.html

@@ -15,7 +15,7 @@ <h2 id="overview">Lifecycle at a glance</h2>
                                                    publish workflow
                                                           │
                                                           ▼
-                                            @bcgov/skill-&lt;name&gt;@x.y.z
+                                            @bcgov/&lt;name&gt;@x.y.z
                                             on GitHub Packages</code></pre>
 </div>
 
@@ -52,7 +52,7 @@ <h2 id="publish-workflow">Publish workflow: <code>.github/workflows/publish.yml<
         <li>Install <code>uv</code> (third-party action, SHA-pinned per the policy below).</li>
         <li><strong>Re-validate every skill</strong> with <code>uv run python scripts/validate_skill.py --all</code>, the final check before any package bytes leave the repo.</li>
         <li>Set up Node with the registry pointed at <code>https://npm.pkg.github.com</code> and the <code>@bcgov</code> scope. (The exact Node version lives in the workflow file.)</li>
-        <li>Run <a href="https://github.com/bcgov/agent-skills/blob/main/.github/scripts/publish-changed-skills.sh" target="_blank" rel="noopener"><code>.github/scripts/publish-changed-skills.sh</code></a>, which diffs <code>BEFORE_SHA</code> against <code>HEAD_SHA</code>, walks each changed skill, and runs <code>npm publish --tag latest</code> with <code>NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}</code>. The <code>--tag latest</code> keeps the <code>latest</code> dist-tag pointed at the just-shipped version, so <code>npm install @bcgov/skill-&lt;name&gt;</code> (no version) always pulls the most recent release.</li>
+        <li>Run <a href="https://github.com/bcgov/agent-skills/blob/main/.github/scripts/publish-changed-skills.sh" target="_blank" rel="noopener"><code>.github/scripts/publish-changed-skills.sh</code></a>, which diffs <code>BEFORE_SHA</code> against <code>HEAD_SHA</code>, walks each changed skill, and runs <code>npm publish --tag latest</code> with <code>NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}</code>. The <code>--tag latest</code> keeps the <code>latest</code> dist-tag pointed at the just-shipped version, so <code>npm install @bcgov/&lt;name&gt;</code> (no version) always pulls the most recent release.</li>
     </ol>
 </div>
 

docs/_pages/catalog.html

@@ -23,7 +23,7 @@ <h2 id="published">Published skills</h2>
         <h3 style="margin: 0; color: var(--bc-blue);">Browse published skills on GitHub Packages</h3>
         <span class="badge badge-gold">live</span>
     </div>
-    <p>The full catalogue of published <code>@bcgov/skill-*</code> packages is browsable on GitHub. Each package links back to its <code>SKILL.md</code> source in this repo.</p>
+    <p>The full catalogue of published <code>@bcgov/*</code> packages is browsable on GitHub. Each package links back to its <code>SKILL.md</code> source in this repo.</p>
     <p style="margin-top: 1rem;">
         <a href="https://github.com/orgs/bcgov/packages?repo_name=agent-skills" target="_blank" rel="noopener"><strong>Open packages for <code>bcgov/agent-skills</code> →</strong></a>
         &nbsp;·&nbsp;