The agents_source field was already implemented but had no documentation, unlike extras_source which was fully documented. - Add agents_source to Full Example in configuration.md - Add dedicated agents_source field reference section - Add Custom Source Directory section to understand/agents.md - Note agents_source in Skills vs Agents comparison table
21 KiB
sidebar_position
| sidebar_position |
|---|
| 4 |
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) includeis applied firstexcludeis applied after include- Pattern syntax uses Go
filepath.Match(*,?,[...]) - In
symlinkmode, include/exclude is ignored - If a previously synced source link becomes excluded,
syncremoves 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-authcore-deprecatedteam__frontend__uiteam__legacy__docsmisc-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:
skillshare target claude --add-include "team-*"
skillshare target claude --add-exclude "_legacy*"
skillshare target claude --remove-include "team-*"
skillshare sync # Apply changes
Duplicate patterns are silently ignored. Invalid glob patterns return an error.
See target command for full reference.
Skill-level targets
Skills can declare which targets they're compatible with using the targets field in SKILL.md:
---
name: claude-prompts
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 namesexclude— remove matching namestargetsfield — 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.
:::note 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).
:::note 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 symlinkscopy— per-file copysymlink— entire directory symlink
Run skillshare sync extras to sync, or skillshare sync --all to sync skills + extras together.
:::info 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_thresholdonly controls when install is blocked — scanning always runs- Use
--skip-auditto bypass scanning for a single install - Use
--forceto 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.
:::tip 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).
Related
- Source & Targets — Core concepts
- Sync Modes — Merge vs copy vs symlink
- Environment Variables — All variables