Npm Git Install

Git-Based Node Package Install

Use this skill when the main question is "what install packet should we trust, what delivery path fits this dependency, and what should we do next?"

The job is not to dump every syntax variant or treat raw Git installs as normal infrastructure. The job is to: 1. normalize the package-delivery packet already in hand, 2. choose one primary delivery mode, 3. make durability, auth, and build consequences explicit, 4. tailor commands to the package manager actually in use, 5. leave a clear exit path when a temporary Git bridge is starting to become permanent.

Read references/intake-packets-and-route-outs.md before handling an unfamiliar delivery packet. Read references/delivery-decision-matrix.md when deciding between Git, tarball, workspace, or publish-first. Read references/package-manager-behavior.md for manager-specific caveats. Read references/private-auth-and-ci.md when CI or private auth is already part of the packet.

When to use this skill

• The user wants to install a Node package from GitHub or another Git host
• The package is unpublished, forked, branch-pinned, tag-pinned, commit-pinned, or private
• The package lives in a monorepo and the user is unsure whether Git install, workspace linking, tarball, or publish-first is the honest answer
• The user asks about git+ssh, git+https, github:owner/repo, tarball installs, npm pack, or file: / workspace links
• A shared dependency is still being treated like a temporary Git shortcut and someone needs to decide whether that shortcut should continue

When not to use this skill

• The main task is fixing local Git branch/history problems → use git-workflow
• The main task is creating or operating GitHub repos, packages, or releases at the admin level → use github-repo-management
• The main task is monorepo/task-runner automation rather than package-delivery choice → use workflow-automation
• The main task is broader runtime, machine, container, or service setup → use system-environment-setup
• The user already has a normal registry dependency and only needs an ordinary version bump

Instructions

Step 1: Start from the delivery packet already in hand

Use references/intake-packets-and-route-outs.md.

Normalize the request into one of these packet shapes:

• temporary-bridge-packet — unpublished fix, fork, PR branch, or short-lived bridge to unblock work now
• shared-bridge-packet — teammates or CI need the bridge too, so branch drift and lockfile stability matter
• private-auth-packet — the install path is private and the real risk is credential parity across local and CI
• artifact-fallback-packet — raw Git source installs are too brittle, but a full registry workflow is still too heavy
• workspace-inner-loop-packet — both the app and package are being developed together locally or inside a monorepo
• durable-distribution-packet — the dependency is no longer a one-off bridge and should probably stop behaving like one

Capture the minimum useful frame:

Packet: shared-bridge-packet
Package manager: pnpm
Package state: unpublished fork fix
Audience: CI + teammates
Current ref: feature branch
Main risk: branch drift and auth parity

Rule: start from the packet the user already has. Do not force them through a perfect release-management template before answering.

Step 2: Choose one primary delivery mode

Pick exactly one primary mode:

• direct-git-bridge — local-only or clearly temporary bridge from Git
• sha-pinned-shared-bridge — Git is still the bridge, but shared reproducibility matters
• private-git-auth-path — the short-term answer is still private Git, and the key constraint is auth parity
• tarball-or-pack-artifact — package the dependency without relying on raw Git source install behavior
• workspace-or-file-link — keep co-development local or monorepo-scoped
• publish-first-registry-path — move to a durable distribution channel

Optional: mention one fallback mode, but do not flatten every request into a six-option menu.

Step 3: Classify durability

Use a small durability model:

• Tier 0 — local-only
• Tier 1 — team / CI bridge
• Tier 2 — durable shared package
• Tier 3 — production / release infrastructure

Capture only what changes the decision:

• who consumes it
• whether the ref is floating or fixed
• whether raw source install behavior is acceptable
• whether local and CI already share one auth story
• what the exit path should be if the dependency stays around

If the packet spans multiple tiers, plan for the highest one.

Step 4: Pick the safest mode from the ladder

Use references/delivery-decision-matrix.md.

Default order: 1. publish-first-registry-path 2. workspace-or-file-link 3. sha-pinned-shared-bridge 4. tarball-or-pack-artifact 5. direct-git-bridge

Rules:

• prefer SHA pins over floating branches for shared use
• prefer artifact or publish-first when raw Git build/prepare behavior is the risk
• prefer workspace / file when both sides move together locally
• treat private auth as a constraint, not proof that Git is the right long-term channel

Step 5: Tailor commands to the manager in use

Give the narrowest correct syntax only.

Common patterns:

• SHA-pinned bridge: npm install github:owner/repo#<commit> / pnpm add github:owner/repo#<commit> / yarn add owner/repo#<commit> / bun add github:owner/repo#<commit>
• Git URL forms: git+https://github.com/owner/repo.git#<commit> or git+ssh://git@github.com/owner/repo.git#<commit>
• Tarball: npm install https://.../package.tgz (or equivalent for pnpm / Yarn / Bun)
• Local path: "dep": "file:../relative-path" or the normal workspace flow

If publish-first is the right answer, give the handoff plan before dumping temporary Git syntax.

Step 6: Make auth, build, and reproducibility visible

Every answer must cover:

