Skill picker

Skill Picker

Install selected skills into the current project by linking them from the local Skills repository. Always keep .agents/skills as the project-standard source of truth. For popular coding agents that use their own skill folders instead of .agents, mirror the selected skill links into their agent-specific locations when those agents are installed.

Workflow

1. Run from the target project root.
2. Read README.md in skills directory. It would help you find the exact skill name and location. If README.md is missing use find command to look for relevant skills. Example: find . -type d -name "*react*" -exec readlink -f {} \; to find a skill with that has react in its name.
3. Use scripts/pick_skills.py with with the requested skill or bundle names and --source-root prefix of user's skills collection directory.
4. Verify the links before reporting completion.

When the user asks which skill to pick, do not pick immediately. Search for README.md files inside the configured Skills directory, read the relevant skill descriptions, suggest the best matching skill or small set of skills for current project, and run the picker only after the user approves the choice.

python3 $HOME/.agents/skills/skill-picker/scripts/pick_skills.py <skill_name> <folder_with_skills> --source-root $HOME/Skills

<IMPORTANT>The Skills folder must be specified in your system instructions: "Skills directory location: {{ SKILLS_FOLDER }}". If you don't see this, either prompt user for Skills folder location or try to search for it. Suggest user to add "Skills directory location" to global system instructions file if it is missing.</IMPORTANT>

The script defaults to ~/Skills as the source repository and the current directory as the target project. Use --source-root or --project-root when either differs.

Behavior

• Create .agents/skills when missing.
• Link each selected skill folder into .agents/skills/<skill-name>.
• Detect installed non-.agents agent flows for Claude Code and Cline.
• When Claude Code is detected, create .claude/skills when missing and link each selected skill into .claude/skills/<skill-name>.
• When Cline is detected, create .cline/skills when missing and link each selected skill into .cline/skills/<skill-name>.
• Do not create Codex- or OpenCode-specific folders; they should consume .agents/skills directly when supported.
• Treat hyphens and underscores as equivalent when matching source folders.
• When a requested folder is a bundle without its own SKILL.md, link every direct child skill folder in that bundle.
• When a nested skill name is requested directly, link only that nested skill.
• Refuse to replace existing non-symlink files or directories.

Examples

# Pick multiple skills; mattpocock-skills expands all child skills.
python3 $HOME/.agents/skills/skill-picker/scripts/pick_skills.py react-best-practices mattpocock-skills

# Pick only one nested skill from mattpocock-skills.
python3 $HOME/.agents/skills/Skills/skill-picker/scripts/pick_skills.py improve-codebase-architecture

After running, check:

ls -la .agents/skills
ls -la .claude/skills .cline/skills 2>/dev/null