| name | suggest-skills |
| description | Analyze past Claude Code and Codex sessions to suggest new skills, workflow improvements, or changes to existing skills. Identifies repetitive patterns and unmet automation opportunities. |
| argument-hint | [--days <N>] [--project <name>] |
| allowed-tools | Read, Bash, Glob, Grep, Agent |
Analyze recent conversation history across Claude Code and Codex to identify opportunities for new skills, workflow improvements, or changes to existing skills.
@shared/SESSION_PARSING.md
Arguments
--days <N> — how far back to look (default: 14)--project <name> — focus on sessions from a specific project
Workflow
1. Inventory Existing Skills
Read the skill directories to build a list of what already exists:
ls ~/.claude/skills/ | grep -v shared
For each skill, read just the frontmatter (first 6 lines) of SKILL.md to get the name and description.
2. Discover Recent Sessions
Find session files modified in the last N days:
find ~/.claude/projects -name "*.jsonl" -not -path "*/subagents/*" -mtime -${DAYS} -type f
find ~/.codex/sessions -name "*.jsonl" -mtime -${DAYS} -type f
If --project is set, filter to matching paths.
3. Sample Sessions
For efficiency, don't read every session end-to-end. Instead:
- Sort files by modification time (newest first)
- Take up to 20 sessions
- For each session, extract only user messages (skip system messages, tool results, and assistant responses). These reveal what the user is asking for and doing repeatedly.
Use a Bash one-liner per file to extract user text:
python3 -c "
import json, sys
with open(sys.argv[1]) as f:
for line in f:
try:
obj = json.loads(line)
if obj.get('type') == 'user':
msg = obj.get('message', {})
content = msg.get('content', '') if isinstance(msg, dict) else ''
if isinstance(content, str) and len(content) > 20 and not content.startswith('<'):
print(content[:500])
elif obj.get('type') == 'response_item':
p = obj.get('payload', {})
if p.get('role') == 'user':
for b in (p.get('content') or []):
t = b.get('text', '')
if len(t) > 20 and not t.startswith('<') and not t.startswith('#'):
print(t[:500])
except: pass
" FILE
4. Analyze Patterns
With the sampled user messages, identify:
A. Repetitive requests — Things the user asks for repeatedly across sessions that could be automated into a skill. Look for:
- Similar phrasing across sessions
- Multi-step workflows the user orchestrates manually
- Recurring "can you..." / "I need to..." patterns
B. Tool usage patterns — If assistant messages show repeated tool call sequences (e.g., always running the same grep → read → edit pattern), that's a candidate for a skill.
C. Pain points — Moments where the user expresses frustration, restarts, or corrects the assistant. These suggest the current workflow is inadequate.
D. Cross-session themes — Topics or tasks that span multiple sessions, indicating ongoing work that would benefit from better tooling.
5. Cross-Reference with Existing Skills
For each identified pattern, check whether an existing skill already addresses it. If a skill exists but the user doesn't seem to use it, that's also worth noting (discoverability issue or skill gap).
6. Generate Recommendations
Present findings as a ranked list:
# Skill Suggestions
Based on analysis of N sessions over the last D days.
## New Skills
### 1. /SKILL-NAME — SHORT DESCRIPTION
**Pattern observed:** What the user does repeatedly
**Sessions:** List 2-3 session dates/projects where this appeared
**Effort:** Low / Medium / High
**Impact:** How much time/friction this would save
### 2. ...
## Improvements to Existing Skills
### 1. /EXISTING-SKILL — WHAT TO CHANGE
**Gap observed:** What the skill doesn't handle that the user needs
**Sessions:** Where this gap appeared
## Workflow Observations
- Any cross-cutting insights about how the user works that don't map to a single skill
Rank by impact (time saved × frequency). Limit to 5-7 recommendations total — quality over quantity.
