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 `.metadata.json` 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

`.skillshare/` Directory Structure

<project-root>/
├── .skillshare/
│   ├── config.yaml              # Targets + settings (incl. extras)
│   ├── .metadata.json           # Remote skills list (auto-managed)
│   ├── .gitignore               # Ignores logs/, trash/, 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.

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 installations are tracked in a separate file, .skillshare/.metadata.json:

{
  "skills": [
    {
      "name": "pdf-skill",
      "source": "anthropic/skills/pdf"
    },
    {
      "name": "_team-skills",
      "source": "github.com/team/skills",
      "tracked": true
    }
  ]
}

Skills list tracks 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.

Portable Skill Manifest

config.yaml and .metadata.json together form a portable skill manifest in both global and project mode. In a project, commit them to git and anyone can run skillshare install -p && skillshare sync. For global mode, copy both files to a new machine and run skillshare install && skillshare sync. This works for teams, open source contributors, community templates, and dotfiles across machines.

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/` and `trash/` 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​

Config Format​

Mode Restrictions​

When to Use: Project vs Organization​

See Also​