Project Skills

Run skillshare at the project level — skills scoped to a single repository, shared via git.

When does this matter?

Use project skills when your team needs repo-specific AI instructions (coding standards, deployment guides, API conventions) that shouldn't be in your personal global skill collection.

Usage Scenarios

Scenario	Example
Monorepo onboarding	New developer clones repo, runs `skillshare install -p && skillshare sync` — instant project context
API conventions	Embed API style guides as skills so every AI assistant follows team conventions
Domain-specific context	Finance app with regulatory rules, healthcare app with compliance guidelines
Project tooling	CI/CD deployment knowledge, testing patterns, migration scripts specific to this repo
Onboarding acceleration	"How does auth work here?" — the AI already knows, from committed project skills
Open source projects	Maintainers commit `.skillshare/` so contributors get project-specific AI context on clone
Community skill curation	A repo's `config.yaml` `skills:` section serves as a curated skill list — anyone can `install -p` to get the same setup

Overview

Auto-Detection

skillshare automatically enters project mode when .skillshare/config.yaml exists in the current directory:

cd my-project/           # Has .skillshare/config.yaml
skillshare sync          # → Project mode (auto-detected)
skillshare status        # → Project mode (auto-detected)

Zero Config

Just cd into any project with .skillshare/ — skillshare detects it automatically. No flags, no environment variables, no configuration needed.

To force a specific mode:

skillshare sync -p       # Force project mode
skillshare sync -g       # Force global mode

Global vs Project

	Global Mode	Project Mode
Source	`~/.config/skillshare/skills/`	`.skillshare/skills/` (project root)
Config	`~/.config/skillshare/config.yaml`	`.skillshare/config.yaml`
Targets	System-wide AI CLI directories	Per-project directories
Sync mode	Merge, copy, or symlink (per-target)	Merge, copy, or symlink (per-target, default merge)
Tracked repos	Supported (`--track`)	Supported (`--track -p`)
Git integration	Optional (`push`/`pull`)	Skills committed directly to project repo
Scope	All projects on machine	Single repository

There is a third option for projects that are yours alone: list the folders under projects in the global config. Each folder gets its own set of skills, agents and MCP servers, nothing is added to the repo, and one sync updates them all. See Many Projects, One Config for when to pick which.

`.skillshare/` Directory Structure

<project-root>/
├── .skillshare/
│   ├── config.yaml              # Targets + settings (incl. extras)
│   ├── skills.lock.json         # Commit each remote skill is pinned to (auto-managed, commit it)
│   ├── skills/.metadata.json     # Runtime metadata (hashes, timestamps — auto-managed, gitignored)
│   ├── .gitignore               # Ignores logs/, trash/, backups/, and cloned remote/tracked skill dirs
│   ├── extras/                  # Extras source directories
│   │   └── rules/               # e.g. extras init rules --target .claude/rules -p
│   │       └── coding.md
│   └── skills/
│       ├── my-local-skill/      # Created manually or via `skillshare new`
│       │   └── SKILL.md
│       ├── remote-skill/        # Installed via `skillshare install -p`
│       │   └── SKILL.md
│       ├── tools/               # Category folder (via --into tools)
│       │   └── pdf/             # Installed via `skillshare install ... --into tools -p`
│       │       └── SKILL.md
│       └── _team-skills/        # Installed via `skillshare install --track -p`
│           ├── .git/            # Git history preserved
│           ├── frontend/ui/
│           └── backend/api/
├── .claude/
│   └── skills/
│       ├── my-local-skill → ../../.skillshare/skills/my-local-skill
│       ├── remote-skill → ../../.skillshare/skills/remote-skill
│       ├── tools__pdf → ../../.skillshare/skills/tools/pdf
│       ├── _team-skills__frontend__ui → ../../.skillshare/skills/_team-skills/frontend/ui
│       └── _team-skills__backend__api → ../../.skillshare/skills/_team-skills/backend/api
└── .cursor/
    └── skills/
        └── (same symlink structure as .claude/skills/)

