Hf Release Notes

HF Release Notes

Overview

Generate release notes for huggingface_hub from cached PR JSON files. This skill reads PR metadata, categorizes entries, and produces a formatted markdown release notes document.

Output directory: The prompt will specify the output directory as <output_dir>. All paths below use this placeholder.

Workflow

1. Read PR data

Read all PR JSON files from <output_dir>/tmp/pr_*.json. Each file contains:

{
  "number": 1234,
  "title": "...",
  "author": "username",
  "merged_at": "2026-01-15T10:30:00Z",
  "body": "...",
  "labels": ["highlight", "cli"],
  "url": "https://github.com/huggingface/huggingface_hub/pull/1234",
  "doc_diffs": [
    {
      "filename": "docs/source/en/guides/cli.md",
      "status": "modified",
      "patch": "@@ -10,6 +10,10 @@ ..."
    }
  ]
}

The doc_diffs field contains unified diffs for any .md files under docs/ that were changed in the PR. This is empty ([]) for PRs with no documentation changes.

2. Identify highlights

A PR should be highlighted if:

• It has the "highlight" label on GitHub, or
• You judge it significant enough to deserve a detailed section (e.g., a major new

feature, a meaningful UX improvement, or a notable breaking change) even without the label.

Use your judgment — not every feature PR needs a highlight, but don't limit highlights to only labeled PRs. Each highlight section follows this structure:

1. Emoji header — e.g., ## 🖥️ New CLI commands 2. Prose summary — 2-5 sentences describing the user-visible change in flowing text. Avoid bullet points here; write natural sentences. Only use bullets if the content truly calls for a list (e.g., enumerating 4+ distinct sub-features). 3. Code examples — if the PR introduces new commands or APIs, include a fenced code block with a concrete usage example (cherry-pick from doc diffs when available). 4. PR attribution lines — one bullet per PR that contributed to this highlight: - PR title by @author in #1234

3. Classify standard items

For non-highlight PRs, classify into sections using references/sections.md heuristics based on:

• PR labels
• PR title keywords
• PR body content

4. Use doc diffs and fetch relevant documentation

For highlighted PRs and other PRs that introduce new features, commands, or APIs:

Use doc diffs first:

• Check the doc_diffs field in the PR JSON. If present, these contain the actual

documentation changes made in the PR (unified diff format).

• Use these diffs to understand what was documented, extract code examples, and write

more accurate summaries. The diffs show exactly what the PR author wrote in the docs.

• The filename field maps to a docs page URL. For example,

docs/source/en/guides/cli.md → https://huggingface.co/docs/huggingface_hub/main/en/guides/cli

Fetch full doc pages when needed: 1. Start by fetching the docs index page to discover the site structure: https://huggingface.co/docs/huggingface_hub/main/en/index 2. Based on the PR content (title, body, labels), identify which doc pages might be relevant. For example:

• A CLI PR → check https://huggingface.co/docs/huggingface_hub/main/en/guides/cli
• An Inference PR → check https://huggingface.co/docs/huggingface_hub/main/en/guides/inference
• A new API class or method → check the corresponding reference page

3. Fetch the candidate doc page to confirm it covers the feature from the PR. 4. Only include a doc link if the page genuinely documents the feature.

How to reference:

• In highlight sections, add a line like:

📚 **Documentation:** [Guide name](https://huggingface.co/docs/huggingface_hub/main/en/guides/...)

• In standard sections, append the doc link inline after the attribution when relevant:

- PR title by @author in #1234 — [docs](https://huggingface.co/docs/huggingface_hub/main/en/...)

• Do NOT add doc links for internal/CI/test PRs or PRs that don't have user-facing docs.
• Do NOT fabricate doc URLs — only link to pages you have actually fetched and verified.

5. Generate release notes

Output to <output_dir>/RELEASE_NOTES_<version>.md using the structure from references/release-notes-template.md:

• Title: # [vX.Y.Z] <tagline> (derive tagline from main highlights; always use the base version without prerelease suffix, e.g. [v1.8.0] even when generating for v1.8.0.rc0)
• One section per highlight with emoji header and narrative
• Standard sections for remaining items (only include sections with items)

6. Quality checks

Before finishing:

• Verify every PR from <output_dir>/tmp/ appears exactly once
• Do NOT include any PR that does not have a corresponding file in `<output_dir>/tmp/` — those PRs belong to a different release and must not appear in these notes
• No empty sections
• Consistent emoji headings
• Every item ends with attribution: by @author in #1234
• Doc links point to real, verified pages

Input

• Version string (e.g., "v1.3.8")
• PR JSON files in <output_dir>/tmp/

Output

• Release notes markdown at <output_dir>/RELEASE_NOTES_<version>.md

Resources

• references/release-notes-template.md: Skeleton structure for release notes
• references/sections.md: Keyword-based section mapping and guidance
• Documentation site: https://huggingface.co/docs/huggingface_hub/main/en/index

[vX.Y.Z] <Tagline>

<Emoji> <Highlight title>

<2-5 sentence prose summary of the user-visible change. Write flowing text, not bullet points. Only use bullets if truly listing 4+ distinct sub-features.>

# Optional code example when relevant (cherry-pick from doc diffs if available)
hf <command> <args>

• <PR title> by @author in #1234
• <Another related PR title> by @author in #5678

<Emoji> <Highlight title>

<Prose summary.>

• <PR title> by @author in #1234

Optional standard sections (include only if used)

💔 Breaking Change

• <PR title> by @author in #1234

🖥️ CLI

• <PR title> by @author in #1234

🤖 Inference

• <PR title> by @author in #1234

📊 Jobs

• <PR title> by @author in #1234

🔧 Other QoL Improvements

• <PR title> by @author in #1234

📖 Documentation

• <PR title> by @author in #1234

🐛 Bug and typo fixes

• <PR title> by @author in #1234

🏗️ Internal

• <PR title> by @author in #1234

Section mapping guidance

Use these heuristics to classify items. Sections are optional; include only if at least one item lands there. When in doubt, pick the most user-facing section and keep consistency within the release.

💔 Breaking Change

Keywords: "breaking", "deprecated", "remove", "removed", "incompatible".

🖥️ CLI

Keywords: "[CLI]", "hf ", "command", "help output", "ls", "skills add", "cli".

🤖 Inference

Keywords: "Inference", "InferenceClient", "provider", "text to image", "image-to-image", "embedding", "endpoint".

📊 Jobs

Keywords: "[Jobs]", "job", "jobs", "hardware", "logs", "training".

🔧 Other QoL Improvements

Keywords: "add", "support", "list", "default", "allow", "improve" without a clearer section.

📖 Documentation

Keywords: "docs", "documentation", "README", "link", "guide", "example", "typo".

🐛 Bug and typo fixes

Keywords: "fix", "bug", "regression", "incorrect", "error", "crash", "compatibility", "permissions".

🏗️ Internal

Keywords: "CI", "tests", "actions", "internal", "maintenance", "refactor", "bump", "upgrade".

Slack post template

This is the template for the Slack announcement message. The script appends the "Pinging:" section and closing line automatically — the skill only generates the body from the greeting through the pip install command.

Template

Hello @canal :hello: The next release of `huggingface_hub` (vX.Y.Z) is on its way! :tadaco:

Release notes :point_right: https://github.com/huggingface/huggingface_hub/releases/tag/vX.Y.Z

:sparkles: Highlights
 :emoji: Feature name: 1-2 sentence summary of the feature.
 :emoji: Another feature: brief description.
 A bunch of QoL improvements to the CLI:
  Sub-feature 1
  Sub-feature 2

<If breaking changes>
:warning: Breaking changes: brief description of what changed.
<If no breaking changes>
No breaking changes in this release.

We also introduced a bunch of QoL improvements and fixes!

You can try the pre-release now:
pip install -U huggingface_hub==X.Y.ZrcN

Real examples

Example 1 (v1.7.0)

Hello @canal :hello: The next release of huggingface_hub (v1.7.0) is on its way! :tadaco:

Release notes :point_right: https://github.com/huggingface/huggingface_hub/releases/tag/v1.7.0

:sparkles: Highlights
 :package: CLI Extensions : extensions can now be full pip-installable Python packages (this may have slipped into the v1.6.0 release notes but is definitely shipped here :see_no_evil:). Plus a new hf extensions search command to discover extensions from the terminal.
hf-xet bumped to 1.4.2 with upload optimizations and a fix for deadlocks on large file downloads. that should improve upload speed for large files
 A bunch of QoL improvements to the CLI:
  All list commands normalized to list / ls aliases
  Hidden --json shorthand for --format json
  num_parameters filtering in hf models list
Allow hf skills add to default to installing from the skills directory
hf auth login has a new flag --force to override  if already logged in

No breaking changes in this release.

You can try the pre-release now:
pip install -U huggingface_hub==1.7.0rc1

Example 2 (v1.5.0)

Hello @canal :hello: The next release of `huggingface_hub` (v1.5.0) is on its way! :tadaco:

Release notes :point_right: https://github.com/huggingface/huggingface_hub/releases/tag/v1.5.0.rc0

:sparkles: Highlights
:bucket: Buckets API! Create, list, sync, and manage buckets on the Hub. Sync local directories with hf buckets sync ./data hf://buckets/username/my-bucket.
:robot_face: AI-first CLI: hf skills add to install skills for Claude, Codex, etc., output options (json/table) for composability, aliases for better consistency, etc.
:fire: Spaces hot-reload: Patch Python files in a running Space with hf spaces hot-reload username/repo-name app.py.
:electric_plug: CLI Extensions: Install and run external CLI extensions from GitHub repos with `hf extensions install hf-claude`.
:chart_with_upwards_trend: Jobs: Multi-GPU training support, hf jobs hardware command, better filtering with labels, and --follow/-f logs flag.

:warning: Breaking changes: hf repo is deprecated in favor of `hf repos`. Also, hf repo-files delete has moved to hf repo delete-files. Aliases are kept for backward compatibility.

We also introduced a bunch of QoL improvements and fixes!

You can try the pre-release now:
pip install huggingface_hub==1.5.0rc0

Example 3 (v1.6.0)

Hello @canal :hello: The next release of huggingface_hub (v1.6.0) is on its way! :tadaco:

Release notes :point_right: https://github.com/huggingface/huggingface_hub/releases/tag/v1.6.0

:sparkles: Highlights
• :bucket: HfFileSystem for Buckets! Reading from buckets is as simple as pd.read_csv("hf://buckets/.../affluence.csv")  (thanks to @Quentin Lhoest).
• :computer: New CLI commands:
 hf spaces dev-mode to enable dev mode and get SSH/VSCode connection instructions (cc @Quentin Lhoest)
 hf discussions for full discussion & PR management
hf webhooks for CRUD on Hub webhooks
hf datasets parquet + hf datasets sql to discover and query dataset parquet files with DuckDB cc @Caleb Fahlgren
hf repos duplicate to duplicate any repo.
• :electric_plug: pip-installable CLI extensions: hf extensions install now supports Python packages in addition to executables
• :zap: NVIDIA provider support added to InferenceClient.

:warning: Breaking change: the deprecated direction argument in list_models, list_datasets and list_spaces has been removed. (was announced since months)

We also introduced a bunch of QoL improvements and fixes!

You can try the pre-release now:
pip install -U huggingface_hub==1.6.0rc0

Slack Announcement Message

Overview

Generate a concise Slack announcement message from existing release notes. The message is intended for internal team communication to announce a prerelease and solicit testing from downstream maintainers.

Important: You generate ONLY the message body (greeting through the pip install command). The "Pinging:" section and closing line are appended by the calling script — do NOT generate those.

Workflow

1. Read inputs

The prompt will specify:

• Version: The base release version (e.g., v1.7.0)
• RC version: The prerelease version for pip install (e.g., 1.7.0rc0)
• Release notes path: Path to the full release notes markdown file
• Output path: Where to write the Slack message

Read the release notes file first to understand what's in the release.

2. Read reference examples

Read references/slack-post-template.md. This file contains the template structure and real Slack messages from past releases. Use these to calibrate your tone, formatting, and level of detail. Match their style closely.

3. Generate the message

Write the Slack message body with these sections in order:

Greeting

Hello @canal :hello: The next release of `huggingface_hub` (vX.Y.Z) is on its way! :tadaco:

Release notes link

Release notes :point_right: https://github.com/huggingface/huggingface_hub/releases/tag/vX.Y.Z

Highlights

:sparkles: Highlights
 :emoji: Feature name: brief 1-2 sentence description
 :emoji: Another feature: description
 A bunch of QoL improvements:
  Sub-feature 1
  Sub-feature 2

Rules for highlights:

• Use Slack emoji codes (:package:, :robot_face:, :fire:, :electric_plug:, :bucket:, :computer:, :zap:, :chart_with_upwards_trend:, etc.), NOT Unicode emoji
• Keep each highlight to 1-2 sentences max — this is a summary, not the full release notes
• Drop ALL PR attribution lines (by @author in #1234)
• Drop ALL code examples and fenced code blocks
• Drop internal/CI/test items entirely
• Drop documentation-only items
• Drop bug fixes from highlights (mention them as "a bunch of QoL improvements and fixes" if there are several)
• Group related small improvements together rather than listing each individually
• Use single-space indentation for sub-items, matching the examples

Breaking changes

If there are breaking changes:

:warning: Breaking changes: brief description of what changed.

If none:

No breaking changes in this release.

Pre-release install command

You can try the pre-release now:
pip install -U huggingface_hub==<RC_VERSION>

Where <RC_VERSION> is the RC version provided in the prompt (e.g., 1.7.0rc0).

4. Formatting rules

• No markdown headers (##, ###) — Slack doesn't render these
• No bold (**text**) — use plain text or Slack formatting ( for inline code)
• Use backticks for command names and code: ` hf extensions install `
• Use Slack emoji codes (:sparkles:) not Unicode emoji
• Keep it informal and friendly — this is team communication, not a formal changelog
• Single space indent for highlight items under the :sparkles: Highlights header
• No trailing newlines at the end of the output

5. Write output

Write ONLY the message body to the specified output path. Stop after the pip install command. Do NOT include:

• The "Pinging:" section
• The "Let us know if you spot any regressions..." closing line
• Any separator lines

Input

• Version string (e.g., v1.7.0)
• RC version string (e.g., 1.7.0rc0)
• Path to the release notes markdown file
• Output path for the Slack message

Output

• Slack message body at the specified output path

Resources

• references/slack-post-template.md: Template structure and past Slack messages for tone/format reference

Social Media Drafts

Overview

Generate draft social media posts for LinkedIn and X (Twitter) from existing release notes for a huggingface_hub release. The output is a set of .txt files — multiple drafts per platform with distinct tones — ready for the team to review, edit, and publish.

Important: The prompt will specify the release notes path and output directory. Write each draft as a separate .txt file using the naming convention below.

Workflow

1. Read inputs

The prompt will specify:

• Version: The release version (e.g., v1.8.0)
• Release notes path: Path to the full release notes markdown file
• Output directory: Where to write the draft files

Read the release notes file to understand what's in the release.

2. Generate LinkedIn drafts

Generate 3 LinkedIn posts, each 150–250 words, with a distinct angle:

linkedin_professional_1.txt — Technical / professional

Write as a developer relations expert. Focus on the technical value and what problems the new features solve for ML engineers and data scientists. Use short paragraphs. Mention concrete features, APIs, or CLI commands by name. Include 2–3 relevant hashtags at the end (e.g., #MachineLearning #OpenSource #Python).

linkedin_community_2.txt — Community / ecosystem

Write as a community manager celebrating an open-source release. Emphasize the collaborative nature: thank contributors (mention a few by handle if names appear in the notes), highlight the ecosystem impact (transformers, diffusers, datasets, sentence-transformers all depend on huggingface_hub), and invite people to try it out or contribute. Warm, inclusive tone. Include 2–3 hashtags.

linkedin_tutorial_3.txt — Tutorial / practical

Write as a technical writer. Pick the 1–2 most impactful new features and show a quick before/after or a mini code snippet. The goal is to make readers think "I need to try this right now." Include 2–3 hashtags.

3. Generate X (Twitter) drafts

Generate 3 X posts. Each tweet must be under 280 characters. Separate tweets within a draft with --- on its own line.

x_announcement_1.txt — Announcement / hype

One punchy main tweet + one follow-up. Lead with the single most exciting feature. Use an energetic tone. 1–2 emoji max. The follow-up should contain a [LINK] placeholder for the release notes URL.

x_technical_2.txt — Technical / developer

One main tweet + one follow-up with a code snippet or command example. Focus on DX improvements, new APIs, or performance gains. Mention concrete method names or CLI commands.

x_thread_3.txt — Thread / storytelling

A short thread of 3–5 tweets walking through the highlights. Number them 1/, 2/, etc. The first tweet should hook the reader. The last tweet should link to the release notes with a [LINK] placeholder.

4. Picture suggestions

Every draft file must end with a picture suggestion on the last line, in brackets:

[Picture: description of suggested image, screenshot, or graphic]

Examples:

• [Picture: screenshot of the new CLI output with a dark terminal theme]
• [Picture: side-by-side code comparison showing the old vs new API]
• [Picture: infographic summarizing the top 3 features with icons]
• [Picture: collage of contributor avatars or a community celebration graphic]
• [Picture: short GIF of the new command in action in a terminal]

5. Formatting rules

• LinkedIn: natural paragraphs, no markdown headers. 2–3 hashtags at end.
• X: tweets separated by ---, each under 280 characters.
• Use [LINK] placeholder for the release notes URL (never hardcode a URL).
• No internal jargon — write for the broader ML/developer community.
• Mention "huggingface_hub" (the Python package name) and "Hugging Face Hub" (the platform).
• Do NOT fabricate features — only mention what's actually in the release notes.

6. Write output

Write each draft as a separate file in the output directory:

• linkedin_professional_1.txt
• linkedin_community_2.txt
• linkedin_tutorial_3.txt
• x_announcement_1.txt
• x_technical_2.txt
• x_thread_3.txt

Each file should contain ONLY the post text (including picture suggestion). No metadata, no headers, no extra formatting.

Input

• Version string (e.g., v1.8.0)
• Path to release notes markdown file
• Output directory path

Output

• 6 draft .txt files in the output directory

Validate Release Notes

Overview

This skill validates that release notes match the manifest exactly: all expected PRs are included, and no extra PRs from other releases are present. It fixes both missing and extra PRs.

Output directory: The prompt will specify the output directory as <output_dir>. All paths below use this placeholder.

Workflow

1. Read current release notes

Read the existing release notes from <output_dir>/RELEASE_NOTES_<version>.md.

2. Fix missing PRs

You may be provided with a list of missing PR numbers. For each missing PR:

• Read the PR details from <output_dir>/tmp/pr_<number>.json
• Check doc_diffs for documentation changes that can inform the summary
• Determine the appropriate section based on labels and title

For each missing PR:

• If it has the "highlight" label, create a new highlight section with:
• Emoji header
• 2-5 sentence summary
• Code examples if applicable
• Attribution line
• If the PR introduces a user-facing feature, check for relevant documentation at

https://huggingface.co/docs/huggingface_hub/main/en/ and add a doc link (see main skill for details on how to fetch and verify doc pages)

• Otherwise, add to the appropriate standard section:
• Match to existing sections first
• Create new section if needed (following references/sections.md)

3. Remove extra PRs

You may be provided with a list of extra PR numbers that do not belong to this release (they were shipped in a different release). For each extra PR:

• Find all references to the PR (e.g., #1234) in the release notes
• Remove the entire line or bullet point that references the PR
• If the PR was the only item in a highlight section, remove the entire highlight section
• If removing the PR leaves a section empty, remove that section entirely
• Do NOT remove PRs that are in the manifest — only remove the ones explicitly listed as extra

4. Update the file

Write the updated release notes back to <output_dir>/RELEASE_NOTES_<version>.md.

5. Verify

After updating, confirm that:

• All previously missing PRs now appear in the document
• All previously extra PRs have been removed from the document

Input

• Version string (e.g., "v1.3.8")
• List of missing PR numbers (may be empty)
• List of extra PR numbers to remove (may be empty)
• PR JSON files in <output_dir>/tmp/

Output

• Updated release notes at <output_dir>/RELEASE_NOTES_<version>.md

Resources

• references/sections.md: Section classification guidance