Configuration

Configuration file reference for skillshare.

Overview

~/.config/skillshare/
├── config.yaml          ← Configuration file
├── skills/              ← Source directory (your skills)
│   ├── .metadata.json   ← Skill metadata (auto-managed)
│   ├── my-skill/
│   ├── another/
│   └── _team-repo/      ← Tracked repository
├── extras/              ← Extras source root
│   └── rules/           ← Extra resource (e.g., rules)

~/.local/share/skillshare/
└── backups/             ← Automatic backups
    └── 2026-01-20.../

IDE Support (JSON Schema)

Config files include a YAML Language Server directive that enables autocompletion, validation, and hover documentation in supported editors.

New configs created by skillshare init include this automatically:

# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/config.schema.json
source: ~/.config/skillshare/skills
targets:
  claude:
    path: ~/.claude/skills

Adding to an existing config

If your config was created before this feature, add the comment as the first line:

Global config (~/.config/skillshare/config.yaml):

# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/config.schema.json

Project config (.skillshare/config.yaml):

# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/project-config.schema.json

Or simply re-run skillshare init --force (global) or skillshare init -p --force (project) to regenerate the config with the schema comment.

Supported editors

Editor	Extension required
VS Code	YAML by Red Hat
JetBrains IDEs	Built-in YAML support
Neovim	yaml-language-server via LSP

Config File

Location: ~/.config/skillshare/config.yaml

Full Example

# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/config.schema.json
# Source directory (where you edit skills)
source: ~/.config/skillshare/skills

# Default sync mode for new targets
mode: merge

# Default target naming (flat or standard)
# target_naming: flat

# Targets (AI CLI skill directories)
targets:
  claude:
    path: ~/.claude/skills
    # mode: merge (inherits from default)

  codex:
    path: ~/.codex/skills
    mode: symlink  # Override default mode
    include: [codex-*] # merge/copy mode only

  cursor:
    path: ~/.cursor/skills
    mode: copy  # real files for Cursor
    exclude: [experimental-*] # merge/copy mode only

  # Custom target
  myapp:
    path: ~/apps/myapp/skills

# Remote skills — auto-managed by install/uninstall
skills:
  - name: pdf
    source: anthropics/skills/skills/pdf
  - name: _team-skills
    source: github.com/team/skills
    tracked: true

# Custom agents source (optional, overrides default location)
agents_source: ~/my-agents

# Custom extras source (optional, overrides default location)
extras_source: ~/my-extras

# Non-skill resources to sync
extras:
  - name: rules
    source: ~/company-shared/rules   # optional per-extra override
    targets:
      - path: ~/.claude/rules
      - path: ~/.cursor/rules
        mode: copy

# Files to ignore during sync
ignore:
  - "**/.DS_Store"
  - "**/.git/**"
  - "**/node_modules/**"
  - "**/*.log"

Fields

`source`

Path to your skills directory (single source of truth).

source: ~/.config/skillshare/skills

Default: ~/.config/skillshare/skills

`mode`

Default sync mode for all targets.

mode: merge

Value	Behavior
`merge`	Each skill symlinked individually. Local skills preserved. (default)
`copy`	Each skill copied as real files. For AI CLIs that can't follow symlinks.
`symlink`	Entire target directory is one symlink.

`target_naming`

Default target naming strategy for merge/copy sync.

target_naming: flat

Value	Behavior
`flat`	Nested skills flattened with `__` separators (e.g. `frontend__dev`). (default)
`standard`	Uses the SKILL.md `name` field directly (e.g. `dev`). Follows the Agent Skills spec.

`targets`

AI CLI skill directories to sync to.

targets:
  <name>:
    path: <path>
    mode: <mode>  # optional, overrides default
    include: [<glob>, ...]  # optional, merge/copy mode only
    exclude: [<glob>, ...]  # optional, merge/copy mode only

Example:

targets:
  claude:
    path: ~/.claude/skills

  codex:
    path: ~/.codex/skills
    mode: symlink

  custom:
    path: ~/my-app/skills

`include` / `exclude` (target filters)

Use per-target filters to control which skills are synced in merge and copy modes.

targets:
  codex:
    path: ~/.codex/skills
    include: [codex-*]
  claude:
    path: ~/.claude/skills
    exclude: [codex-*]

Rules:

Matching is against target flat names (for example team__frontend__ui)
include is applied first
exclude is applied after include
Pattern syntax uses Go filepath.Match (*, ?, [...])
In symlink mode, include/exclude is ignored
If a previously synced source link becomes excluded, sync removes that target entry
Local non-symlink folders that already existed in target are preserved

Pattern cheat sheet

