name: faq-shortcuts description: Turn the questions and instructions a user keeps typing into a project into short slash-command skills, mined from their real Claude Code, Codex and Cursor session history and git log. The shortcuts load in Claude Code, Codex and Cursor. Use when the user says they ask the same things every day, wants an FAQ or shortcuts or abbreviations for a project, wants to "stop writing the whole command", or asks what they repeat most. argument-hint: "[project dir, default cwd] [--source all|claude|codex|cursor] [--since YYYY-MM-DD]"

FAQ shortcuts from your own history

People working with an agent on one project type the same asks over and over: "how many signed up", "did it go out?", "send a reminder to those who haven't…". Each time the agent starts cold and has to relearn the traps. This skill mines what was actually asked and turns the most repeated asks into short project skills (/joined, /sent, /remind…). Each one records the right tool and the mistakes already made on that path.

Build from evidence, not from guesses about what might be useful.

1. Collect the asks

python3 scripts/extract_asks.py <project_dir> [--source all|claude|codex|cursor] [--since YYYY-MM-DD] > asks.tsv

On Windows, run it with python instead of python3. This prints every prompt typed in that project's sessions, oldest first, as date<TAB>source<TAB>prompt. It reads Claude Code (~/.claude/projects/, plus ~/.claude/history.jsonl for sessions older than the 30 days Claude Code keeps transcripts), Codex (~/.codex/sessions/, or $CODEX_HOME) and Cursor (its state.vscdb SQLite store) by default, and skips subagent turns and scripted runs such as codex exec, because nobody typed those. An ask repeated across tools counts as one cluster. Cursor chats opened without a folder belong to no project, so they are not read.

Write the output to a scratch location, not into the repo, because prompts can contain names, emails and tokens.

Also read the commit subjects (git log --format='%ad %s' --date=short). Commits show which operations recur, like repeated send-*, sync-* and import-* scripts. Prompts show how the user phrases them.

2. Cluster by intent, then count

Read the whole list. Group prompts that want the same outcome whatever their wording ("how many joined", "how many confirmed", "how many members now" → one head-count ask). Count each cluster and keep 2–3 verbatim phrasings, which become the description's triggers.

A cluster earns a shortcut when:

• it recurs (roughly 5+ times, or on most working days), and
• it takes more than one lookup to answer properly, or it has already gone wrong at least once. Look for follow-ups like "you did it wrong", "why did you…", "did you check…".

Drop one-offs and anything a single command already answers.

3. Check what already exists

List .claude/skills/, .claude/commands/, .agents/skills/ and the project's CLAUDE.md and AGENTS.md. Extend an existing skill instead of adding a near-duplicate. Then find the project's existing tools for each cluster, such as scripts, CLI commands and API routes. A shortcut should point to the tool that exists. Don't write a new one.

Read those tools' headers and the commits that fixed them. The traps you find there are the most valuable part of each skill.

4. Propose before writing

Show the user a short table with shortcut name, the ask it replaces, and how often it appeared. Let them pick. Short names beat descriptive ones here, because the point is less typing. Use one lowercase word, and never shadow a built-in command.

5. Write each skill

.claude/skills/<name>/SKILL.md, committed with the project so it travels. Claude Code and Cursor load skills from .claude/skills/. Codex loads them from .agents/skills/, so link each one there as well:

mkdir -p .agents/skills && ln -s ../../.claude/skills/<name> .agents/skills/<name>

Link each skill folder, not .agents/skills itself: Codex follows a symlinked skill folder but does not scan a symlinked .agents/skills.

The skill file itself:

---
name: <short>
description: <what it does>. Use for "<verbatim phrasing 1>", "<phrasing 2>", "<phrasing 3>".
argument-hint: "[optional arg]"
---
# <What it answers>

Report only / Dry run first — **never <write/send> from this skill without a yes.**

## Query / tool       ← the existing script or query, with its real flags
## Traps              ← only ones that actually happened, each with the consequence
## Report             ← exactly what to print, then ask

Rules:

• Split reading from acting. Question skills only report. Action skills dry-run, show the list with every exclusion and its reason, then apply only after a yes.
• Point to the source for every trap, like the script header, commit or incident. If you can't trace a trap to something that happened, leave it out.
• Verify every field, flag and file name against the code before you write it down. A shortcut that cites a wrong column fails silently on the day it's needed.
• Keep a skill short enough to read in a minute. Leave out history, keep the lesson.
• Quote the frontmatter description if it contains : or #, or YAML will truncate it.

6. Make them findable

Add a table to the project's CLAUDE.md (and AGENTS.md, if the project has one) that maps each shortcut to the sentence it replaces. It serves as both documentation and a reminder to use it.

Report

The shortcuts added, the ask each replaces with its count, and any frequent cluster you deliberately left out and why.

cli-faq-shortcuts

Stop typing the same long request to your coding agent every day. This Agent Skill reads your own history, finds the asks you keep repeating, and turns each one into a short command, like /sent or /project billing. It works in Claude Code, Codex and Cursor.

The extractor uses only Python's standard library: no packages, API keys, or network access are needed. Intent grouping happens in your coding agent.

Watch or download the 24-second video · What's new in v1.2.0

The demo illustrates the workflow with synthetic data; it is not a live agent recording.

Quick start

1. Install (macOS / Linux, needs git and Python 3.9+; on Windows see Windows):

git clone https://github.com/kishormorol/cli-faq-shortcuts ~/.agents/skills/faq-shortcuts
mkdir -p ~/.claude/skills && ln -sfn ~/.agents/skills/faq-shortcuts ~/.claude/skills/faq-shortcuts

2. Open your project in Claude Code, Codex or Cursor, in a new session.

3. Ask "what do I keep asking in this project?", or type /faq-shortcuts in Claude Code.

