Graphify Project-Scoped Installation vs User-Wide Installation: A Complete Guide

Graphify supports two installation modes—user-wide (default) stores skills in ~/.claude/skills/ for global access, while project-scoped installation writes to .claude/skills/ inside your repository for version-controlled, team-shared AI coding assistant configurations.

The safishamsi/graphify tool streamlines AI-assisted development by installing "skills"—structured Markdown files that teach coding assistants like Claude or Codex how to work with your codebase. Understanding the difference between Graphify project-scoped installation vs user-wide install is critical for choosing the right strategy for solo development versus team collaboration.

Understanding Graphify's Installation Scopes

User-Wide Installation (Default)

By default, Graphify installs skills to your home directory, making them available across all repositories you work on. When you run graphify install, the CLI calls graphify.__main__._copy_skill_file() with project=False, copying the bundled skill Markdown to ~/.claude/skills/graphify/SKILL.md (or equivalent platform-specific paths). The installer then updates the global instruction file (e.g., ~/.claude/CLAUDE.md) so the assistant always loads the skill regardless of which directory you open.

This approach keeps your repositories clean but requires manual reinstallation when switching machines or user accounts.

Project-Scoped Installation

When you append the --project flag, Graphify performs a project-scoped installation instead. According to the source code in graphify/__main__.py (lines 28-33), the CLI parses the --project flag and sets project_scope=True, triggering different behavior:

• The skill file is written relative to the repository root (e.g., .claude/skills/graphify/SKILL.md or .agents/skills/graphify/SKILL.md for Codex/OpenCode)
• The installer registers the skill in the project's local instruction file (e.g., .claude/CLAUDE.md)
• A git add hint prints for the newly created files, prompting you to commit them

This ensures the skill travels with the repository under version control, guaranteeing every contributor uses identical AI assistant configurations.

How the CLI Handles Installation Scopes

The implementation in graphify/__main__.py distinguishes between scopes through explicit flag handling. The argument parsing loop (lines 28-33) detects --project and sets the scope variable:

while i < len(args):
    arg = args[i]
    if arg == "--project":
        project_scope = True
        i += 1
    # ...

The installer then forwards this boolean to the copy function:

skill_dst = _copy_skill_file(platform, project=project, project_dir=project_dir)

For project-scoped installs, the helper function _project_scope_root() (lines 18-25) determines the top-level artifact that should be committed, ensuring the printed git add hint points to the correct path for version control.

Installation Commands and Examples

User-wide installation (single developer, cross-project usage):

# Installs to ~/.claude/skills/graphify/SKILL.md

graphify install

Project-scoped installation (team workflows, version-controlled):

# Installs to .claude/skills/graphify/SKILL.md within current repo

graphify install --project

Platform-specific project installs (Codex, OpenCode):

# Creates .agents/skills/graphify/SKILL.md and updates AGENTS.md

graphify codex install --project

The CLI prints specific git-add hints for each mode. For user-wide installs, it suggests adding files from your home directory; for project-scoped installs, it suggests adding the local .claude/ or .agents/ directories to your repository.

Uninstalling Skills

Uninstall mirrors the installation location exactly. Removing a user-wide skill:

graphify uninstall

Removing a project-scoped skill:

graphify uninstall --project

This deletes the files from the corresponding location—either ~/.claude/skills/ or the local repository's .claude/ directory—and cleans up the associated instruction file references.

When to Use Each Installation Mode

Choose user-wide installation when you want the Graphify skill available for any project you open locally. This avoids polluting repositories with AI configuration files and works well for personal development where you maintain consistent toolchain preferences across all your work.

Choose project-scoped installation when working in teams that need reproducible AI assistant behavior. By committing the skill files to .claude/skills/ or .agents/skills/, you ensure every contributor receives the exact same instructions without requiring them to run installation commands. This approach also prevents version conflicts when different repositories require different skill versions.

Summary

• Graphify project-scoped installation vs user-wide install determines whether skills live in your home directory (~/.claude/skills/) or inside the repository (.claude/skills/)
• User-wide installs use graphify install and call _copy_skill_file() with project=False
• Project-scoped installs require the --project flag, triggering project_scope=True in graphify/__main__.py
• Project-scoped installations print git add hints because they are designed for version control
• Uninstall commands mirror their respective install locations with matching flags

Frequently Asked Questions

Where does Graphify store user-wide skills?

User-wide skills are stored in platform-specific home directory locations, typically ~/.claude/skills/graphify/SKILL.md for Claude Desktop or equivalent paths for other platforms. The installer updates the global CLAUDE.md file in your home directory to reference these skills.

Can I use Graphify with multiple AI platforms in the same project?

Yes. Graphify supports platform-specific subdirectories such as .claude/ for Claude Desktop and .agents/ for Codex or OpenCode. You can install project-scoped skills for multiple platforms simultaneously, and each will maintain its own instruction file and skill directory.

How do I switch from user-wide to project-scoped installation?

First run graphify uninstall to remove the user-wide skill, then run graphify install --project from your repository root. The CLI will copy the skill files into the repository and update the local instruction file. Commit the resulting .claude/ or .agents/ directory to complete the migration.

Are project-scoped skills automatically committed to git?

No, Graphify does not automatically commit files. After running graphify install --project, the CLI prints a git add hint showing exactly which files were created (e.g., .claude/skills/graphify/SKILL.md and .claude/CLAUDE.md). You must manually stage and commit these files to share the configuration with your team.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}