• chosen ref / artifact / published version strategy
• whether install pulls raw source + lifecycle/build behavior
• local + CI auth story
• deterministic install expectation (npm ci, frozen lockfile equivalents, pinned ref)
• replacement path once the dependency stops being temporary

Defaults:

• floating branches are convenience shortcuts, not shared infrastructure
• private Git is only as good as the worst environment's auth setup
• tarballs trade Git surprises for artifact ownership
• publish-first is usually the honest answer once the package becomes routine shared infrastructure

Step 7: Route the next owner immediately

This skill owns package-delivery choice, not every downstream task.

Typical route-outs:

• git-workflow — fix or shape the underlying branch/history state
• github-repo-management — operate repos, packages, releases, or package-host settings
• workflow-automation — wire repeatable repo scripts or monorepo automation around the chosen package flow
• system-environment-setup — handle machine/runtime/container/service setup once the dependency question is no longer the main blocker

If the user asks “how should we consume this package?” stay here. If they ask “how do we administer hosting or fix auth at the platform level?” route out.

Step 8: Produce one concise install brief

Return a short operator-style brief with:

• packet
• primary mode
• durability tier
• 1-3 recommended steps
• only the needed commands
• auth / build / reproducibility notes
• exit strategy
• next owner if the work leaves this skill

If the honest answer is “publish this or package it properly,” say that directly.

Output format

Always return a Git package install brief, artifact recommendation brief, or publish-first handoff brief.

Required qualities:

• identify the packet already in hand
• choose one primary delivery mode
• classify durability explicitly
• make auth/build/reproducibility consequences visible
• tailor commands to the package manager actually in use
• leave a clear exit strategy
• route package hosting, repo admin, workflow glue, or environment setup to the right neighboring skill

Examples

Example 1: unpublished fix shared in CI

Input

We need an unpublished fix from a GitHub repo for our npm app. Should we install from the branch or do something safer for CI?

Good output direction

• shared-bridge-packet
• sha-pinned-shared-bridge
• rejects floating branch use for shared CI
• gives one npm-specific command plus an exit path

Example 2: private package auth trouble

Input

Our package is in a private GitHub repo and pnpm install keeps failing in CI. What path should we take?

Good output direction

• private-auth-packet
• chooses private-git-auth-path or publish-first-registry-path
• clarifies CI credential parity and avoids committed secrets

Example 3: monorepo or durable shared package

Input

The package lives in a monorepo. I use Yarn locally but the rest of the team just needs the package in normal projects. Should we install straight from GitHub?

Good output direction

• workspace-inner-loop-packet or durable-distribution-packet
• prefers workspace / file: for local co-development or publish-first for durable use
• does not oversell raw Git install

Best practices

1. Start from the delivery packet already in hand, not from a favorite syntax form. 2. Treat Git refs as a bridge, not a default release channel. 3. Prefer SHA pins over floating branches whenever a Git dependency will be shared. 4. Surface lifecycle/build behavior early; raw Git installs can behave like source packaging, not registry downloads. 5. Keep local, team/CI, and durable shared usage clearly separated. 6. Treat private-auth pain as a signal to re-evaluate the delivery path, not just patch credentials forever. 7. Recommend a durable exit path once the dependency stops being temporary. 8. Update compact and discovery surfaces when the front-door wording changes materially.

References

• Intake packets and route-outs
• Delivery decision matrix
• Package-manager behavior
• Private auth and CI notes
• ../git-workflow/SKILL.md
• ../github-repo-management/SKILL.md
• ../workflow-automation/SKILL.md
• ../system-environment-setup/SKILL.md
• npm package spec: https://docs.npmjs.com/cli/v11/using-npm/package-spec
• npm package.json Git docs: https://docs.npmjs.com/cli/v11/configuring-npm/package-json
• npm pack: https://docs.npmjs.com/cli/v11/commands/npm-pack
• pnpm add: https://pnpm.io/cli/add
• pnpm workspaces: https://pnpm.io/workspaces
• Yarn Git protocol: https://yarnpkg.com/protocol/git
• Yarn workspaces: https://yarnpkg.com/features/workspaces
• Bun add: https://bun.sh/docs/pm/cli/add
• GitHub Packages: https://docs.github.com/en/packages/learn-github-packages/introduction-to-github-packages

Delivery Decision Matrix

Use this matrix before giving commands.

Default recommendation order

1. Publish-first / private registry for durable shared usage 2. Workspace / file: for active local co-development 3. SHA-pinned Git install for short-lived bridges 4. Tarball / npm pack when packaged artifacts are needed without full registry setup 5. Floating-branch Git install only as an explicitly temporary convenience

Intake Packets and Route-outs

Start from the package-delivery packet the user already has. Do not force every request through a giant syntax tour.

temporary-bridge-packet

Use when the request is about an unpublished fix, fork, PR branch, or short-lived unblocker.

Capture:

• package manager
• repo/ref currently being considered
• whether the bridge is local-only or already shared
• how long the bridge is expected to live

Good outcomes:

