AI Supply Chain Guard

Agent-facing install guide for a portable, tool-agnostic supply-chain defense skill.

If a human gave you this repository URL and said something like "install this skill URL", install the supply-chain-guard/ folder from this repo. Do not run package-manager installs, setup scripts, generators, or one-line installers from this repository. The installable unit is plain Markdown: supply-chain-guard/SKILL.md plus optional reference files under supply-chain-guard/references/.

Repository URL:

https://github.com/ZarK/ai-supply-chain-guard

First Use

After installing, read the installed skill and apply it to the current repository:

Use the supply-chain-guard skill before dependency, package-manager, CI, release, IDE-extension, MCP, or AI-agent-tool work in this repo. First inspect the manifests, lockfiles, workflows, package-manager config, and agent/tooling config. Then report what protections are missing before making changes.

For humans, the shortest instruction to give your agent is:

Install this skill and use it before dependency or CI work: https://github.com/ZarK/ai-supply-chain-guard

Agent Install Contract

You are installing a local agent skill, not a software package.

1. Fetch the repository into a temporary directory.
2. Verify that supply-chain-guard/SKILL.md exists.
3. Copy the full supply-chain-guard/ directory into the user's agent skill location.
4. If the target tool does not have native skills, add a small bridge instruction that points at the installed skill.
5. Verify by reading the installed SKILL.md.
6. Start using the skill before dependency, package-manager, CI, release, IDE-extension, MCP, or AI-agent-tool work.

Do not duplicate the full skill into multiple instruction files. Keep one canonical copy of the skill and use bridges that point to it.

Quick Install For Agents

Use this flow when the user did not name a specific tool.

repo_tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/ZarK/ai-supply-chain-guard.git "$repo_tmp/ai-supply-chain-guard"
test -f "$repo_tmp/ai-supply-chain-guard/supply-chain-guard/SKILL.md"

Preferred project-local install:

mkdir -p .agents/skills
rm -rf .agents/skills/supply-chain-guard
cp -R "$repo_tmp/ai-supply-chain-guard/supply-chain-guard" .agents/skills/supply-chain-guard
test -f .agents/skills/supply-chain-guard/SKILL.md

Portable global install:

skills_dir="${AGENT_SKILLS_DIR:-$HOME/.agents/skills}"
mkdir -p "$skills_dir"
rm -rf "$skills_dir/supply-chain-guard"
cp -R "$repo_tmp/ai-supply-chain-guard/supply-chain-guard" "$skills_dir/supply-chain-guard"
test -f "$skills_dir/supply-chain-guard/SKILL.md"

If your agent has a native skills directory, use that directory instead of .agents/skills, but preserve this layout:

<skills-root>/
`-- supply-chain-guard/
    |-- SKILL.md
    `-- references/

Bridge Instruction

For tools that read repository instructions such as AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, Cursor rules, Windsurf rules, or similar files, add this bridge:

# Supply Chain Guard

Before any install, update, scaffold, package-manager command, CI action/workflow change, IDE/MCP/agent-tool change, release job, or dependency-provided tool execution, read and follow `.agents/skills/supply-chain-guard/SKILL.md`.

For deeper guidance, load only the relevant file from `.agents/skills/supply-chain-guard/references/`.

For a global-only install, adapt the path in the bridge to the global skill location, for example ~/.agents/skills/supply-chain-guard/SKILL.md.

What This Skill Is

AI Supply Chain Guard is an agent skill that makes coding agents and human reviewers defensive around dependencies and developer tooling. It is meant to reduce preventable exposure to package compromise, CI compromise, malicious install scripts, dependency confusion, unsafe generators, poisoned caches, compromised actions, suspicious IDE extensions, risky MCP servers, and AI-agent tool persistence.

The skill tells an agent to:

• prefer no new dependency when existing code is enough
• pin exact versions and preserve lockfiles
• block or review young package releases before adoption
• disable lifecycle scripts by default
• treat package-manager commands and project generators as code execution
• verify signatures, provenance, attestations, repositories, workflows, refs, builders, and artifact digests where supported
• remember that valid provenance proves origin or integrity, not that code is safe
• treat CI actions, reusable workflows, caches, artifacts, release jobs, IDE extensions, MCP servers, and agent tools as dependencies
• isolate risky installs from valuable credentials
• stop for human approval on ambiguous or high-risk supply-chain actions
• guide incident response when malicious code may have executed

When To Invoke It

Use the skill before touching any of these:

• package manifests, dependency files, lockfiles, or package-manager config
• npm, npx, pnpm, yarn, bun, deno, uv, pip, poetry, pipenv, cargo, go, mvn, gradle, dotnet, bundle, composer, pod, package installers, or project generators
• GitHub Actions, reusable workflows, workflow templates, CI caches, artifacts, release jobs, or publish pipelines
• Dockerfiles, container image references, binary downloads, one-line shell installers, or generated toolchains
• VS Code/Open VSX/Cursor/Windsurf/JetBrains extensions, MCP configs, AI-agent tools, or automation permissions
• active advisories, suspicious dependency changes, unexpected scripts, new transitive sources, or suspected credential exposure

Compatibility Pattern

The installable skill follows the common agent skill structure:

supply-chain-guard/
|-- SKILL.md
`-- references/
    |-- attack-patterns.md
    |-- ci-and-repository-hardening.md
    |-- ecosystem-playbooks.md
    |-- incident-response.md
    |-- npm-trusted-publishing.md
    |-- package-manager-configs.md
    |-- threat-model-and-rules.md
    `-- tooling.md