Symlinks in project mode use relative paths (e.g., ../../.skillshare/skills/...). This makes the project directory portable — rename it, move it, or clone it on another machine and all symlinks continue to work. Global mode uses absolute paths since source and targets are in separate filesystem locations.

Visible Project Directory

Repositories that treat skills as reviewable content rather than tool state can use a visible skillshare/ directory instead of the hidden .skillshare/:

skillshare init -p --visible

<project-root>/
├── skillshare/
│   ├── config.yaml
│   ├── skills/
│   └── agents/
└── src/

Everything else is identical — config.yaml, skills/, agents/, extras/, and the operational trash/, backups/ and logs/ directories all live inside whichever project directory is in use.

Detection checks .skillshare/config.yaml first and skillshare/config.yaml second, so:

Existing projects are unaffected.
If both directories exist, .skillshare/ wins.
To move an existing project, run mv .skillshare skillshare, then skillshare sync -p to repair target symlinks that still point to the old directory. If your sources settings explicitly reference .skillshare/, update those paths in config.yaml before syncing.

init -p without --visible continues to create .skillshare/.

note

The global config directory is also called skillshare (~/.config/skillshare/). Only a skillshare/ directory inside a project root is treated as a project.

Missing config

Project commands initialize a project automatically when there isn't one yet, and a shared skills repo using --config local regenerates its gitignored config.yaml the same way.

They stop short of one case: if the project directory already holds skills or agents but its config.yaml is missing, re-initializing would write an empty config and drop every configured target. Those commands report the problem instead, so you can restore config.yaml from version control or run skillshare init -p deliberately.

Config Format

.skillshare/config.yaml:

targets:
  - claude                    # Known target (uses default path)
  - cursor                         # Known target
  - name: custom-ide               # Custom target with explicit path
    path: ./tools/ide/skills
    mode: symlink                  # Optional: "merge" (default), "copy", or "symlink"
  - name: codex                    # Optional filters (merge mode)
    include: [codex-*]
    exclude: [codex-experimental-*]

Targets support two formats:

Short: Just the target name (e.g., claude). Uses known default path, merge mode.
Long: Object with name, optional path, optional mode (merge, copy, or symlink), and optional include/exclude filters. Supports relative paths (resolved from project root) and ~ expansion.

Remote skill dependencies are declared in config.yaml under skills::

targets:
  - claude
  - cursor

skills:
  - name: pdf
    source: anthropic/skills/pdf
  - name: _team-skills
    source: github.com/team/skills
    tracked: true
  - name: review
    source: github.com/team/skills/code-review
    group: frontend

Skills list declares remote installations only. Local skills don't need entries here.

tracked: true: Installed with --track (git repo with .git/ preserved). When someone runs skillshare install -p, tracked skills are cloned with full git history so skillshare update works correctly.
group: Subdirectory path (corresponds to --into during install).

Runtime metadata (install timestamps, file hashes, commit SHAs) is stored separately in .skillshare/skills/.metadata.json — this file is auto-managed and gitignored.

Portable Skill Manifest

config.yaml is the declarative skill manifest. In a project, commit it to git and anyone can run skillshare install -p && skillshare sync. For global mode, .metadata.json serves as the manifest since global config doesn't need to be shared via git.

Lockfile

config.yaml says what a skill follows, such as a repo's default branch. .skillshare/skills.lock.json records which commit that was when someone last installed or updated it. Commit both, and everyone who runs skillshare install -p gets the same content, even after the upstream repo has moved on.

{
  "version": 1,
  "skills": {
    "pdf": {
      "source": "github.com/anthropics/skills/skills/pdf",
      "commit": "8f14e45fceea167a5a36dedd4bea2543ce848564",
      "tree_hash": "f88c87101780018cfabdd229d5d92abedd6f640e"
    }
  }
}

The file is written for you. You never edit it:

