How to use the SuggestSkills agent skill: install and run it

What an agent skill is and what SuggestSkills does

An agent skill is a folder containing a SKILL.md file and optional supporting files, such as scripts or intent documents, that an AI agent loads when a request matches the skill's description. SuggestSkills is one such skill. Its job is to answer one question: given what you have been doing and where you have been frustrated, is there a recurring problem that deserves its own skill and does not have one yet?

Once installed, the agent can scan your recent work sessions, low-rated frustration logs, and skill-gap records. It then proposes a ranked shortlist of new skills. Each proposal must cite the evidence behind it and is checked against existing skills so it does not duplicate them.

• It is read-only: it never creates or edits a skill itself.
• Accepted proposals are handed off to a separate skill called CreateSkill, which builds or improves skills.
• Gaps hidden under topics that look covered can surface, because frustration is weighted above topic frequency.

Install the SuggestSkills skill

Download the SuggestSkills ZIP from this page and unzip it. You can install it in one of two places, depending on how you use your agent.

For a personal install that applies everywhere, unzip the folder into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ directory. If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal (all projects): ~/.claude/skills/SuggestSkills
• Single project: .claude/skills/SuggestSkills inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload the skill

Ask for a skill gap scan in plain language

You do not need to name the skill or a command. The skill triggers on requests that match its description. Phrases from its trigger list include: "should I create a skill", "what skills do I need", "suggest skills", "skill gap", "based on my recent work", "am I missing a skill", and "what should I build".

The default window is the last 45 days, with a rating cut of 4 for low-rated frustration entries. You can ask for a different window in your request, and the skill's collector accepts a days value from 1 to 3650.

• "What skills should I build based on my recent work?"
• "Skill gap: what am I missing?"
• "I keep hitting the same wall. Am I missing a skill?"

Know what the scan needs before you run it

The skill reads no config file. It takes its inputs from the Bun-run collector, Tools/CollectSignals.ts, using flags or environment variables. The root defaults to $HOME/.claude, and each store (ratings, work sessions, skill-gap records, skills directory, and an optional loops directory) can be pointed elsewhere.

If you have no recorded work history, ratings, or skill-gap data, there is little evidence to ground proposals in, so the shortlist will be thin. If the ratings store is missing, the report should say the frustration signal was unavailable for that run, rather than presenting a topic-only result as complete.

• Bun runtime, needed to execute Tools/CollectSignals.ts
• Local work-session, Errata ratings, skill-gap and skills directories (default root $HOME/.claude)
• Root override: --root <dir> or SKILLSCAN_MEMORY_ROOT
• Window override: --days <n> (default 45)
• Rating cut override: --max-rating <n> (default 4)
• Store overrides: --ratings, --work, --skill-gaps, --skills, --loops, or matching SKILLSCAN_* environment variables
• The full flag table is in Intents/Scan.md under Tool contract.

Read the report and act on it

The report header states the window, the session count, and whether the frustration store was present. Each proposal lists the evidence it rests on: sessions, frustration rows, or skill-gap detections. Read the evidence before deciding. A proposal with weak or missing supporting signals, or one that duplicates an existing capability, should be dropped.

When you accept a proposal, take it to CreateSkill as a separate step. SuggestSkills will not build it for you.

• Check the window and session count in the header.
• Confirm each proposal cites real evidence.
• Reject proposals that duplicate an existing skill.
• Send accepted proposals to CreateSkill.

Safety notes: scripts and network

SuggestSkills runs a script: Tools/CollectSignals.ts, which requires Bun. The skill does not use the network. It reads local directories you already have, and it does not edit or create files in your skills folder. Because it runs a script, review the source of Tools/CollectSignals.ts before you install, as you would with any skill that executes code on your machine.

• Runs scripts: yes (Bun)
• Uses network: no
• Read-only with respect to skills