Pattern	Matches	Typical use
`codex-*`	`codex-agent`, `codex-rag`	Prefix-based grouping
`team__*`	`team__frontend__ui`	Repo/group namespace
`*-experimental`	`rag-experimental`	Suffix-based cleanup
`core-?`	`core-a`, `core-1`	Single-character variant
`[ab]-tool`	`a-tool`, `b-tool`	Small explicit set

Scenario A: include only

Use include when a target should receive only a focused subset.

targets:
  codex:
    path: ~/.codex/skills
    include: [codex-*, shared-*]

Use case:

Keep Codex focused on coding workflows only
Avoid sending writing/research-only skills to this target

Scenario B: exclude only

Use exclude when a target should receive almost everything except a known subset.

targets:
  claude:
    path: ~/.claude/skills
    exclude: [*-experimental, codex-*]

Use case:

Keep one main target broad
Hide unstable or target-specific skills

Scenario C: include + exclude

Use both when you want a broad include, then carve out exceptions.

targets:
  cursor:
    path: ~/.cursor/skills
    include: [core-*, team__*]
    exclude: [*-deprecated, team__legacy__*]

Evaluation order:

Keep only names matching include
Remove matches from exclude

Given source skills:

core-auth
core-deprecated
team__frontend__ui
team__legacy__docs
misc-tool

Result for cursor:

Synced: core-auth, team__frontend__ui
Not synced: core-deprecated, team__legacy__docs, misc-tool

Managing filters via CLI

Instead of editing YAML manually, use the target command:

# Skills
skillshare target claude --add-include "team-*"
skillshare target claude --add-exclude "_legacy*"
skillshare target claude --remove-include "team-*"

# Agents (only for targets with an agents path)
skillshare target claude --add-agent-include "team-*"
skillshare target claude --add-agent-exclude "draft-*"
skillshare target claude --remove-agent-include "team-*"

skillshare sync  # Apply changes

Duplicate patterns are silently ignored. Invalid glob patterns return an error. Agent filters use the same glob syntax as skill filters, but only work in merge and copy modes. In symlink mode, agent filters are ignored because the entire agents directory is linked as one unit.

See target command for full reference.

Skill-level targets

Skills can declare which targets they're compatible with using metadata.targets in SKILL.md. A top-level targets field is still supported as a fallback for older skills, but metadata.targets takes precedence when both are present:

---
name: claude-prompts
metadata:
  targets: [claude]
---

This is a second layer of filtering that works alongside config-level include/exclude:

Source Skills
  │
  ├─ Config include/exclude    ← per-target, set by consumer
  │
  └─ Skill targets field       ← per-skill, set by author
      │
      ▼
  Skills synced to target

Evaluation order:

include — keep only matching names
exclude — remove matching names
targets field — remove skills whose targets list doesn't include this target

Both layers must pass (AND relationship). Config filters always take priority — even if a skill declares targets: [claude], a config exclude: [claude-*] will still exclude it.

Cross-mode matching: targets: [claude] matches both the global target claude and the project target claude, because they refer to the same AI CLI. See supported targets.

tip

Use config filters (include/exclude) when the consumer wants to control what goes where. Use skill-level targets when the author knows the skill only works with specific AI CLIs.

Existing target entries when filters change

When you add or change filters, then run skillshare sync:

Existing item in target	What happens
Source-linked symlink/junction that is now filtered out	Removed (unlinked)
Managed copy (copy mode) that is now filtered out	Removed
Local non-symlink directory created in target	Preserved
Unrelated local content	Preserved

`skills`

Tracks remotely-installed skills. Auto-managed by skillshare install and skillshare uninstall.

skills:
  - name: pdf
    source: anthropics/skills/skills/pdf
  - name: _team-skills
    source: github.com/team/skills
    tracked: true

Field	Required	Description
`name`	Yes	Skill directory name
`source`	Yes	GitHub URL or local path
`tracked`	No	`true` if installed with `--track` (default: `false`)

When you run skillshare install with no arguments, all listed skills that aren't already present are installed. This makes config.yaml a portable skill manifest — copy it to another machine and run skillshare install && skillshare sync.

The skills: list is automatically updated after each install and uninstall operation. You don't need to edit it manually.

Migrated to .metadata.json

Starting from v0.16.2, installed skill entries moved from config.yaml to a separate file. In the current version, all installation metadata is stored in a centralized .metadata.json inside the skills/ directory. Migration from older formats (registry.yaml, per-skill .skillshare-meta.json) is automatic on first run.

`agents_source`

Custom source directory for agents. Overrides the default ~/.config/skillshare/agents/.

agents_source: ~/my-agents

When set, all agents are read from this directory instead of the default. Supports ~ expansion.

Default: ~/.config/skillshare/agents/ (auto-detected, no need to set explicitly unless you want a custom location).

