Files
skillshare/website/docs/reference/targets/configuration.md
T
Willie ccdafd3293 feat(sync): add target_naming config option (flat/standard)
Add per-target target_naming setting that controls how skill directories
are named in sync targets. 'flat' (default) preserves the existing
flattened __ separator behavior. 'standard' uses the SKILL.md name field
directly, following the Agent Skills specification.

Standard mode:
- Validates SKILL.md names match directory basenames
- Detects and skips name collisions with warnings
- Auto-migrates managed entries when switching from flat to standard
- Preserves legacy entries when bare name is already occupied

Also includes:
- Per-target toggle via CLI (--target-naming), TUI (N key), and Web UI
- Collision output redesigned as deduplicated compact summary
- Config inheritance: global target_naming → per-target override
- JSON schema + UI validation for the new field

Closes #110
2026-04-01 00:32:49 +08:00

20 KiB

sidebar_position
sidebar_position
4

Configuration

Configuration file reference for skillshare.

Overview

~/.config/skillshare/
├── config.yaml          ← Configuration file
├── registry.yaml        ← Skill registry (auto-managed)
├── skills/              ← Source directory (your skills)
│   ├── 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 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:

  1. Keep only names matching include
  2. 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:

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:

  1. include — keep only matching names
  2. exclude — remove matching names
  3. 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.

:::note Migrated to registry.yaml Starting from v0.16.2, installed skill entries are stored in a separate registry.yaml file instead of inside config.yaml. Existing skills: entries in config.yaml are migrated automatically on first run. The schema and fields remain the same. :::

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

  1. Per-extra source → exact path (e.g., ~/company-shared/rules)
  2. extras_source → <extras_source>/<name>/ (e.g., ~/my-extras/rules/)
  3. 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.

:::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_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.

:::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 creates a .skillshare-meta.json file:

{
  "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"
}
Field Description
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).