| name | discover |
| description | Contextual skill discovery - observe what the user is working on and surface relevant WFK skills and principles they might not know about. Use this skill when the user says "discover", "what skills should I use", "what can you do", "help me work better", "workflow tips", "what am I missing", or when a new user wants to learn the kit. Can also run as a lightweight tip during /orient. |
Discover - Contextual Skill Guide
Observe the user's current work context and surface 2-3 WFK skills or principles that would help them right now. This is not a catalog dump. It's a targeted recommendation based on what the user is actually doing.
Arguments: $ARGUMENTS
Path Resolution
Read ~/.claude/wfk-paths.json at startup. Use vault_root and paths to resolve directory references (e.g., {paths.daily_notes}/DN - {today}.md, {paths.projects}/). If the file doesn't exist, use defaults and warn once.
Step 1: Read the user's context
Gather signals about what the user is doing. Read in parallel, skip missing files silently.
-
Today's daily note - 01_Notes/Daily/DN - {today}.md
- What topics are in
## Worked on?
- What's in
## TODO?
- Any meetings listed?
-
Open PICs - glob **/PIC - *.md with status: open
- What work is in flight? What's stalled?
- How many are open? (5+ suggests the user needs
/recap)
-
Recent daily notes - last 3-5 days of DN - *.md
- What skills has the user been invoking? (look for
[[PL -, [[SPC -, [[RE -, [[PJL -, /closeout, /implement references)
- What's repeating? What's missing?
-
Vault structure - quick scan of 02_Projects/
- How many active projects?
- Do projects have CLAUDE.md and lessons.md?
- Do projects have PJL files? (missing PJLs = knowledge not compounding)
- Are there specs without plans? Plans without implementation?
-
User profile - read CLAUDE.md at vault root
- What's the
wfk_role?
- Any queued context or preferences?
Step 2: Build the skill catalog (dynamic)
Do not use a hardcoded skill list. Build the catalog at runtime from installed skills so it stays current as the kit evolves.
2a. Scan installed skills
for dir in ~/.claude/skills/*/; do
name=$(basename "$dir")
if [ -f "$dir/SKILL.md" ]; then
head -15 "$dir/SKILL.md"
fi
done
Read each skill's frontmatter name and description fields. The description contains trigger phrases and use cases - this is your matching material.
2b. Categorize skills
Group skills into categories based on their descriptions. Use these categories as a guide, but let the descriptions drive categorization - new skills should slot into the right group automatically:
| Category | Description keywords to look for |
|---|
| Session lifecycle | orient, pickup, log-work, closeout, end-day, dream, recap |
| Planning and design | spec, review, plan, design, structure, grill |
| Implementation | implement, step-away, test, pr-review, git-safe |
| Research and learning | video, article, best-practice, learn, explain |
| Content and quality | meeting notes, frontend, web-theme, retro, pipeline-qa |
| Meta and maintenance | skill-creator, auto-research, usage-audit, update-wfk, intake, park |
2c. Filter out irrelevant skills
- Skip deprecated skills (check
kit.json if available)
- Skip org-specific skills the user doesn't have installed
- Skip skills with
DEPRECATED in their description
2d. Enrich with context signals
For each skill, note what vault state would make it relevant:
| If you see this... | ...recommend this |
|---|
| No SOD for today | /orient |
| Open PICs exist | /pickup |
| Work done but no DN entry | /log-work |
| Multiple closeouts, no EOD | /end-day |
| 5+ open PICs, long conversation | /recap |
| Feature described with no spec | /create-note SPC |
| Spec exists, no review artifacts | /review-spec |
| Reviewed spec, no plan | /create-note PL |
| Plan exists, no implementation started | /implement |
| Implementation done, no review | /pr-review |
| Complex doc or topic being discussed | /explain |
| Something broke and was fixed | /learn |
| YouTube URL or video mentioned | /video-intel |
| Article URL shared | /article-intel |
| Raw transcript or meeting content | /create-MN |
| User needs a web page or component | /frontend-design |
| Sprint or milestone completed | /retro |
| Files to organize | /intake |
| Context relevant to another project | /park |
| User wants to automate a workflow | /skill-creator |
| Token consumption concerns | /usage-audit |
| Kit hasn't been updated recently | /update-wfk |
Workflow Principles
Not skills, but patterns the user should know. These stay as a curated list because they represent system-level knowledge, not individual tool capabilities.
| Principle | When to Teach | Signal |
|---|
| Spec > Plan > Implement | User jumping straight to code | No spec or plan exists for active work |
| PIC for everything deferred | Work being abandoned without tracking | Tasks mentioned but no PIC created |
| PJL for every project | Project has work but no knowledge compounding | Active project missing a PJL file |
| Both layers on every log | PJL has timeline gaps | Work logged to daily note but PJL has no entry for that date |
| One heading per project in daily notes | Daily note is a wall of text | Multiple entries for same project as separate headings |
| Date subfolders for project docs | Files sitting in specs/ or plans/ directly | Spec or plan file not in a YYYY-MM-DD/ subfolder |
| CLAUDE.md + lessons.md per project | Project has no agent context | Active project missing these files |
| Verify before logging | Closeout logged unverified claims | Daily note says "deployed" but no deploy command was run |
| Session boundaries in the PJL | PJL only has work entries, no start/end | Pickup and create-pickup should log session boundaries |
Step 3: Match and recommend
Compare the user's context (Step 1) against the catalog (Step 2). Find the 2-3 most relevant recommendations.
Matching rules:
- Prioritize skills the user has NEVER used (check daily note history) over skills they use regularly
- Prioritize skills that address an active gap (spec exists without review, plan exists without implementation, project has no PJL) over general suggestions
- Prioritize workflow principles when the user is doing things manually that a skill automates
- Never recommend more than 3 items. If nothing stands out, say so.
Step 4: Present recommendations
Format each recommendation as:
### /skill-name - one-line summary
**Why now:** What you observed in their context that makes this relevant.
**What it does:** 2-3 sentences explaining the skill in plain language, focused on the outcome not the mechanics.
**Try it:** The exact command to run, with any arguments pre-filled from context.
For workflow principles (not skills), use:
### Principle name
**Why now:** What you observed.
**What to do:** Concrete action the user should take.
After the recommendations, add:
Run `/discover catalog` to see all available skills, or ask about any specific skill for details.
Actions
Default (no arguments) - contextual recommendations
Run Steps 1-4 as described above.
catalog - full skill list
Run Step 2 to build the dynamic catalog, then present it as a formatted reference grouped by category. No contextual analysis needed.
<skill-name> - explain a specific skill
Read the named skill's SKILL.md and explain what it does, when to use it, and show an example invocation. Tailor the explanation to the user's context if available.
Skill Chains
Skills compose into documented chains. See [[REF - Skill Chain Map]] for the full map. Key chains:
- Daily: orient → pickup → log-work → closeout → end-day → dream
- Build: create-spec → review-spec → create-note PL → implement → pr-review → retro
- Deploy: git-safe → vps-deploy → document-change
When recommending skills, consider where the user is in a chain and suggest the natural next step.
Constraints
- Maximum 3 recommendations. Quality over quantity.
- Never recommend a skill the user just used in this session.
- Never recommend
/orient or /pickup mid-session (they're session-start skills).
- If the user is clearly experienced (daily notes show regular skill usage across categories), focus on advanced tips and workflow principles rather than basic skill introductions.
- Keep each recommendation under 100 words. The user should be able to scan all 3 in 30 seconds.
Local Customizations
If LOCAL.md exists in this skill directory, load and follow it after these instructions. Local instructions override upstream where they conflict.