Global mode only

Project mode always uses .skillshare/agents/ and does not support agents_source.

See Agents for details on agent file format, sync behavior, and supported targets.

`extras`

Non-skill resources (rules, commands, prompts, etc.) to sync to arbitrary directories.

extras_source: ~/my-extras            # optional global default source
extras:
  - name: rules
    source: ~/company-shared/rules    # optional per-extra override
    targets:
      - path: ~/.claude/rules
      - path: ~/.cursor/rules
        mode: copy
  - name: agents
    targets:
      - path: ~/.claude/agents
        flatten: true                 # sync subdirectory files flat
  - name: commands
    targets:
      - path: ~/.claude/commands

Field	Required	Description
`name`	Yes	Extra identifier
`source`	No	Custom source directory for this extra (overrides `extras_source` and default)
`targets`	Yes	List of target paths
`targets[].path`	Yes	Destination directory
`targets[].mode`	No	`merge` (default), `copy`, or `symlink`
`targets[].flatten`	No	When `true`, sync subdirectory files directly into target root (cannot use with `symlink`)

extras_source is auto-populated to the default path (~/.config/skillshare/extras/) on skillshare init or first extras init. Override it to use a custom location for all extras.

Source resolution (three-level priority):

Per-extra source → exact path (e.g., ~/company-shared/rules)
extras_source → <extras_source>/<name>/ (e.g., ~/my-extras/rules/)
Default → ~/.config/skillshare/extras/<name>/

Sync modes:

merge (default) — per-file symlinks
copy — per-file copy
symlink — entire directory symlink

Run skillshare sync extras to sync, or skillshare sync --all to sync skills + extras together.

Both modes supported

Extras work in both global and project mode. In project mode, source is .skillshare/extras/<name>/.

See sync extras for usage details.

`ignore`

Glob patterns for files to skip during sync.

ignore:
  - "**/.DS_Store"
  - "**/.git/**"
  - "**/node_modules/**"

Default patterns:

