@buildinternet/releases-skills 0.26.0 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/package.json +1 -1
  2. package/skills/releases-cli/SKILL.md +15 -13
  3. package/skills/releases-cli/references/reader.md +7 -6
  4. package/skills/releases-mcp/SKILL.md +4 -5
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@buildinternet/releases-skills",
3
- "version": "0.26.0",
3
+ "version": "0.27.0",
4
4
  "description": "Agent skills bundled with the Releases CLI. Markdown playbooks for changelog ingest, discovery, and analysis.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/skills/releases-cli/SKILL.md CHANGED
@@ -31,26 +31,28 @@ The CLI talks to `api.releases.sh` by default — no configuration needed for re
31
31
 
32
32
  ```bash
33
33
  # Reader (no auth required)
34
- releases search "breaking change" # hybrid FTS + semantic search
35
- releases tail next-js # latest releases from one source
36
- releases tail --org vercel --count 20 # latest from a whole org
37
- releases list --category ai # browse sources
38
- releases get vercel # dispatch by id or slug
39
- releases stats # registry overview
40
- releases categories # list valid category values
34
+ releases search "breaking change" # hybrid FTS + semantic search
35
+ releases tail next-js # latest releases from one source
36
+ releases tail src_abc123 # IDs work anywhere a slug does
37
+ releases tail --org vercel --count 20 # latest from a whole org
38
+ releases list --category ai # browse sources
39
+ releases get vercel # dispatch by id or slug
40
+ releases get org_abc123 # typed IDs are accepted
41
+ releases stats # registry overview
42
+ releases categories # list valid category values
41
43
 
42
44
  # Admin (requires RELEASED_API_KEY)
43
45
  releases admin source create "Linear" --url https://linear.app/changelog
44
- releases admin source fetch <slug> --max 50
46
+ releases admin source fetch <source> --max 50 # source = src_… or slug
45
47
  releases admin org create "Acme" --category cloud
46
- releases admin product create "CLI" --org acme
47
- releases admin discovery onboard "Stripe" # AI-powered discovery agent
48
+ releases admin product create "CLI" --org acme # --org accepts org_…, slug, domain, name, or handle
49
+ releases admin discovery onboard "Stripe" # AI-powered discovery agent
48
50
 
49
51
  # Local stdio MCP bridge (proxies to api.releases.sh)
50
52
  releases admin mcp serve
51
53
  ```
52
54
 
53
- 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.
55
+ 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.
54
56
 
55
57
  ## Authentication
56
58
 
@@ -70,7 +72,7 @@ These can also go in a `.env` file — Bun auto-loads it when running from sourc
70
72
  ## Common Mistakes
71
73
 
72
74
  - `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).
73
- - Slug renames (`admin source update <slug> --slug new-slug`) require `--confirm-slug-change` because they break web links.
74
- - `releases admin source fetch` with no slug or filter is blocked in remote mode. Use `--stale`, `--unfetched`, `--retry-errors`, `--changed`, or a source slug.
75
+ - Slug renames (`admin source update <identifier> --slug new-slug`) require `--confirm-slug-change` because they break web links.
76
+ - `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).
75
77
  - Default fetch cap is 200 releases per source (GitHub pagination limits). Use `--max <n>` or `--all` to override.
76
78
  - `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 CHANGED
@@ -37,9 +37,10 @@ Statuses on the Lookup section: `INDEXED` (just materialized), `EXISTING` (alrea
37
37
 
38
38
  ```bash
39
39
  releases tail # across all sources
40
- releases tail next-js # one source (by slug)
41
- releases tail --org vercel --count 20 # whole org
42
- releases tail --product nextjs # one product
40
+ releases tail next-js # one source (slug)
41
+ releases tail src_abc123 # one source (typed id)
42
+ releases tail --org vercel --count 20 # whole org (org_…, slug, domain, name, or handle)
43
+ releases tail --product nextjs # one product (prod_… or slug)
43
44
  releases tail --type feature # filter by release type
44
45
  releases tail --json
45
46
  ```
@@ -48,9 +49,9 @@ releases tail --json
48
49
 
49
50
  ```bash
50
51
  releases list # all sources
51
- releases list next-js # detail for one source (by slug or id)
52
- releases list --org sentry # filter by organization
53
- releases list --product nextjs # filter by product
52
+ releases list next-js # detail for one source (src_… or slug)
53
+ releases list --org sentry # filter by organization (org_…, slug, domain, name, or handle)
54
+ releases list --product nextjs # filter by product (prod_… or slug)
54
55
  releases list --query shadcn # name / slug / url substring
55
56
  releases list --has-feed # sources with a discovered feed URL
56
57
  releases list --category ai # filter by category
package/skills/releases-mcp/SKILL.md CHANGED
@@ -33,15 +33,14 @@ If the query returns no results, try variations:
33
33
 
34
34
  ### Step 2: Choose the Right Tool
35
35
 
36
- - **"What's new?" / "Latest releases"** → Use `get_latest_releases` with the organization or product slug
36
+ - **"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)
37
37
  - **Specific feature or keyword across orgs + catalog + releases** → Use `search` (unified) with a descriptive query; narrow via `type: ["releases"]` etc.
38
38
  - **Releases-only search** → Use `search_releases` (kept for back-compat) when you only want release rows
39
39
  - **Single release by id** → Use `get_release` when you already have a `rel_` id (search results include ids)
40
40
  - **Catalog deep-dive (product or standalone source)** → Use `get_catalog_entry` for metadata, tags, and linkage
41
41
  - **Organization detail** → Use `get_organization`
42
- - **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.
43
- - **Compare two products** → Use `compare_products` with an array of two product slugs
44
- - **Summarize recent activity** → Use `summarize_changes` with the product slug
42
+ - **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.
43
+ - **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.
45
44
 
46
45
  ### Step 3: Present Results
47
46
 
@@ -53,6 +52,6 @@ If the query returns no results, try variations:
53
52
  ## Guidelines
54
53
 
55
54
  - Pass the user's full question context into query parameters for better relevance
56
- - When the user mentions a time range ("last month", "since v4"), use the `days` parameter on `get_latest_releases` or `summarize_changes`
55
+ - When the user mentions a time range ("last month", "since v4"), use the `days` parameter on `get_latest_releases`
57
56
  - If a product isn't found, say so clearly — don't fabricate release information
58
57
  - For comparison questions, both products must be indexed; if one isn't found, explain which is missing