skill-picker

name	skill-picker
description	Select and link existing skills from a local curated collection into a project's configured skill directories. Use when the user asks to pick, recommend, install, or connect collection skills to a project, including bundles and nested skills. Not for downloading or authoring new skills.

Skill Picker

Link only the collection skills that the target project needs. .agents/skills is the sole default target; additional targets are opt-in configuration, never inferred from installed harnesses.

Workflow

1. Run from the target project root. Locate this skill's base directory and run:

   python3 <skill-base>/scripts/pick_skills.py --show-config
   

2. Read DATABASE.md in the reported source_root. Treat it as the catalog for names, paths, descriptions, categories, and applicability. If it is missing, stop and report that the configured collection is incomplete.

3. If the user named skills or a bundle, resolve those names. If the user asks what to pick, inspect the project, shortlist the smallest relevant set from DATABASE.md, explain the recommendation, and wait for approval.

4. Run the picker with the approved names and target project. Do not add harness-specific targets unless the user requested them or they are present in configuration.

5. Verify every resulting link and confirm that no unconfigured skill directories were created.

The task is complete when each requested skill resolves to its collection source from every configured target and no unrelated target directory changed.

Configuration

Default configuration:

{
  "source_root": "~/Skills",
  "targets": ["agents"]
}

Store overrides in ~/.config/skill-picker/config.json, or set SKILL_PICKER_CONFIG to another JSON file. SKILL_PICKER_SOURCE_ROOT overrides only the collection path. Command-line flags override both environment and config.

Target aliases:

• agents → .agents/skills
• claude → .claude/skills
• cline → .cline/skills

--target is repeatable and may also contain another project-relative directory. Supplying any --target values replaces the configured target list for that run.

Commands

Use configured defaults—only .agents/skills unless changed:

python3 <skill-base>/scripts/pick_skills.py typescript-best-practices --project-root .

Override the source collection:

python3 <skill-base>/scripts/pick_skills.py impeccable \
  --source-root /path/to/Skills --project-root /path/to/project

Opt into Claude Code as an additional target for one run:

python3 <skill-base>/scripts/pick_skills.py impeccable \
  --target agents --target claude

Names match hyphens and underscores equivalently. A bundle selects every descendant skill recursively. A nested skill name selects only that skill. Existing non-symlink paths are preserved and reported as errors.