You'll get a table of your most repeated asks with how often you typed each. Pick the ones you want and they become shortcuts in that project.

The repo is cli-faq-shortcuts; the skill it installs is called faq-shortcuts.

If it saves you typing, please ⭐ star the repo. Stars are how other people find it.

Commands

# inside your project, in Claude Code
/faq-shortcuts                        # find your repeated asks and propose shortcuts
/faq-shortcuts --since 2026-06-01     # only look at recent history
/faq-shortcuts --source codex         # only what you asked Codex

# the extractor on its own: no agent, nothing leaves your machine
E=~/.agents/skills/faq-shortcuts/scripts/extract_asks.py
python3 "$E" .                       # matching prompts, oldest first
python3 "$E" . --since 2026-09-01 | wc -l               # how many since September
python3 "$E" . --format jsonl         # structured records for your own scripts
python3 "$E" . | awk -F'\t' 'split($3,w," ")>=4 {print tolower($3)}' \
  | sort | uniq -c | sort -rn | head                     # your most repeated exact requests

The last one counts exact repeats only, and it undercounts. On one real project, the most repeated exact request appeared 4 times. Grouped by intent, however it was worded, the top ask had been typed 127 times. That grouping is the agent's job in /faq-shortcuts.

What you get

Each shortcut is a small file in your project, .claude/skills/<name>/SKILL.md, for example:

---
name: sent
description: Check whether a batch email actually reached people. Use for "did the
  newsletter go out?", "did it reach everyone?", "did X get the email?".
---
# Did it go out

Report only. Never re-send from this shortcut.

## Query
scripts/email-status.js --batch <name>   ← the script your project already has

## Traps
- A "delivered" status to a shared inbox proves nobody read it (happened 3 May).

## Report
Sent / delivered / bounced counts, then the bounced addresses. Then ask.

The shortcuts point at the scripts and queries your project already uses, and they record the mistakes already made on that path. /sent checks the send record, not the earlier message where the agent said it sent it. So a shortcut is shorter to type, and it verifies the outcome instead of trusting a previous claim. Anything that writes or sends does a dry run first and waits for your yes, so a typo stops at the preview.

How it works

1. Collect. scripts/extract_asks.py prints every prompt you typed in the project, from Claude Code and Codex history. It skips subagent turns and scripted runs, because you didn't type those.
2. Cluster. The agent groups prompts by intent, whatever the wording, and counts them.
3. Check. It looks for shortcuts you already have and the tools your project already has.
4. Propose. You get a table of shortcut, the ask it replaces, and how often you asked. You pick.
5. Write. Each chosen shortcut becomes a SKILL.md in .claude/skills/, linked into .agents/skills/ so all three agents load it, committed so your team gets it too.
6. List. A table in CLAUDE.md / AGENTS.md maps each shortcut to the sentence it replaces.

Install

The quick start above is the whole install. It puts the skill where each agent looks:

Update: git -C ~/.agents/skills/faq-shortcuts pull --ff-only, then start a new agent session.

Uninstall: rm ~/.claude/skills/faq-shortcuts && rm -rf ~/.agents/skills/faq-shortcuts

As a Claude Code plugin

If you only use Claude Code, you can install it as a plugin instead, inside Claude Code:

/plugin marketplace add kishormorol/cli-faq-shortcuts
/plugin install faq-shortcuts@cli-faq-shortcuts

The command is then /faq-shortcuts:faq-shortcuts, or just ask "what do I keep asking in this project?". Codex and Cursor don't read Claude Code plugins, so use the quick start for those.

Windows

In PowerShell, with git and Python 3.9+ installed. A directory junction links the skill into ~/.claude/skills and, unlike a symlink, needs no admin rights or Developer Mode:

git clone https://github.com/kishormorol/cli-faq-shortcuts "$env:USERPROFILE\.agents\skills\faq-shortcuts"
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
New-Item -ItemType Junction -Path "$env:USERPROFILE\.claude\skills\faq-shortcuts" -Target "$env:USERPROFILE\.agents\skills\faq-shortcuts"

Run the extractor with python (or py), not python3:

python "$env:USERPROFILE\.agents\skills\faq-shortcuts\scripts\extract_asks.py" . | Select-Object -First 10

Update: git -C "$env:USERPROFILE\.agents\skills\faq-shortcuts" pull --ff-only, then start a new agent session.

Uninstall: remove the junction with rmdir, which leaves its target alone, then the clone:

cmd /c rmdir "$env:USERPROFILE\.claude\skills\faq-shortcuts"
Remove-Item -Recurse -Force "$env:USERPROFILE\.agents\skills\faq-shortcuts"

What it reads

To see what it finds without the agent:

python3 ~/.agents/skills/faq-shortcuts/scripts/extract_asks.py ~/my-project | head

This prints date<TAB>source<TAB>prompt. Add --source claude, --source codex, or --source cursor to read one tool only, and --since 2026-01-01 to skip older prompts.

Extractor reference

python scripts/extract_asks.py [project_dir] [--source all|claude|codex|cursor]
                              [--since YYYY-MM-DD] [--max-len N] [--format tsv|jsonl]

JSONL records have date, source, and prompt fields. Both formats collapse prompt whitespace to single spaces. Dates are YYYY-MM-DD, or an empty string when unavailable; undated records sort first. Counts and diagnostics go to stderr, keeping stdout usable in a pipeline. Exit codes: 0 when a source is available (even if filters match nothing), 1 when no source is available, and 2 for invalid arguments.

Limits

• This is a view of the history still stored on your machine, not a complete activity log.
• Prompts longer than 400 characters, injected context, and non-interactive runs are filtered out. Increase --max-len if your usual requests are longer.
• Projects a