• one direct Git bridge recommendation
• one warning if the user is about to use a floating branch for shared work
• one exit strategy note

Route out when:

• the real work is fixing the underlying branch/history state → git-workflow
• the real work is publishing or administering the package host → github-repo-management

shared-bridge-packet

Use when teammates or CI need the same bridge and reproducibility now matters.

Capture:

• current ref type: branch, tag, SHA
• whether lockfiles and deterministic install commands are already part of the workflow
• whether multiple repos or deploy environments depend on the same bridge

Look for:

• SHA pin over floating branch
• one clear package-manager-specific command
• one honest recommendation for when to stop bridging and publish/package properly

Route out when:

• the next job is wiring scripts or repeatable repo automation around the chosen flow → workflow-automation

private-auth-packet

Use when the install path is private and auth parity is the real blocker.

Capture:

• SSH vs HTTPS token vs registry token path
• whether local and CI use the same auth story
• whether the bridge is still temporary or has become routine infrastructure

Good outcomes:

• one chosen auth path
• one explicit CI parity note
• one warning against committing secrets into manifests or docs

Route out when:

• package hosting/repo admin is now the real work → github-repo-management
• machine/runtime provisioning is the blocker rather than package choice → system-environment-setup

artifact-fallback-packet

Use when raw Git installs are too brittle but a full registry workflow is not justified yet.

Capture:

• whether install-time build/prepare behavior is unsafe or surprising
• who owns artifact refresh/versioning
• whether a tarball URL or npm pack flow is acceptable

Look for:

• tarball / npm pack recommendation
• explicit artifact ownership
• clear explanation of why raw Git is the wrong fit here

Route out when:

• release/package publication is now the better long-term answer → github-repo-management

workspace-inner-loop-packet

Use when both the app and package are being developed together locally or within one monorepo-style workflow.

Capture:

• whether the package is only needed on one machine/repo right now
• whether workspace-aware tooling already exists
• whether the user is accidentally solving a local co-dev problem with a remote Git dependency

Good outcomes:

• workspace / file: recommendation
• explicit note that this is not a remote distribution strategy
• route away from raw Git when the package root / monorepo layout makes that misleading

Route out when:

• the main job is monorepo automation or task-runner wiring → workflow-automation

durable-distribution-packet

Use when the package is no longer a one-off bridge and multiple repos, teammates, CI, or production depend on it routinely.

Capture:

• number of consuming repos/environments
• onboarding/release friction
• whether branch/SHA installs are now acting like permanent infrastructure

Good outcomes:

• publish-first / private registry recommendation
• artifact fallback only when registry overhead is still genuinely too high
• clear statement that floating Git refs are not durable shared infrastructure

Route out when:

• the next job is package-host administration, release setup, or registry configuration → github-repo-management

Quick route-out table

Rule of thumb

A good delivery packet is the smallest artifact set that lets you choose one honest install path. If the packet still cannot support that choice, ask for one missing artifact or route to the neighboring skill that owns the next step.

Package-Manager Behavior Notes

Shared reality

All major managers can install from Git, but Git dependencies are not always equivalent to registry tarballs.

Common consequences:

• install may involve cloning the repo
• lifecycle/build steps can run
• auth and Git host access become part of dependency installation
• monorepo/subdir support is uneven

npm

• Strong baseline syntax support for GitHub shorthands and Git URLs
• Important caveat: Git dependencies may trigger packing/build-related lifecycle behavior
• Good fit when the repo already uses npm and the need is straightforward

pnpm

• Similar Git-install ergonomics to npm for many cases
• Strong workspace story for pnpm-managed repos, but still decide whether remote Git is the right tool before defaulting to it

Yarn

• Git protocol is a first-class concept
• Especially relevant when the upstream repo is Yarn-oriented or the package lives in a workspace/monorepo setup
• Better place to mention repo/workspace-specific Git behavior than pretending npm-style rules cover everything

Bun

• Bun can install from Git and tarballs with concise syntax
• Still apply the same decision rules: direct Git is a bridge, not automatically the best long-term package channel

Operator rule

When the package manager is known, give only the commands for that manager unless a contrast is necessary.

Private Auth and CI Notes

Prefer explicit auth choice

Choose one path and say it clearly:

• SSH-based Git auth when developer machines and CI already have key/discoverability support
• HTTPS token auth when the environment is standardized around tokens/secrets managers
• Registry token auth when the package is durable enough that a private registry is the cleaner answer

Rules

• Do not recommend embedding secrets directly into committed manifests, example code, or docs.
• If the dependency must work on teammate machines and CI, call out that credential parity is part of the task.
• If auth friction is already dominating the problem, recommend a private registry or artifact-based distribution instead of doubling down on raw Git URLs.

CI checklist

• Git host access is available on the runner
• the chosen auth method is injected through the platform's secret mechanism
• host key / SSH known-host setup is handled if SSH is used
• the runner has any toolchain needed by install-time build/prepare steps
• the dependency ref is pinned strongly enough for incident/debug reproduction

Exit heuristic

If the package is shared, private, and expected to persist, registry-based auth usually ages better than repeated Git credential setup.