Should GitHub CLI gh skill Be Installed at Project or User Level? 2026 Security Comparison

Choose project-level installation when a team needs to review and reproduce a skill with its repository. Choose user-level installation only when personal reuse across repositories is worth the broader scope. This guide compares both choices and shows how to inspect skill files, establish an update policy, and verify the installation.

Decision: Choose project-level installation for skills that a team must review, reproduce, and maintain with a repository. Choose user-level installation only for skills intended for personal reuse across repositories. In either case, preview the files and verify the source, version, and update path before installation.

This guide is for: Developers adding GitHub CLI gh skill to a repository; platform engineers standardizing skills across team workflows; and security or toolchain owners deciding where skills may apply.

Last updated: October 8. Checked against the GitHub documentation for adding agent skills and the GitHub CLI skill command manuals. The preview status and supported CLI options can change, so confirm the current documentation and local CLI help before applying the steps below.

How should you decide between personal reuse and team control?

The installation scope determines where a skill is placed and who is expected to manage it. It does not establish that the skill is safe, nor does it guarantee that every agent host will behave the same way. GitHub documents options for selecting an agent host and an installation scope, and warns that skills are not verified by GitHub. Treat scope as an operational boundary, not a security certification.

For Agent Skills project-level installation, the repository is the natural place when collaborators need to inspect the same files, discuss changes in code review, and follow a shared update process. This approach makes the skill easier to associate with a project’s change history. It also gives maintainers a clear place to document why the skill is present and who is responsible for reviewing it.

For Agent Skills user-level installation, the individual developer manages the skill for personal use across repositories. That can avoid repeating an installation in each project. The trade-off is that the skill may be available in a wider set of working contexts. Convenience does not make this scope safer: a mistake in the skill, or a change to its source, may affect more than one project.

A team shared skill belongs with the repository when its contents and updates need team review. A personal convenience skill belongs in the user scope only after you accept its broader reach.

There are practical differences that are easy to miss:

• Review ownership: A project-level skill can be reviewed alongside other repository changes. A user-level skill may change without a corresponding project review, so the developer must track it separately.
• Reproduction: A repository gives teammates a shared reference point, but a file’s presence alone does not prove that every member has installed it correctly or that their agent recognizes it.
• Scope of impact: A user-level installation can reduce repeated setup while broadening where the skill may be used. A project-level installation is narrower in intent, but still needs content review and execution safeguards.
• Maintenance: Shared copies can drift if contributors install from different sources or update at different times. Personal copies can drift when the owner does not record the source revision or check for changes.
• Permissions and execution: A skill file can influence agent behavior, and accompanying scripts may have their own effects. Neither installation scope should be treated as a substitute for limiting the agent’s access to files, credentials, and commands.

The official installation manual for gh skill describes the installation options. Verify the exact flags against the version of the CLI in use instead of assuming that a setting or default from an older guide still applies.

Which scope fits each working scenario?

The following comparison is a decision aid, not a security certification or a compatibility test. The fit labels summarize how well each scope supports the stated workflow. They do not measure the skill itself.

Personal use across multiple repositories

User-level installation can be reasonable when one developer deliberately uses the same reviewed skill in unrelated projects. Before choosing it, ask whether the skill needs access to every repository where the selected agent may operate. If the answer is uncertain, use a narrower project-level setup first and test it in a low-risk repository.

How can you inspect skill files and scripts before installing? Start with GitHub CLI’s skill preview reference, then inspect the skill’s SKILL.md, its directory tree, and any included scripts. Review the source location and the actual content rather than relying on a short description or a familiar repository name. The Agent Skills file-structure specification can help you understand the expected structure; it is not evidence that a particular skill is trustworthy.

Look for instructions that ask the agent to disclose secrets, ignore higher-priority instructions, run opaque commands, or fetch and execute code without review. Check scripts separately: read what they access, what they modify, and whether they contact external services. If the purpose or effect of a file is unclear, do not install it into a broader user scope just to see what happens.

Team use in a single repository

Project-level installation is usually the more manageable choice when a team needs a shared skill for a repository’s workflow. The repository can carry the skill and the review record together. That helps a new contributor find the intended version and gives maintainers a place to discuss updates.

This does not mean a project-level installation automatically synchronizes agent configuration across the team. Confirm separately that each intended user’s agent host recognizes the skill and that the installation procedure is documented. GitHub’s documentation explains the supported host and scope choices, but do not infer an organization-wide policy or automatic team rollout from those options.

For a shared skill, record at least:

• Where the skill came from, including its source repository or other source identifier.
• Which version or revision was reviewed.
• Who owns future reviews and what change should trigger one.
• Which agent host and installation scope the team intends to use.
• Whether the skill includes scripts, and what access those scripts require.

These are review records, not claims that the CLI enforces a team policy. A repository can make the decision visible; maintainers still need to establish and follow the review process.

Sensitive repositories and governed environments

