@buildinternet/releases-skills 0.25.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-skills",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Agent skills bundled with the Releases CLI. Markdown playbooks for changelog ingest, discovery, and analysis.",
   "type": "module",
   "license": "MIT",

package/skills/managing-sources/SKILL.md

@@ -30,7 +30,7 @@ Operations can be performed via CLI commands or typed MCP/agent tools. Use which
 | Ignore URL | `releases admin policy ignore add --org <org> <url>` | `exclude_url` action "ignore" with url, organization |
 | Block URL | `releases admin policy block add <url>` | `exclude_url` action "block" with url |
 | Get playbook | `releases admin playbook <org>` | `manage_playbook` action "get" with organization |
-| Update playbook notes | `releases admin playbook <org> --notes "..."` | `manage_playbook` action "update_notes" with organization, notes |
+| Update playbook notes | `releases admin playbook <org> --notes-file <path>` (use `-` for stdin) | `manage_playbook` action "update_notes" with organization, notes |
 
 Valid categories (pass to `manage_org`/`manage_product`): see the enum in those tool descriptions or your system prompt. `list_categories` (now retired) has been folded into the two tool descriptions.
 

package/skills/releases-cli/SKILL.md

@@ -31,26 +31,28 @@ The CLI talks to `api.releases.sh` by default — no configuration needed for re
 
 ```bash
 # Reader (no auth required)
-releases search "breaking change"            # hybrid FTS + semantic search
-releases tail next-js                      # latest releases from one source
-releases tail --org vercel --count 20      # latest from a whole org
-releases list --category ai                  # browse sources
-releases get vercel                          # dispatch by id or slug
-releases stats                               # registry overview
-releases categories                          # list valid category values
+releases search "breaking change"               # hybrid FTS + semantic search
+releases tail next-js                           # latest releases from one source
+releases tail src_abc123                        # IDs work anywhere a slug does
+releases tail --org vercel --count 20           # latest from a whole org
+releases list --category ai                     # browse sources
+releases get vercel                             # dispatch by id or slug
+releases get org_abc123                         # typed IDs are accepted
+releases stats                                  # registry overview
+releases categories                             # list valid category values
 
 # Admin (requires RELEASED_API_KEY)
 releases admin source create "Linear" --url https://linear.app/changelog
-releases admin source fetch <slug> --max 50
+releases admin source fetch <source> --max 50   # source = src_… or slug
 releases admin org create "Acme" --category cloud
-releases admin product create "CLI" --org acme
-releases admin discovery onboard "Stripe"    # AI-powered discovery agent
+releases admin product create "CLI" --org acme  # --org accepts org_…, slug, domain, name, or handle
+releases admin discovery onboard "Stripe"       # AI-powered discovery agent
 
 # Local stdio MCP bridge (proxies to api.releases.sh)
 releases admin mcp serve
 ```
 
-Every reader command accepts `--json` for machine-readable output. IDs (`org_…`, `src_…`, `prod_…`, `rel_…`) are accepted anywhere a slug is. Source and product commands also accept an `org/slug` coordinate (e.g. `vercel/vercel-ai-sdk`); coordinates and typed IDs are unambiguous and skip an extra resolver round-trip that bare slugs require.
+Every command that takes an org / product / source / release identifier accepts the typed ID (`org_…`, `prod_…`, `src_…`, `rel_…`) interchangeably with the slug — including `--org`, `--product`, `--source` flags. IDs are stable across renames; slugs are friendlier to type. Source and product commands also accept an `org/slug` coordinate (e.g. `vercel/vercel-ai-sdk`); coordinates and typed IDs are unambiguous and skip an extra resolver round-trip that bare slugs require. Every reader command accepts `--json` for machine-readable output.
 
 ## Authentication
 
@@ -70,7 +72,7 @@ These can also go in a `.env` file — Bun auto-loads it when running from sourc
 ## Common Mistakes
 
 - `releases admin …` without `RELEASED_API_KEY` set fails fast with a clear error — don't retry the same command. Note that keys are not self-serve yet (see Authentication).
-- Slug renames (`admin source update <slug> --slug new-slug`) require `--confirm-slug-change` because they break web links.
-- `releases admin source fetch` with no slug or filter is blocked in remote mode. Use `--stale`, `--unfetched`, `--retry-errors`, `--changed`, or a source slug.
+- Slug renames (`admin source update <identifier> --slug new-slug`) require `--confirm-slug-change` because they break web links.
+- `releases admin source fetch` with no source or filter is blocked in remote mode. Use `--stale`, `--unfetched`, `--retry-errors`, `--changed`, or a source identifier (src_… or slug).
 - Default fetch cap is 200 releases per source (GitHub pagination limits). Use `--max <n>` or `--all` to override.
 - `summary` and `compare` are *not* in this CLI. Those commands require AI provider calls and live in the private maintainer tooling. Use the hosted MCP tools `summarize_changes` / `compare_products` at `mcp.releases.sh` instead.

package/skills/releases-cli/references/reader.md

