I built supply-chain-safety-skill after running into a pattern that felt too easy to miss: an AI coding agent can move very quickly through dependency work, but dependency work is exactly where speed can become a liability.
Adding a package, running a one-off CLI, upgrading a build plugin, or asking a generator to rewrite part of a project all look like normal development tasks. In practice, they are supply-chain decisions. They can execute remote code, change lockfiles, download binaries, touch credentials, or send dependency information to third-party services.
The point of this project is simple: make the agent stop at the right moments.
Not after something strange happens. Not after a lockfile changes in a way nobody read. Not after npx has already run code from a package that looked plausible. Before that.
The Problem Is Not Lack of Scanners
There are already good places to look for package risk: OSV, Socket, Snyk, GitHub Advisories, npm and PyPI metadata, ecosystem advisory databases, and project-specific security tooling.
I did not want to build another scanner and pretend it was authoritative. A local scanner can be useful as machine evidence. It can inspect lockfiles, cache traces, package-manager stores, and obvious indicators of compromise. But it cannot replace public vulnerability databases, package behavior analysis, maintainer history, release metadata, or human judgment.
The more interesting problem was workflow.
When an agent is working inside a real repository, the risky moment is not always presented as “please do a security review.” It is usually phrased as ordinary engineering work:
- “Add this package.”
- “Upgrade the UI library.”
- “Run the migration tool.”
- “Use the official CLI.”
- “Try this command from the README.”
- “Install the code generator and update the types.”
Those are exactly the moments where an agent needs a policy it cannot casually skip.
Why a Skill
I wanted the behavior to travel with the agent, not with one specific repository.
The project has two pieces:
- a reusable
supply-chain-safetyskill that describes the dependency-intake workflow; - a global guardrail block for
AGENTS.mdorCLAUDE.mdthat tells the agent when the skill must be used.
That split matters.
The guardrail is short and hard to miss. It says that dependency changes, package execution, build plugins, code generators, native modules, lockfile changes, and similar tasks must trigger the skill. It also bans the most dangerous shortcuts unless the user explicitly approves them: unknown npx, pnpm dlx, npm exec, curl | sh, installer scripts, and similar remote-code execution paths.
The skill holds the longer workflow. It asks the agent to classify the dependency, inspect metadata before installing or executing it, prefer trusted public sources, respect repo-pinned tooling, keep lockfiles with dependency changes, and report residual risk clearly at the end.
This makes the rule usable. The global instruction catches the category of work. The skill gives the agent enough structure to act well once the category is detected.
The Boundary I Care About
The most important boundary in this project is execution.
Reading package metadata is different from running the package. Inspecting a tarball is different from executing its CLI. Looking up an advisory is different from sending a private lockfile or dependency graph to a third-party service.
Agents are useful because they can act. Supply-chain safety starts by slowing down the actions that have a wider blast radius.
The skill asks for approval before:
- executing unknown package commands such as
npx,pnpm dlx,npm exec,yarn dlx,bunx,pipx, or installer scripts; - sending private package names, lockfiles, manifests, source code, or dependency graphs to external services;
- adding packages with install scripts, native binaries, code generation, CI/CD access, credential access, cloud access, or very recent releases;
- treating a local scanner result as if it were a complete vulnerability database.
These are not dramatic rules. They are the boring rules I want in place before the dramatic incident.
A typical unsafe path is simple: the agent sees a README command, runs pnpm dlx ..., and only then inspects what changed. The safer path is slower at the boundary: inspect the package, explain what it can do, check the risk signals, and ask before executing remote package code.
What the Skill Actually Teaches
The skill is intentionally procedural.
Before a dependency change, it asks the agent to explain why the dependency is needed and whether existing code, the standard library, or an already installed package can solve the problem. That catches a surprising amount of unnecessary dependency intake.
Then it classifies the risk:
- runtime library or development-only helper;
- build plugin, code generator, release tool, test tool, or one-off CLI;
- install-time scripts, native code, binary downloads, or remote scripts;
- filesystem, environment, token, registry, Git, SSH, browser, cloud, or CI/CD access.
After that, it points the agent toward better evidence: OSV, Socket, Snyk where appropriate, GitHub Advisories, npm or PyPI metadata, and ecosystem advisory sources. It does not treat local tools as useless. It just keeps their role honest: local machine evidence, not an authoritative vulnerability database.
Finally, it makes the final response harder to hand-wave. If the agent changes dependencies, it should report what changed, why it was needed, whether the lockfile changed, what metadata and third-party checks were used, what local checks were run, and what residual risk remains.
That final report is not ceremony. It gives the human reviewer a compact audit trail.
How It Ships
The repository includes an installer script because a skill is only useful if it can be installed consistently. It supports Codex, Claude, or both, and writes the global guardrail as a managed block:
<!-- supply-chain-safety-skill:start -->
<!-- supply-chain-safety-skill:end -->That means the installer can be run again without overwriting unrelated personal instructions. It replaces only the block it owns.
There is also a --no-guardrail option for people who want to install the skill but wire their own global instructions manually. The important part is that the installation is repeatable without taking ownership of the user’s whole agent configuration.
What I Deliberately Did Not Build
I did not build a magic “is this package safe?” button.
That would be the wrong promise. Supply-chain risk is contextual. A package with no known CVEs can still be a poor choice. A package with a binary installer may be acceptable in one environment and unacceptable in another. A third-party check can miss a new compromise. A local scanner can confirm useful facts without seeing the whole ecosystem picture.
The skill is meant to improve the decision process, not replace it.
It also does not try to force one package manager, one scanner, or one advisory source. Real repositories already have pinned tooling and local constraints. The right behavior is to respect the repo first, then add supply-chain checks around the actual change being made.
Where This Fits in My Workflow
This project came from using agents in real repositories, not from designing a generic policy document in isolation.
The behavior I want is very practical:
- if the task is normal code editing, keep moving;
- if the task adds or upgrades dependencies, slow down;
- if the task runs remote package code, ask first;
- if a third-party service would receive private dependency data, ask first;
- if a lockfile changes, make that visible;
- if the final answer says the dependency is safe, show what evidence supports that statement.
That is the shape of agent safety I care about most: not a large abstract framework, but small operational rules that fire at the moment they matter.
The Project as a Public Artifact
I like this project because it is small and opinionated.
It does not try to solve the whole supply-chain security problem. It solves a narrower problem: giving coding agents a better default posture around dependency work.
That makes it easy to install, easy to review, and easy to adapt. The repo is mostly text: the skill, the checklist, the guardrail template, and a small installer. There is not much machinery. That is intentional.
For me, this is also the kind of project worth writing about on this site. It sits close to real development work, it captures a boundary I kept running into, and it turns a repeated judgment into a reusable tool.
The project is available on GitHub: supply-chain-safety-skill.
The next time an agent reaches for npx, I want it to pause for the right reason.