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

> Choose between Graphify user-wide or project-scoped installation for your AI coding assistant. This guide details global access versus version-controlled configurations for teams.

- Repository: [Safi/graphify](https://github.com/safishamsi/graphify)
- Tags: how-to-guide
- Published: 2026-06-15

---

**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`](https://github.com/safishamsi/graphify/blob/main/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`](https://github.com/safishamsi/graphify/blob/main/.claude/skills/graphify/SKILL.md) or [`.agents/skills/graphify/SKILL.md`](https://github.com/safishamsi/graphify/blob/main/.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`](https://github.com/safishamsi/graphify/blob/main/.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`](https://github.com/safishamsi/graphify/blob/main/graphify/__main__.py) distinguishes between scopes through explicit flag handling. The argument parsing loop (lines 28-33) detects `--project` and sets the scope variable:

```python
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:

```python
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):

```bash

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

graphify install

```

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

```bash

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

graphify install --project

```

**Platform-specific project installs** (Codex, OpenCode):

```bash

# 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:

```bash
graphify uninstall

```

Removing a project-scoped skill:

```bash
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`](https://github.com/safishamsi/graphify/blob/main/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`](https://github.com/safishamsi/graphify/blob/main/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`](https://github.com/safishamsi/graphify/blob/main/.claude/skills/graphify/SKILL.md) and [`.claude/CLAUDE.md`](https://github.com/safishamsi/graphify/blob/main/.claude/CLAUDE.md)). You must manually stage and commit these files to share the configuration with your team.