hub-operations
Operate Hugging Face Hub repositories and API resources with authenticated or mocked Python workflows, explicit revision control, safe mutations, and actionable error recovery.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- hub-operations
- license
- Apache-2.0
- metadata
- { "disco-role": "operating" }
- description
- Operate Hugging Face Hub repositories and API resources with authenticated or mocked Python workflows, explicit revision control, safe mutations, and actionable error recovery.
- disable-model-invocation
- true
02 资源文件 3
- 参考文档references/api-reference.md20.7 KB
- 参考文档references/troubleshooting.md15.7 KB
- 参考文档references/workflows.md26.9 KB
03 SKILL.md 正文
Hub Operations
Use this sub-skill for Python workflows that discover or mutate Hub API
resources: repositories, files and commits, refs, collections, cards,
discussions and pull requests, and webhook registrations. It is grounded in
huggingface_hub 1.29.0.
Trigger And Route
This is the routing surface, not a full API manual. Select the smallest linked reference that covers the request, then keep the operation and verification boundaries visible.
| Request signal | Route | Read next |
|---|---|---|
| create/inspect/search a repo, list files/tree/commits, or manage refs | repository and discovery | API reference |
| upload/copy/delete files, create a commit or PR, or pin a parent SHA | files and commits | Workflows |
| cards, metadata, collections, discussions, or PR review | collaboration and metadata | API reference and Workflows |
| webhook registration, scope, enable/disable, or deletion | webhook resources | Workflows |
| token precedence, access, 401/403/404/409/412/429, or ambiguous mutation | authentication and recovery | Troubleshooting |
| deterministic unit-style behavior without Hub access | mocked HfApi case | Mocked recovery case |
Use this route when the request includes one or more of:
- create, list, inspect, update, delete, move, or duplicate a model, dataset, or Space repository;
- upload, delete, or server-side copy repository files; create a commit or PR;
- inspect a revision or manage branches and tags;
- search models, datasets, or Spaces and interpret returned info objects;
- create or curate collections and repository cards;
- read or manage discussions, PRs, and their events;
- create, inspect, enable, disable, update, or delete webhook resources;
- configure or diagnose authentication needed upstream of these operations;
- identify and recover from Hub API errors, including stale-parent conflicts.
Route elsewhere when the primary task is:
- download/cache behavior,
HfFileSystem, or buckets: siblingdownloads-and-storageroute; - hosted inference or Inference Endpoints: sibling
inference-and-endpointsroute; - exact
hfcommand syntax, output modes, or shell automation: siblingcli-and-automationroute; - Jobs, sandboxes, Space runtime/hardware, or a deployed webhook server:
sibling
hosted-compute-and-integrationsroute.
Webhook registration is owned here; receiving payloads in a server is not. Space repository metadata is owned here; running or scaling the Space is not.
Operating Contract
- Classify the operation. Label every step
READ-ONLY,MUTATION, orDESTRUCTIVE. Do not hide a mutation inside an inspection step. - Resolve identity. Record
repo_id,repo_type,revision, endpoint, and token source before calling the API. Prefer explicitnamespace/name; Python uses singular repo types:model,dataset,space. - Authenticate safely. Prefer
HF_TOKENor a previously saved login. Never hardcode, log, print, serialize, or include a token in an exception report. Use a write-scoped token only for mutations. - Inspect before mutation. Fetch the target object and revision, confirm ownership/type/visibility, capture the current SHA when concurrency matters, and preview local paths or remote resources affected.
- Use explicit mutation intent. Set a meaningful
commit_message; passrepo_type; chooserevision; usecreate_pr=Truewhen review is safer; useparent_commitfor optimistic concurrency. - Verify the result. Assert returned IDs/types and inspect the resulting
revision. For PR commits, verify
CommitInfo.pr_revisionand inspect that ref rather than assumingmainchanged. - Guard destructive actions. Require an exact target display, a dry-run plan, and explicit confirmation immediately before delete, merge, move, or visibility reduction. Re-inspect after confirmation if the workflow waited.
- Recover narrowly. Branch on typed exceptions and HTTP status. Retry only operations shown to be safe, bounded, and still valid after re-read.
Safety confirmations
Deletion, move, visibility reduction, branch/tag deletion, collection or
webhook deletion, irreversible comment hiding, and PR merge require a
read-only plan, a dry-run gate, exact target confirmation, an immediate SHA or
state recheck, one mutation, and a post-check. --yes or APPLY=1 is only a
mechanism; non-interactive use must receive approval from an upstream reviewed
control. See the guarded workflow.
Core Concepts
repo_idis normallynamespace/name. A bare name can use the authenticated namespace for creation, but explicit IDs are safer in automation.repo_type=Nonemeans a model for most APIs. Always passdatasetorspace; never pass plural forms to Python methods.- A revision can be a branch, tag, commit OID, or PR ref such as
refs/pr/3. Mutating methods normally default tomain; verify the method-specific constraints before combiningrevisionandcreate_pr. exist_ok=Truemakes repository, branch, or tag creation tolerant of an existing target. It does not prove that the existing resource has the requested visibility or settings. Collections spell thisexists_ok.visibilityacceptspublicorprivate, plusprotectedfor Spaces. Do not pass bothprivateandvisibility.parent_commitis a full or short commit OID used as an optimistic concurrency check. On conflict, fetch the new head and re-evaluate; do not blindly drop the check.create_pr=Trueplaces a proposed commit on a PR ref.CommitInfoexposespr_url,pr_num, andpr_revision;mainis unchanged until merge.commit_messageis the commit summary. Keep it specific and never place credentials, signed URLs, or private payload content in it.- API listings are iterables and returned info fields are often optional.
Limit iteration and test for
None; aninfoquery usually contains more detail than a list query.
Choose The Client Surface
Use HfApi(...) when several calls should share an endpoint, token,
user-agent, or headers. Root-level helpers such as create_repo,
upload_file, and list_models expose the same public operations and are
convenient for isolated calls. Keep one configured client through a workflow
so endpoint and credentials cannot drift.
Read API reference before writing calls or
interpreting RepoUrl, info, collection, discussion, webhook, or commit
objects. It contains signatures verified from the installed 1.29.0 package.
Read workflows when implementing create → inspect → upload → revision/PR flows, discovery, refs, cards, collections, discussions, webhook resources, or a check-before-delete plan. Examples explicitly mark read-only and mutation boundaries.
Read troubleshooting when credentials, identity, access, revisions, concurrency, upload patterns, rate limits, network failures, or destructive safeguards are involved. Follow its typed, bounded recovery rules instead of broad retries.
Output Expectations
Return or record, without secrets:
- resolved endpoint,
repo_id,repo_type, and requested revision; - mutation classification and whether confirmation occurred;
- observed starting SHA and resulting SHA or PR ref when applicable;
- concise fields from returned objects, not raw object dumps containing secrets (notably webhook resources);
- verification observations: resource exists, expected path/ref/card/event is present, or resource is absent after an approved deletion;
- typed error, HTTP status, request ID, recovery attempted, and any remaining ambiguity.
Stop rather than guess when target ownership, repo type, destructive intent, credential scope, or post-conflict content validity cannot be established.
04 同仓库更多 Skills
passnet-triton-opt
Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.
passnet-solve
END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.
passnet-skill
PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.
passnet-pattern-fusion
Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.
passnet-orchestrate
Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.
passnet-feedback
Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).