**/.DS_Store
**/.git/**

`gitlab_hosts`

Hostnames of self-managed GitLab instances that use nested subgroups. Hosts containing gitlab or jihulab in the name are detected automatically — this field is only needed for other custom domains.

gitlab_hosts:
  - git.company.com
  - code.internal.io

When a hostname is listed here, skillshare install treats the full URL path as the repository (supporting nested subgroups up to 20 levels), instead of assuming the standard owner/repo two-segment split.

Without gitlab_hosts:

# git.company.com/team/frontend/ui → clones "team/frontend", subdir "ui"
skillshare install git.company.com/team/frontend/ui

With gitlab_hosts: [git.company.com]:

# git.company.com/team/frontend/ui → clones "team/frontend/ui" (full path)
skillshare install git.company.com/team/frontend/ui

Workaround without config: append .git to mark the end of the repo path:

skillshare install git.company.com/team/frontend/ui.git

Entries must be bare hostnames (no scheme, path, or port). They are normalized to lowercase.

Environment variable

For CI/CD pipelines that don't have a config file, use SKILLSHARE_GITLAB_HOSTS (comma-separated):

SKILLSHARE_GITLAB_HOSTS=git.company.com,code.internal.io skillshare install git.company.com/team/frontend/ui

When both the config file and env var are set, their values are merged (deduplicated). Invalid entries in the env var are silently skipped.

`audit`

Security audit configuration.

audit:
  block_threshold: CRITICAL
  profile: default
  dedupe_mode: global
  enabled_analyzers: [static, dataflow, tier, integrity]

Field	Values	Default	Description
`block_threshold`	`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO`	`CRITICAL`	Minimum severity to block `skillshare install`
`profile`	`default`, `strict`, `permissive`	`default`	Audit profile preset (sets defaults for threshold and dedupe)
`dedupe_mode`	`legacy`, `global`	`global`	Finding deduplication mode
`enabled_analyzers`	Array of analyzer IDs	(all)	Allowlist of analyzers to run (omit for all)

Profiles set sensible defaults that can be overridden by explicit field values:

Profile	Threshold	Dedupe	Description
`default`	`CRITICAL`	`global`	Same as current behavior
`strict`	`HIGH`	`global`	Stricter blocking for security-conscious teams
`permissive`	`CRITICAL`	`legacy`	Advisory-only, minimal blocking

Analyzer IDs: static, dataflow, tier, integrity, structure, cross-skill

Precedence: CLI flags → project config → global config → profile defaults.

block_threshold only controls when install is blocked — scanning always runs
Use --skip-audit to bypass scanning for a single install
Use --force to override a block (findings are still shown)

Project Config

Location: .skillshare/config.yaml (in project root)

Project config uses a different format from global config.

# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/project-config.schema.json
# Targets — string or object form
targets:
  - claude                    # String: known target with defaults
  - cursor
  - name: custom-ide               # Object: custom path and mode
    path: ./tools/ide/skills
    mode: symlink
  - name: codex                    # Object with filters
    include: [codex-*]
    exclude: [codex-experimental-*]

# Remote skills — auto-managed by install/uninstall
skills:
  - name: pdf
    source: anthropic/skills/pdf
  - name: _team-skills
    source: github.com/team/skills
    tracked: true                  # Cloned with git history

# Audit — same fields as global
audit:
  block_threshold: HIGH
  profile: strict

`targets` (project)

Supports two YAML forms:

Form	Example	When to use
String	`- claude`	Known target, default path and merge mode
Object	`- name: x, path: ..., mode: ..., include: [...], exclude: [...]`	Custom path, mode override, or per-target filters

`skills` (project)

Same schema as the global skills field. Auto-managed by skillshare install -p and skillshare uninstall -p.

Portable Manifest

config.yaml is a portable skill manifest — in both global and project mode. Run skillshare install && skillshare sync on a new machine (or skillshare install -p in a project) to reproduce the same setup.

Managing Config

View current config

skillshare status
# Shows source, targets, modes

Edit config directly

# Open in editor
$EDITOR ~/.config/skillshare/config.yaml

# Then sync to apply changes
skillshare sync

Reset config

rm ~/.config/skillshare/config.yaml
skillshare init

Custom Audit Rules

Location:

Mode	Path
Global	`~/.config/skillshare/audit-rules.yaml`
Project	`.skillshare/audit-rules.yaml`

Rules are merged in order: built-in → global → project. You can add new rules, disable built-in rules, or override severity.

rules:
  # Add a custom rule
  - id: flag-todo
    severity: MEDIUM
    pattern: todo-comment
    message: "TODO comment found"
    regex: '(?i)\bTODO\b'

  # Disable a built-in rule
  - id: insecure-http-0
    enabled: false

Field	Required	Description
`id`	Yes	Unique rule identifier
`severity`	Yes	`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO`
`pattern`	Yes	Pattern category name
`message`	Yes	Human-readable finding description
`regex`	Yes	Regular expression to match
`exclude`	No	Suppress match when line also matches this regex
`enabled`	No	Set `false` to disable a built-in rule

To scaffold a starter file:

skillshare audit --init-rules       # Global
skillshare audit --init-rules -p    # Project

See audit command for full details.

Environment Variables

Variable	Description
`SKILLSHARE_CONFIG`	Override config file path
`GITHUB_TOKEN`	For API rate limit issues

Example:

SKILLSHARE_CONFIG=~/custom-config.yaml skillshare status

Skill Metadata

When you install a skill, skillshare records its metadata in the centralized .metadata.json file:

{
  "skills": [
    {
      "name": "pdf",
      "source": "anthropics/skills/skills/pdf",
      "type": "github",
      "installed_at": "2026-01-20T15:30:00Z",
      "repo_url": "https://github.com/anthropics/skills.git",
      "subdir": "skills/pdf",
      "version": "abc1234"
    }
  ]
}

Each skill entry includes:

Field	Description
`name`	Skill directory name
`source`	Original install source input
`type`	Source type (`github`, `local`, etc.)
`installed_at`	Installation timestamp
`repo_url`	Git clone URL (git sources only)
`subdir`	Subdirectory path (monorepo sources only)
`version`	Git commit hash at install time

This is used by skillshare update and skillshare check to know where to fetch updates from.

Don't edit this file manually.

Platform Differences

macOS / Linux

source: ~/.config/skillshare/skills
targets:
  claude:
    path: ~/.claude/skills

Uses symlinks.

Windows

source: %AppData%\skillshare\skills
targets:
  claude:
    path: %USERPROFILE%\.claude\skills

Uses NTFS junctions (no admin required).

Source & Targets — Core concepts
Sync Modes — Merge vs copy vs symlink
Environment Variables — All variables

Overview​

IDE Support (JSON Schema)​

Adding to an existing config​

Supported editors​

Config File​

Full Example​

Fields​

source​

mode​

target_naming​

targets​

include / exclude (target filters)​

Pattern cheat sheet​

Scenario A: include only​

Scenario B: exclude only​

Scenario C: include + exclude​

Managing filters via CLI​

Skill-level targets​

Existing target entries when filters change​

skills​

agents_source​

extras​

ignore​

gitlab_hosts​

Environment variable​

audit​

Project Config​

targets (project)​

skills (project)​

Managing Config​

View current config​

Edit config directly​

Reset config​

Custom Audit Rules​

Environment Variables​

Skill Metadata​

Platform Differences​

macOS / Linux​

Windows​

Related​