Compatibility choices:

• SKILL.md is the only required entrypoint.
• YAML frontmatter contains name and description.
• Deep detail is in one-level references/ files so agents load only what they need.
• There are no hidden installers, binaries, package manifests, or tool-specific runtime dependencies.
• The root README is for installation and orientation; the skill itself is the supply-chain-guard/ directory.

Versioning And Releases

Released versions are Git tags such as v1.0.0.

The source SKILL.md does not carry an embedded version. This avoids drift between frontmatter and the repository release. To pin an install, use a Git tag or commit SHA instead of a branch name.

Release artifacts package only the installable supply-chain-guard/ directory and include a SHA-256 checksum.

What The Skill Teaches

For the deeper tutorial, read supply-chain-guard/references/threat-model-and-rules.md. It explains why the rules exist, including:

• legitimate package releases that briefly ship malicious versions
• install-time scripts, source builds, generators, and one-shot CLIs as code execution
• package-age gates and cooldown exceptions for urgent security fixes
• provenance, trusted publishing, signatures, and attestations as identity/integrity signals rather than malware verdicts
• GitHub Actions, reusable workflows, cache scopes, artifacts, tags, and release jobs as supply-chain dependencies
• pull_request_target, poisoned caches, mutable action tags, and overbroad OIDC permissions
• npm Trusted Publishing, staged publishing, exact identity matching, safe release diagnostics, and package bootstrap flows
• trust downgrade, exotic sources, Git dependencies, tarballs, and registry confusion
• IDE extensions, MCP servers, AI-agent config, and editor marketplaces as executable supply-chain surfaces
• incident response when a malicious dependency may have exposed workstation, CI, SCM, registry, or cloud credentials

Recommended Companion Controls

This skill changes agent behavior. It should be paired with real controls where the user's environment supports them:

• install-time malware blocking, registry proxying, or package intelligence on developer machines and CI runners
• exact versions, frozen installs, checked-in lockfiles, and lifecycle scripts disabled by default
• native package-age gates such as npm min-release-age, pnpm minimumReleaseAge, Yarn npmMinimalAgeGate, Bun minimumReleaseAge, Deno minimumDependencyAge, uv exclude-newer, and pip --uploaded-prior-to
• dependency review, vulnerability alerts, code scanning, secret scanning with push protection, signed commits, and repository rulesets
• trusted publishing, short-lived OIDC credentials, protected release environments, and artifact/provenance verification
• isolated dev containers, VMs, Codespaces, or short-lived runners for risky dependency work

Use third-party products only when they fit the user's environment, budget, and trust model. This skill is not tied to any vendor.

Example Prompts

See examples/README.md for short prompts covering repository review, dependency review, dependency diffs, CI/release review, incident triage, and a comprehensive full review.

Install In Agentic Coding Tools

Tool behavior changes quickly. Prefer the tool's current documentation when it differs from this table. The safest portable pattern is always the same: install supply-chain-guard/ intact, then add a bridge instruction that points at the installed SKILL.md.

Sources And References

Skill format and repository instructions:

• Agent Skills: Overview and specification
• AGENTS.md: Open format for guiding coding agents

Agent and editor setup references:

• Devin Docs: Skills
• Claude Code Docs: Skills
• Goose Docs: Using skills
• GitHub Docs: Repository custom instructions for Copilot
• Cursor Docs: Rules
• Windsurf Docs: Rules and AGENTS.md
• Gemini CLI Docs: GEMINI.md context files
• Replit Docs: custom templates and skills
• JetBrains Docs: Junie guidelines
• OpenHands Docs: repository skills
• Cline Docs: Cline Rules
• Continue Docs: Rules
• Kilo Code Docs: rules and AGENTS.md migration
• Aider Docs: conventions files
• Qodo Docs: Agent TOML files
• Tabnine Docs: Custom commands
• Sourcegraph Amp Manual: AGENTS.md
• Factory Docs: Skills
• Factory Docs: AGENTS.md
• Mistral Docs: Vibe Agents and Skills
• Google Jules Docs: AGENTS.md support
• Augment Docs: Rules and Guidelines
• Zed Docs: Agent Panel
• Warp Docs: Using Agents

Incident case studies:

• TanStack: npm supply-chain compromise postmortem
• Socket: TanStack npm packages compromised in Mini Shai-Hulud attack
• Aikido: Mini Shai-Hulud is back, TanStack and other packages compromised
• Socket: Active supply-chain attack compromises AntV packages on npm
• Aikido: Mini Shai-Hulud compromises hundreds of AntV packages

Supply-chain security guidance:

• GitHub Well-Architected: Defending against dependency supply chain attacks
• GitHub Docs: About supply chain security
• GitHub Docs: About dependency review
• GitHub Docs: Secure use reference for GitHub Actions
• GitHub Docs: Artifact attestations
• NIST SSDF SP 800-218 v1.1

Package-manager and registry controls:

• npm Docs: Config
• npm Docs: Trusted publishing
• pnpm Docs: Settings
• Yarn Docs: Security
• Bun Docs: bun install
• Deno Docs: approve-scripts
• uv Docs: Settings
• pip Docs: pip install
• PyPI Docs: Trusted Publishers

Optional scanners and hardening tools:

• OSV-Scanner
• OpenSSF Scorecard

Contributing

Keep the installable skill concise and durable. Add ecosystem-specific detail to supply-chain-guard/references/. Add incident-specific package lists to issues or advisories, not to SKILL.md, because compromised package sets change quickly.