@@ -37,9 +37,10 @@ Statuses on the Lookup section: `INDEXED` (just materialized), `EXISTING` (alrea
 
 ```bash
 releases tail                          # across all sources
-releases tail next-js                  # one source (by slug)
-releases tail --org vercel --count 20  # whole org
-releases tail --product nextjs         # one product
+releases tail next-js                  # one source (slug)
+releases tail src_abc123               # one source (typed id)
+releases tail --org vercel --count 20  # whole org (org_…, slug, domain, name, or handle)
+releases tail --product nextjs         # one product (prod_… or slug)
 releases tail --type feature           # filter by release type
 releases tail --json
 ```
@@ -48,9 +49,9 @@ releases tail --json
 
 ```bash
 releases list                          # all sources
-releases list next-js                  # detail for one source (by slug or id)
-releases list --org sentry             # filter by organization
-releases list --product nextjs         # filter by product
+releases list next-js                  # detail for one source (src_… or slug)
+releases list --org sentry             # filter by organization (org_…, slug, domain, name, or handle)
+releases list --product nextjs         # filter by product (prod_… or slug)
 releases list --query shadcn           # name / slug / url substring
 releases list --has-feed               # sources with a discovered feed URL
 releases list --category ai            # filter by category

package/skills/releases-mcp/SKILL.md

@@ -33,15 +33,14 @@ If the query returns no results, try variations:
 
 ### Step 2: Choose the Right Tool
 
-- **"What's new?" / "Latest releases"** → Use `get_latest_releases` with the organization or product slug
+- **"What's new?" / "Latest releases"** → Use `get_latest_releases` with the organization or product identifier (typed ID like `org_…` / `prod_…` / `src_…`, slug, or `org/slug` coordinate)
 - **Specific feature or keyword across orgs + catalog + releases** → Use `search` (unified) with a descriptive query; narrow via `type: ["releases"]` etc.
 - **Releases-only search** → Use `search_releases` (kept for back-compat) when you only want release rows
 - **Single release by id** → Use `get_release` when you already have a `rel_` id (search results include ids)
 - **Catalog deep-dive (product or standalone source)** → Use `get_catalog_entry` for metadata, tags, and linkage
 - **Organization detail** → Use `get_organization`
-- **Canonical CHANGELOG.md from a GitHub repo** → Use `get_source_changelog` when the user wants the full maintained file, not just the tagged releases (refreshed on every fetch). For large files, pass `tokens` (cl100k_base budget, e.g. 5000 or 10000) to get a heading-aligned slice that fits a known context window; chain via the returned `nextOffset`. Every response reports `totalTokens` so you can plan how many calls you need upfront.
-- **Compare two products** → Use `compare_products` with an array of two product slugs
-- **Summarize recent activity** → Use `summarize_changes` with the product slug
+- **Canonical CHANGELOG.md from a GitHub repo** → Use `get_catalog_entry` with `include_changelog: true` when the user wants the full maintained file, not just the tagged releases (refreshed on every fetch). For large files, pass `changelog_tokens` (cl100k_base budget, e.g. 5000 or 10000) to get a heading-aligned slice that fits a known context window; chain via the returned `nextOffset`. Every response reports `totalTokens` so you can plan how many calls you need upfront.
+- **Compare two products** → Fetch each product separately with `get_catalog_entry` (and `get_latest_releases` for recent activity), then synthesize the comparison from the returned data. The hosted MCP server does not expose AI summarization tools.
 
 ### Step 3: Present Results
 
@@ -53,6 +52,6 @@ If the query returns no results, try variations:
 ## Guidelines
 
 - Pass the user's full question context into query parameters for better relevance
-- When the user mentions a time range ("last month", "since v4"), use the `days` parameter on `get_latest_releases` or `summarize_changes`
+- When the user mentions a time range ("last month", "since v4"), use the `days` parameter on `get_latest_releases`
 - If a product isn't found, say so clearly — don't fabricate release information
 - For comparison questions, both products must be indexed; if one isn't found, explain which is missing

package/skills/seeding-playbooks/SKILL.md

@@ -109,15 +109,14 @@ Products: {product list or "none"}
 **Coverage**: 2-3 sentences. Which sources are canonical, whether there are gaps.
 
 Save by running:
-releases admin playbook {slug} --notes "$(cat <<'NOTES'
+releases admin playbook {slug} --notes-file - 2>/dev/null <<'NOTES'
 YOUR NOTES HERE
 NOTES
-)" 2>/dev/null
 
 Verify with: releases admin playbook {slug} 2>/dev/null | tail -20
 ```
 
-The playbook header regenerates automatically after any source create/update/delete, and the `--notes` PATCH seeds a fresh header on first write — no separate regenerate step needed.
+The playbook header regenerates automatically after any source create/update/delete, and the `--notes-file` PATCH seeds a fresh header on first write — no separate regenerate step needed.
 
 ### Verified prompt template
 
@@ -156,10 +155,9 @@ Every claim must cite observed data. If uncertain, say so explicitly.
 
 ## Step 4: Save
 
-releases admin playbook {slug} --notes "$(cat <<'NOTES'
+releases admin playbook {slug} --notes-file - 2>/dev/null <<'NOTES'
 YOUR NOTES HERE
 NOTES
-)" 2>/dev/null
 
 Verify with: releases admin playbook {slug} 2>/dev/null | tail -20
 ```
@@ -184,10 +182,9 @@ Sub-agents may be blocked from saving notes via Bash (heredoc permission issues)
 2. The parent agent (you) saves the notes manually:
 
 ```bash
-releases admin playbook {slug} --notes "$(cat <<'NOTES'
+releases admin playbook {slug} --notes-file - 2>/dev/null <<'NOTES'
 {paste notes from agent result}
 NOTES
-)" 2>/dev/null
 ```
 
 This is a known limitation of subagent permissions. Plan for it — check each agent's result and save manually if needed.