Command	Effect on the lockfile
`skillshare install <source> -p`	Pins the new skill to the commit it was installed from
`skillshare install -p`	Installs every skill at its pinned commit. A skill that is already installed at another commit is moved to the pinned one
`skillshare update <name> -p`	Moves the skill to the latest commit and rewrites its pin, so the change shows up in code review
`skillshare uninstall <name> -p`	Removes the pin

Tracked repos are pinned too. They are reset to the pinned commit but stay on their branch, so skillshare update can still pull. A pin is ignored once the skill's source in config.yaml no longer matches it. Local-path sources have no commit and are not pinned.

A pin only moves when you move the skill, with update or a forced reinstall. If a teammate's pin is newer than your copy, other commands leave the pin alone until skillshare install -p brings your copy up to it. install -p does not move a tracked repo that has uncommitted changes; commit or discard them first.

Skills installed with an earlier skillshare version have no recorded commit. They are pinned the next time they are updated or reinstalled.

The lockfile is different from --branch <sha>: that flag pins a skill permanently, and update reinstalls the same revision. With the lockfile the skill keeps following its branch, and only an explicit update moves it.

Custom Source Directories

By default, project mode reads skills, agents, and extras from .skillshare/skills/, .skillshare/agents/, and .skillshare/extras/. Override these paths with the optional sources map when you want to keep skill content alongside other project documentation:

sources:
  skills: ./docs/skills
  agents: ./docs/agents
  extras: ./docs/extras
targets:
  - claude

Each key is optional — omitting a key falls back to the default .skillshare/<type>/ path. Paths are resolved relative to the project root, and absolute paths (including ~) work too.

Common layouts:

# Co-locate skill content with existing project docs
sources:
  skills: ./docs/skills

# Keep agents in an AI-focused subdirectory
sources:
  agents: ./ai/agents

Constraints:

No alias with target paths. skillshare sync -p rejects configs where a source resolves to the same directory as a target (or one contains the other). This prevents sync --force from wiping the configured source. For example, sources.skills: .claude/skills combined with a claude target is rejected with an overlaps error.
External paths skip gitignore management. When a source resolves outside the project root (an absolute path elsewhere on disk), skillshare does not add entries to the project's .gitignore. Manage ignore rules in the source directory yourself if needed.
Operational dirs stay in the project directory. Trash, backups, and operation logs always live under the active project directory (.skillshare/, or skillshare/ — see below) regardless of sources settings.
init -p always seeds {skills,agents}/ in the project directory. Custom sources take effect only after you edit config.yaml.

Mode Restrictions

Project mode has some intentional limitations:

Feature	Supported?	Notes
Merge sync mode	✓	Default, per-skill symlinks
Copy sync mode	✓	Per-target via `skillshare target <name> --mode copy -p`
Symlink sync mode	✓	Per-target via `skillshare target <name> --mode symlink -p`
`--track` repos	✓	Cloned to `.skillshare/skills/_repo/`, added to `.gitignore` (`logs/`, `trash/`, and `backups/` are also ignored by default)
`--discover`	✓	Detect and add new targets to existing project config
`push` / `pull`	✗	Use git directly on the project repo
`collect`	✓	Collect local skills from project targets to `.skillshare/skills/`
`extras`	✓	Extras sync, init, list, remove, collect — all support `-p`
`backup` / `restore`	✗	Not needed (project targets are reproducible)

When to Use: Project vs Organization

Need	Use
Skills specific to one repo (API style, deployment, domain rules)	Project skills — committed to the repo
Skills shared across all projects (coding standards, security audit)	Organization skills — tracked repos via `--track`
Onboarding a new member to a specific project	Project skills — clone + install + sync
Onboarding a new member to the organization	Organization skills — one install command
Both repo context and org standards	Use both — they coexist independently

Usage Scenarios​

Overview​

Auto-Detection​

Global vs Project​

.skillshare/ Directory Structure​

Visible Project Directory​

Missing config​

Config Format​

Lockfile​

Custom Source Directories​

Mode Restrictions​

When to Use: Project vs Organization​

See Also​