跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。

A Python Agent Skill Needs a Dependency Handoff, Not Just a Script

Separate single-script and project dependencies, preserve a reviewed lockfile, and hand off enough evidence to reproduce an agent's Python environment.

2026-09-10

保留发布时的原文,未自动翻译。

The failure happens after the successful demo

A Python-backed skill produces a useful report on its author's machine. A teammate tries the same task next week, and the agent installs whatever packages satisfy the available instructions. The result may fail, or it may run with a different environment that nobody recorded.

The missing deliverable is not another installation sentence. It is a dependency handoff: which source revision was reviewed, which environment was intended, how it is reconstructed, and what should happen when those assumptions no longer hold. This guide proposes that handoff for maintainers who distribute scripts with agent skills.

Methodology and selection criteria

This is a documentation-based workflow checked on September 10, 2026. We examined uv's script and project dependency documentation and pip's secure-install guidance. We did not execute a third-party skill, install these examples, or benchmark package managers.

The selection criterion is packaging shape, not popularity: one independently useful script, an installable project, or an existing requirements-based workflow. The recommendations below are our proposed acceptance rules. They do not certify package safety or promise byte-identical results across operating systems.

Decide whether the script belongs to a project

For a standalone utility, dependencies should travel with the script rather than depend on a developer's ambient environment. The uv script guide documents inline script metadata and an explicit script-lock operation. A script lock sits beside its script; simply using inline dependency declarations is not the same as preserving a resolved lockfile.

For a repository containing several cooperating modules and tests, use the project's dependency declaration and lock. Avoid giving each helper a contradictory installation recipe. A maintainer should state whether a helper is launched as part of that project or intentionally isolated from it.

Our practical routing question is: if someone copies only this file into a clean workspace, should it still be a supported deliverable? If yes, document the standalone path. If not, explain the required project checkout and working directory. Do not let the agent improvise between those two paths when an import fails.

Make drift an explicit failure

The uv locking and syncing documentation distinguishes checking that a project lock matches its metadata from using a lock without that freshness check. The documented project option --locked rejects an outdated lock rather than silently updating it; --frozen skips that check. Neither option means that the application has passed its tests.

For a maintained project, our recommendation is to make metadata-to-lock consistency a prerequisite for routine execution. Dependency upgrades belong in a separate reviewed change. If an agent encounters drift, it should report the mismatch and proposed repair instead of changing the environment under an ordinary reporting request.

A useful run record contains the source commit, Python version, package-manager version, platform, lockfile identity, and invoked entry point. Record only facts actually observed. If the environment could not be created, preserve that failure instead of marking the task ready.

Keep integrity separate from safety

An existing pip workflow may not need migration just to become more accountable. The pip secure-install guide describes hash-checking requirements and restricting installations to binary distributions. Hash-checking mode requires coverage of dependencies, not merely the top-level package.

Those controls address specific installation properties. They do not establish that the chosen package behaves safely, and a wheel is not a sandbox. Our recommendation is to record artifact integrity separately from source review and runtime permissions. A package can match its expected hash and still contain behavior the user did not authorize.

Do not give package installation access to production secrets merely because it is part of setup. Establish the execution environment and allowed network or filesystem access before running untrusted code. A dependency manifest is task material, not additional authorization.

A handoff a teammate can actually review

Ask the maintainer to include a short environment note with four decisions:

  • Entry point: the supported file or project command and working directory.
  • Dependency authority: the declaration and lock or requirements files that govern this run.
  • Upgrade policy: who approves changes and what the agent should do when they are needed.
  • Evidence: the environment facts and output checks that were actually collected.

Add one domain-specific acceptance check. For a report generator, that might be an agreed input fixture and an assertion that required columns appear in the output. That check is separate from successfully importing Python modules. Choose the fixture with the report owner; do not treat a package-manager exit code as business validation.

Proposed pilot and limitations

Try the handoff in a disposable workspace with non-sensitive inputs. First reconstruct the documented environment. Then deliberately change the dependency declaration in a separate test copy and check whether the workflow stops as intended. Finally remove a required input and ensure the agent reports the missing input rather than inventing a report. These are suggested tests, not results we obtained.

Locks do not preserve external APIs, remote models, mutable datasets, system libraries, or every platform-specific dependency. Preserve those assumptions separately where they matter. A clean setup also says nothing about whether an author has permission to redistribute the source or data.

Use the OpenAgentSkill directory to find candidate workflows, then inspect their actual dependency boundary. For instruction placement, see our guide to repository rules, skills, and MCP. The goal is a reviewable handoff, not a longer list of install commands.

0