Menu
How to create, delete, list, validate, and manage changelog sources — covers ignored/blocked URLs, duplicate detection, and the validation workflow
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Routine maintenance of indexed organizations — fetch all sources, regenerate overviews, verify data quality. Use when asked to "update", "refresh", or "maintain" one or more orgs, or when doing periodic sweeps of the registry.
Generate or refresh an org's AI overview from recent releases. Use when asked to "regenerate", "rewrite", or "refresh the overview" for one or more orgs, or as the regen step inside a maintaining-orgs run.
How to find, evaluate, and recommend the best ingestion method for changelog URLs — covers feed discovery, provider detection, GitHub API, markdown sources, and scraping fallback
Backfill a changelog source's full history locally in Claude Code via the backfill-source / backfill-sweep dynamic Workflows — preflight-gated, window-capped, budget-gated extraction written through the idempotent /batch upsert, with no remote extraction inference bill. Use when a source has a lot of history to pull in and running the remote update workflow per window would be too expensive. Local Claude Code only.
Put a challenge-blocked or unreliable scrape source on the external Firecrawl monitoring backend, or triage one that's already on it. Use when a page sits behind a bot challenge our Browser Rendering can't clear, when render keeps returning an empty shell, when enabling/disabling/tuning a monitor, or when a Firecrawl-backed source went quiet or ingested wrong content. Operator skill; requires admin API access and prod-only Firecrawl bindings.
Group releases that cover the same underlying launch so readers see one story instead of three. Use when manually curating an org's coverage — reconciling a window of recent releases, fixing a bad automatic grouping, or linking coverage the deterministic clusterer can't see. Decide which item is the best entry point for the average reader and mark it canonical. Local Claude Code operator skill; ingest-time grouping is deterministic code, not this skill.
| name | managing-sources |
| description | How to create, delete, list, validate, and manage changelog sources — covers ignored/blocked URLs, duplicate detection, and the validation workflow |
Operational guide for managing changelog sources.
Operations can be performed via CLI commands or typed MCP/agent tools. Use whichever interface is available in your context.
| Operation | CLI | Typed tool |
|---|---|---|
| List sources | releases list [slug] --json [--org <org>] [--query <text>] [--has-feed] [--category <c>] [--compact] [--limit <n>] [--page <n>] | list_catalog (scoped by organization) or search with type: ["catalog"] for query-style lookup |
| Create source | releases admin source create <name> --url <url> [--type <type>] [--org <org>] [--feed-url <url>] [--primary] | manage_source action "add" with name, url, type, organization, feed_url, is_primary (type auto-detected if omitted; only pass is_primary=true when the source is the org's primary changelog — see "Primary Sources") |
| Create App Store source | releases admin source create-appstore <url-or-id> [--platform ios|macos] [--org <slug>] [--product <slug>] [--storefront <code>] | (no typed tool yet — CLI only) |
| Update source | releases admin source update <identifier> [--primary] [--priority <p>] | manage_source action "edit" with identifier, is_primary, fetch_priority, name, url, type (use only when changing an already-added source; prefer setting flags on "add") |
| Delete source | releases admin source delete <slug> [--ignore --reason <reason>] | manage_source action "remove" with identifier |
| Fetch releases | releases admin source fetch <slug> [--dry-run] [--max <n>] | manage_source action "fetch" with identifier |
| Get latest releases | releases tail [slug] --json [--org <org>] | get_latest_releases with source, organization, limit params |
| Search releases | releases search <query> --json | search with type: ["releases"], query, limit |
| Evaluate URL | releases admin discovery evaluate <url> --json | evaluate_url with url param (optional dry-run; manage_source action "add" auto-evaluates) |
| Create org | releases admin org create <name> [--domain <d>] [--description <t>] [--category <c>] [--tags <t1,t2>] | manage_org action "add" with name, domain, description, category, tags |
| Update org | releases admin org update <slug> [--name <n>] [--domain <d>] [--tier <t>] [--billing-customer-id <id>] | manage_org action "edit" with identifier, name, domain, description, category (--tier and --billing-customer-id are CLI-only; no typed-tool equivalent) |
| Get org | releases admin org get <slug> --json | get_organization with identifier |
| Add tags to org | releases admin org tag add <slug> <tags...> | manage_org action "tag_add" with identifier, tags |
| Link account | releases admin org link <slug> --platform <p> --handle <h> | manage_org action "link_account" with identifier, platform, handle |
| Create product | releases admin product create <name> --org <org> [--category <c>] [--tags <t>] | manage_product action "add" with name, organization, category, tags |
| 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-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.
Search for existing sources with optional filters:
Use --json (CLI) for structured output. Typed tools always return JSON.
Required: name and url. Optional: type (github, scrape, feed, agent — auto-detected from URL if omitted), organization (org ID or slug to associate with), feed_url (direct feed URL if known). App Store apps (appstore type) are not created this way — use create-appstore (below); source create rejects --type appstore and pasted apps.apple.com URLs with a pointer to it.
On slug collision the API auto-suffixes (blog → blog-2, -3, …) and the created row in the response tells you the resolved slug — no rename-and-retry needed. Reserved words never auto-suffix: slugs like changelog, releases, sources, api, admin, new, list (RESERVED_NESTED_SLUGS in packages/core/src/reserved-slugs.ts) return 409 slug_reserved — pass an explicit non-reserved --slug / slug instead.
App Store apps need a dedicated command because the create flow resolves the iTunes listing, mints the current version as the first release, and backfills the product's avatar with the app icon. There is no typed-tool equivalent yet — this is CLI-only:
releases admin source create-appstore <url-or-id> [--platform ios|macos] [--org <slug>] [--product <slug>] [--storefront <code>]
<url-or-id> accepts an apps.apple.com/.../id<trackId> URL, a bare numeric track ID, or an appstore:<trackId> coordinate. --platform defaults to ios (macos = Mac App Store); --storefront defaults to us.
Pre-create the product for a clean name. With no --product, the endpoint names a new product after the (often verbose) App Store title — e.g. "Shopify: Sell online/in person". To control the name, create the product first and reference it:
releases admin product create "Shopify" --org shopify
releases admin source create-appstore https://apps.apple.com/us/app/shopify/id719892358 --org shopify --product shopify
Keep writes serial. The endpoint resolves the listing on the fly; concurrent creates for a brand-new org/product race on the org/product slug uniqueness constraint. Add one app at a time.
The command is idempotent on the app's track ID — re-running reports the existing source instead of creating a duplicate.
YouTube channels and playlists need a dedicated command because the create flow resolves the channel/playlist to its Atom feed, mints a video source, and backfills current videos as releases (description-only, summarizer-cleaned, marketing-filtered):
releases admin source create-video <channel-or-playlist-url> --org <slug> [--product <slug>]
<channel-or-playlist-url> is a YouTube channel (youtube.com/@handle, /channel/<id>) or playlist (/playlist?list=<id>) URL.--org is required and must already exist — unlike create-appstore, no org is derived from the channel. Pass a slug or a typed org_… id. --product <slug> optionally attaches the source to an existing product.source create for a YouTube URL. It builds a feed source whose parser drops media:group/media:description, leaving a source with titles and dates but empty release bodies — a silent failure that needs deleting and re-creating to fix. create rejects YouTube URLs with a pointer to create-video.Don't prefix names with the org name. The org is already shown as context on every page — repeating it in each child source produces noise like "Datadog › Datadog dd-trace-py". Pick the bare, recognizable name instead.
Rules, in priority order:
DataDog/dd-trace-py → dd-trace-py, vercel/next.js → next.js. That's the name devs already recognize; the owner/repo byline underneath disambiguates.Datadog Browser SDK → Browser SDK, Stripe API Changelog → API Changelog.Claude Code, GitHub Actions, Google Cloud Run, Amazon S3 — people say them that way. If you strip the prefix and what's left is the actual name people use, strip. If stripping produces something nobody would recognize on its own, keep the prefix.Datadog Blog, Vercel Engineering Blog — "Blog" alone is meaningless, and org-prefix is the standard convention. Same for "Newsroom", "Announcements".Next.js, not Vercel Next.js. A product under Datadog whose actual name is Agent stays Agent — the org context above it already says Datadog.When in doubt: would a developer reading this name on its own (with the org already shown above) recognize what it is? If yes, strip. If no, keep the prefix.
Grouping sources into products. Most companies are single-product — leave productSlug/productName unset and sources attach directly to the org (the default).
Only when a company ships 2 or more genuinely distinct products — each with its own identity and release cadence (Vercel → Next.js, Turborepo, SWR; Datadog → APM, RUM, Browser SDK) — tag each discovered source with the product it belongs to: productName (canonical name, same naming rules as sources — no org prefix) and productSlug (stable kebab-case, per-org unique).
A product is a distinct offering, not:
If you can't name 2+ distinct products with confidence, tag nothing. Spurious products are worse than none.
When creating an org, include a brief one-sentence product description. This grounds AI summaries for lesser-known products, and it's also the primary signal for the entity vector index — the search tool's catalog path matches on description + category, not just name. A good description noticeably improves recall.
Adding or editing an org, product, or source triggers an entity embedding into the registry vector index in the background (fire-and-forget on the worker, never blocks the write). PATCHes are gated on the embed-relevant fields (name, description, category, domain, url) actually changing, so cosmetic edits and poll-driven metadata bumps don't re-embed. There's no manual step — if a write succeeds, treat the embedding as in-flight. If you ever need to verify or backfill, run releases admin embed status and then releases admin embed entities (remote mode only).
When removing discovery results, also ignore the URL to prevent re-discovery. In CLI: releases admin source delete <slug> --ignore --reason "...". With typed tools: call manage_source action "remove" then exclude_url action "ignore".
A URL ignored for one org can still be valid for another org. Always scope ignores to the relevant organization.
For spam domains and known-bad URLs that should never be added for any org. Use block_type "domain" to block an entire domain.
After adding a source, validate it:
--dry-run for preview, then real fetch; typed tools: manage_source action "fetch")An org can have one source marked as its primary changelog — the main, company-wide changelog.
is_primary is conditional, not default. Only set it when the source you are adding is clearly the org's primary changelog:
example.com/changelog) — set is_primary=true on the add.is_primary. Leave the existing primary alone.When it does apply, set it on the add call in one step, not via a follow-up edit:
manage_source(action="add", name="Changelog", url="https://example.com/changelog", organization="example-corp", is_primary=true)
The same applies on CLI: pass --primary to releases admin source create, not a follow-up source update.
Use releases admin source create --primary or manage_source(action="add", ..., is_primary=true) when adding the source in the current onboarding flow; reserve releases admin source update --primary or manage_source(action="edit", is_primary=true) for promoting a source that already existed before this session.
That promotion path is only for sources added in an earlier session — never in the same flow as the add.
A playbook is a per-org skill for fetching that org's releases. Same mental model as the global skills in this corpus, scoped to one organization. Agents load the playbook into context alongside global skills whenever they fetch from this org — the playbook overrides general rules with the org's specific behavior (naming conventions, what counts as a release, cross-source dedup, rollup cadence).
Each playbook has two layers:
Always read the playbook before fetching or working with an org's sources. Typed tool: manage_playbook action "get" with organization param. CLI: releases admin playbook <org>. If no playbook exists yet, one will be auto-generated on the next source mutation (add/edit/remove).
The same rubric you would use to author any skill in this corpus applies here. A playbook is durable, instruction-shaped guidance for a future fetch agent that has never seen this org before. It is not a status report, not a bug log, not a record of what happened during onboarding.
Three different shapes of information end up needing a home during onboarding and fetching. Each has its own destination. Routing facts to the wrong one is the most common authoring mistake.
| Shape of fact | Home | Read by |
|---|---|---|
| Target-shaped, durable, org-specific (DOM hooks, IP blocks, repo splits, monorepo patterns, version format, scope decisions). | Playbook — manage_playbook(action=update_notes). | Every future fetch agent for this org. |
| Org-specific raw observation, possibly noisy or single-session (a redirect chain you saw, a candidate URL you probed, a quirk you suspect but haven't confirmed). | releases-errata memory store, /orgs/<org_id>/observations.md for resolved orgs, /discovery/global.md for cross-org / pre-resolution notes. | Future discovery and fetch agents in managed-agent sessions. |
| Harness-shaped or adapter-shaped — any fact that's true about our code, MCP tool, or fetcher rather than the target. ("Adapter X errors with Y", "MCP tool Z arrived as custom_tool_use", "fetch returns 0 even with feedUrl set"). | releases-tool-notes memory store, /tools/<tool>.md, /mcp/<server>/<tool>.md, /harness/notes.md. | Future managed-agent sessions across all orgs. |
If you have memory stores attached, log to the right store and leave the playbook out of it. If you don't (e.g. local Claude Code sub-agents), drop facts that don't pass the playbook keep test — don't relocate them into the playbook just because there's nowhere else to put them.
Before you write a sentence in the playbook, ask: would a brand-new fetch agent six months from now, fetching this org from a clean harness, still need this fact?
If yes — keep it. If no — drop it (or, in a managed-agent session, route it to errata or tool-notes).
| Keep | Drop |
|---|---|
| Network or platform behavior of the target (IP blocks, geo gates, auth walls). | Transient errors that happened during onboarding. |
| Page-structure facts the parser needs (DOM hooks, version-keyed headings, date format). | Symptoms of bugs in our adapters or harness ("returns 'Missing feedUrl in metadata' even though it's set"). Those go to releases-tool-notes. |
Site-wide vs scoped feed gotchas (the <link rel="alternate"> resolves to the wrong feed; force a specific URL and feedType). | Notes that pause a source pending an internal fix ("Re-evaluate after harness fix", "Do not re-enable until X is investigated"). |
Org / repo naming history and split (googleapis vs google-gemini, deprecated mirror repos). | Anything phrased as a follow-up engineering task. |
| Monorepo / per-package release-tag patterns; what the real artifact is (CHANGELOG.md vs Releases). | Speculation about why something failed if you have no evidence. |
| Pre-release / nightly tag noise that's expected and ongoing. | Self-reporting that the agent should "investigate" or "look into" something later. |
| Scope decisions: which sources are canonical, which siblings to skip and why (mirror site, marketing blog, archived repo). | Restating what's already in the auto-generated header (source list, last-fetched dates). |
| Cadence and content depth as observed signals (cite real examples). | Cadence claims with no observed basis ("probably ships weekly"). |
Do not direct the agent to file issues, write to a notes field elsewhere, or trigger any follow-up engineering process from inside the playbook. Issue tracking is a separate, human concern. Agents do not self-report engineering work in the body.
The body has three sections, in order. Use these exact headings — no fourth section, no renamed headings.
### Fetch instructions — One short paragraph per active source. Imperative voice. Tell the next agent what to do and what to expect:
renderRequired: false, crawl mode, paused).If a source is paused, say why in target-specific terms ("archived and superseded by X", "low star count, lower than the canonical Y SDK"). Do not say "paused pending bug fix" — that's a tool-notes concern, not a playbook fact.
If the org publishes seasonal, quarterly, or annual rollup pages instead of incremental entries (Shopify Editions, Brex Fall Release, Ramp quarterly blog), say so here and tell the parser to classify matching pages as type: rollup. Example: "Ramp publishes quarterly rollups at /blog/new-on-ramp-q*-* and monthly editions at /blog/new-on-ramp-*-edition. Classify all entries from this source as type: rollup." The parsing-changelogs skill ("Classifying Rollups" section) covers what rollups look like; the playbook captures the org-specific signal.
Skip purely-restated metadata. The reader can already see the URL and type in the auto-generated header.
### Traps — Bullet list. Each bullet starts with a bolded trigger label describing the situation, then a short imperative explaining what to do.
Only include traps that pass the keep test. Good traps name a property of the target that would cause a future fetch to do the wrong thing:
<link rel="alternate"> on every doc page resolves to the global blog feed. Set feedUrl explicitly to the section index.xml and force feedType=atom.org/foo-deprecated is archived; the canonical repo lives at org/foo. Don't re-add the mirror.metadata.firecrawl) or pause it with the blocker recorded.Do not include adapter or harness bugs ("feed returns 'Missing feedType in metadata'") — route to releases-tool-notes. Do not include onboarding-time errors not tied to a target property. Do not include future engineering work the agent thinks should happen.
### Coverage — Two to four sentences. Which sources are canonical, what's covered, what's intentionally skipped (with a one-clause reason — "blog feed is site-wide marketing", "mobile SDKs live under a different org"). Optionally a short cadence summary if it varies meaningfully across sources.
Do not list "missing" sources as a to-do. If a surface isn't worth tracking, say it's out of scope and why. If a surface is worth tracking but doesn't exist yet ("API changelog is currently a 404"), one sentence noting that the URL was probed and what the next agent should re-check is fine.
<h2> as version boundaries", "Skip nightly tags". Not "we should…" or "the agent could…".It's fine to write a short trap that records a real, durable target property even if you couldn't fully exploit it during onboarding — for example, "the API changelog is a static HTML page with no feed; rely on scrape" or "developer changelog URL returned 404 — re-check on next visit." That's target-shaped.
It is not fine to write "fetch returned an error during onboarding so we paused it." That's session-shaped and adapter-shaped. If a source is failing for reasons you can't attribute to the target, pause the source without an explanation in the playbook body — the source's own state already records that it's paused. In a managed-agent session, log the underlying tool error to releases-tool-notes.
Always call manage_playbook(action=get) before writing. Preserve durable trap entries from prior runs. If you're rewriting a section, fold prior facts that still pass the keep test into the new draft instead of dropping them.
In a managed-agent session, also read releases-errata /orgs/<org_id>/observations.md (and /discovery/global.md if it predates the org being resolved) before writing. Some of those observations may have stabilized into facts worth promoting into the playbook; others are still hints and stay in errata.
Compilation (fast, from metadata only): Write notes based on source metadata — URL, type, priority, parseInstructions. Good for bulk coverage but claims about page structure, cadence, and version format are inferred, not verified. Suitable for initial scaffolding or low-priority orgs.
Verified (thorough, from actual data): Before writing, query release data and fetch logs to ground every claim in observation:
releases list <slug> --json — Check actual version formats, titles, content length, publishedAt patternsreleases admin source fetch-log <slug> --json — Check for errors, success rates, stale datalastFetchedAt to the cadence you measure in step 1. An empty fetch-log is not the same as "ingested successfully". If lastFetchedAt is older than ~3× the typical interval between releases (e.g. last fetch was 5 weeks ago for a weekly source), the cron is no-op'ing this source. The likely cause: the changeDetector is unreliable and nothing else is flagging the source. Don't rubber-stamp it as healthy — surface this to the human operator, or (if you authored the unreliable quirk yourself) reconsider whether a more targeted detector would work, e.g. body-hash-filtered for SSR pages whose raw body churns but article markup is stable, or body-hash against a CSS-selector slice in a future revision.Use the verified approach for high-value orgs, when onboarding new orgs with scrape sources, or when refreshing stale compilation-only playbooks. The difference: "this source likely needs JS rendering" (compilation) vs "all 50 releases have empty content — the RSS feed delivers summaries only, needs crawl mode on per-release pages" (verified).
Write notes during onboarding after you've fetched and validated sources. Update them when you discover new quirks or when source behavior changes. If notes are empty or stale, write them before doing fetch work — future agents (including yourself in later sessions) will benefit.
Updating notes: Use manage_playbook action "update_notes" with the complete notes content — it replaces the entire notes section. You can rewrite, reorganize, or clear notes at any time.
Frontmatter (typed config): If the existing notes begin with a YAML frontmatter fence (--- lines at the very top), preserve that block verbatim when you update. It carries typed configuration that cron code reads directly — e.g. fetchQuirks per-source change-detector hints. Write your markdown below the closing ---. Example:
---
fetchQuirks:
brex:
changeDetector: etag
rationale: ETag stable across HEADs
---
### Fetch instructions
(your prose notes here)
Only edit the fence when a source's fetch behavior genuinely changes (e.g. you verified a new ETag stability, or the site switched to SSR). Valid changeDetector values: etag, content-length, body-hash, body-hash-filtered, unreliable. Optional keys: tier (normal | low), changeProbeUrl (alternate HEAD target).
Pick body-hash-filtered when the page is SSR (Next.js / Vercel / Astro) and the raw body hash churns per-request (hydration tokens, chunk URLs, nonces) but the article markup is stable. The detector strips <script>, <style>, <link>, <meta>, and HTML comments before hashing. If body-hash already works, leave it — body-hash-filtered is for cases that would otherwise be tagged unreliable and lean on the daily force-drain cron.
Changing source configuration: The header reflects current source metadata. To change things like parseInstructions, fetchPriority, or crawlEnabled, use manage_source action "edit" with metadata — the header updates automatically.
Product context: Playbooks group sources by product when products are configured. Some sources (like an org's engineering blog) aren't tied to a specific product but may contain content relevant to any product under that org — the playbook calls these out as "Organization-Level Sources" with a note about which products they may cover.
The scrape adapter can fetch pages with or without a headless browser. Static-site providers (Docusaurus, VitePress, WordPress, Ghost, Mintlify) are fetched without rendering by default — this is ~10-30x faster.
To override the default for a specific source:
releases admin source update <identifier> --no-render — force fast fetch (no headless browser)releases admin source update <identifier> --render — force headless browser renderingUse --render when you know a source needs JavaScript execution. Use --no-render when you've verified the content is in the initial HTML for a provider not yet in the static list.
After adding a new scrape source with an unknown provider, check the first fetch results. If content is complete, consider setting --no-render and noting the provider behavior in the playbook.
Blocked by a Cloudflare Managed Challenge? --render/--no-render only choose how we fetch — they don't help when the page returns a bot challenge that fails browser rendering itself (symptom: persistent no_change / 0 releases on a page that clearly updates, e.g. some vendor help pages). For those, the external Firecrawl monitoring backend can fetch the page instead. It's enabled per source via the admin API (POST /v1/sources/:slug/firecrawl/sync { enabled: true }), backend-only — not via a metadata edit (which skips monitor creation). See docs/architecture/firecrawl-monitoring.md.
The on-demand lookup endpoint (POST /v1/lookups) can materialize a hidden source row for any {org}/{repo} GitHub coordinate a user searches for. These rows carry discovery = 'on_demand' and isHidden = true. They fold into the normal cron fetch at low priority but skip AI features (overviews, summarization, playbook regen).
If you encounter a source with discovery = 'on_demand' during an agent task:
manage_source action "edit" with discovery: 'curated' and flip isHidden to false. Also edit the name if it was auto-generated from the coordinate.discovery = 'on_demand'. Promote it with manage_org action "edit" with discovery: 'curated'.Owners can activate a stub for their own domain via the anonymous self-serve lane (POST /v1/listing/{validate,activate}); an activation with requestTracking: true stamps tracking_requested_at — a demand signal, not an auto-onboard. Reviewing that queue is a curator task:
GET /v1/orgs?trackingRequested=1 (admin-gated). Rows carry trackingRequestedAt and zeroed stats.https://<domain>/.well-known/releases.json), then run the normal onboarding ladder (finding-changelogs) over the declared locators. Materialization is fill-if-empty and never clobbers curator fields.relv_ token via .well-known/releases-verify.txt or DNS TXT) prove domain control for self-serve Tier-1 promotion — a verified claim raises confidence but doesn't skip source vetting.The AASA/assetlinks scan (docs/architecture/well-known-config.md → Mobile-app discovery) lands a domain's iOS apps as paused, hidden appstore candidates (discovery: "on_demand", isHidden: true, fetchPriority: "paused") — deliberately off every public surface until reviewed, because app-site associations routinely include third-party apps (SSO/wallet integrations). Reviewing a candidate:
manage_source action "edit" (or releases admin source update) flipping fetchPriority to normal, isHidden to false, and discovery to curated; fix the auto-derived name per the naming rules above.org.metadata.discoveredApps) — there is no Play Store source type; don't try to materialize one.On-demand re-scan for one org: POST /v1/orgs/:slug/discover-apps (write scope, ?dryRun=1 to preview).
Before adding sources, search for overlapping URLs.
Common duplicates:
www. prefix