For a repository that handles sensitive code, credentials, or automated changes, treat the skill as untrusted input until reviewed. GitHub explicitly warns that skills may contain prompt injection, hidden instructions, or malicious scripts, and advises previewing them before installation. The official guide to adding agent skills is the source for that warning. It does not guarantee safety after preview, and installation scope alone cannot prevent a harmful instruction from influencing an agent.

A governed project should separate three decisions:

• Source approval: Is this source acceptable for the project, and can reviewers inspect its contents?
• Version choice: Which revision was reviewed, and can the team identify it later?
• Update responsibility: Who checks for changes and decides whether a new revision is acceptable?

Where the current CLI documentation supports selecting or pinning a version, use the documented mechanism and record the chosen revision. Do not assume a default branch is equivalent to a fixed version. When the documentation or CLI does not make the selected revision clear, preserve the source details in the review record and confirm what was installed before relying on it.

For ongoing maintenance, the skill update manual describes the update command, while the skill list manual documents how to inspect installed skills. Use those references to establish a repeatable process. An update should be reviewed as a content change, not treated as a harmless refresh: re-check the skill instructions, scripts, source, and version information before allowing the revised skill into a sensitive workflow.

Previewing a skill reduces uncertainty about what you are installing; it does not prove the skill is benign. If a file is unclear, unexpected, or unnecessary for the task, stop and ask its owner for an explanation before installation.

How can you test a skill without widening its reach?

Use a low-risk repository and confirm each stage before adopting the skill in a shared or sensitive workflow. These steps avoid treating a successful installation as an approval decision.

Step one: Confirm the CLI’s current options. Check the installed CLI’s help and the current installation command documentation. Confirm the available scope and agent-host options for that version. Do not copy flags from an old tutorial without verifying them.

Step two: Preview the source. Use the documented preview workflow, then inspect SKILL.md, the full file tree, and any scripts. Compare the visible contents with the purpose stated by the source owner. If files are omitted from the preview or the source cannot be identified, defer installation until you can inspect them.

Step three: Record the review target. Note the source and the version or revision you intend to test, when that information is available. For a team workflow, put this information where maintainers can review it. For personal use, keep a record that can be checked before future updates.

Step four: Install at the narrowest useful scope. If the test concerns one repository, start with project scope. Choose user scope only if cross-repository personal reuse is part of the requirement. Follow the current CLI syntax; do not infer flags from this guide.

Step five: Check the result. Use the documented listing command to confirm what is installed and where it is installed. Then ask the intended agent host to recognize or use the skill in a harmless task. A listed skill confirms an installation state; it does not establish that the host handles every instruction as expected.

Step six: Test team reproduction. Have another authorized team member follow the documented procedure in a suitable test environment. Confirm that they can identify the same source and intended revision, that the repository gives them enough information to reproduce the setup, and that their agent recognizes the skill. If the process relies on undocumented personal state, it is not yet a reproducible team setup.

Step seven: Define update and rollback ownership. Assign someone to review source changes and check updates using the current CLI documentation. If a preview reveals unexpected files, the installed location is wrong, or the team cannot establish what revision was tested, remove the skill using the current documented procedure and return to the narrower scope while investigating.

How should you pin a version or check for updates? Use version-selection options only when the current installation documentation explicitly supports them, and record the revision the team reviewed. Use the documented update command to check or apply changes, then review the changed content before adoption. Do not assume that automatic availability, an update notification, or a successful update means the new version has passed your security review.

A useful acceptance record is short: source, reviewed revision, selected scope, intended agent host, reviewer, and update owner. Keep it with the project for a shared workflow or in a personal engineering record for individual use. This makes later questions answerable: what was installed, why was it trusted for this task, and who should inspect the next change?

When should you keep the scope narrow?

Choose project-level installation when the skill affects one repository, the team needs a shared review trail, or maintainers must reproduce its use. Choose user-level installation when the skill is intentionally personal, useful across projects, and acceptable in every context where it may become available.

Avoid user-level installation when the skill is not understood, its source is unclear, or its instructions could expose sensitive repositories to unnecessary access. Avoid treating project-level placement as a complete containment mechanism: the agent’s actual access still depends on its environment and permissions.

The trade-off is not simply setup effort. A user-level skill reduces repeated setup but can widen the places where it is available. A project-level skill makes review and handoff more visible but requires maintainers to own version decisions and keep the workflow reproducible. In both cases, preview, scope selection, access control, and update review solve different parts of the problem.

Teams planning where code and agent configuration should live can also review our guide to Mac VPS environments for remote development and our Mac support and operating guidance. Those resources can help when the skill’s installation boundary needs to be considered alongside the working environment and its access boundaries.

If the current setup relies on developers maintaining separate local configurations, it can create version drift, inconsistent review records, and uncertainty about which environment has access to the project. A managed Mac environment is not automatically the right answer: teams with stable, sustained workloads or a requirement for physical interfaces may be better served by dedicated hardware. But when you need a temporary, isolated environment to validate a skill workflow or reproduce a remote development setup, renting a Mac from ZekVPS can be easier to evaluate than expanding personal installations across machines. Review the environment and access requirements first, then compare them with ZekVPS Mac rental options before choosing.