| name | jack-references |
| description | Manage Jack's personal technical reference library at ~/git/references. Use for searching/reading existing references, or adding new ones. Invoke with /jack-references and optional keywords to search, or when the user wants to save a new reference guide. PROACTIVELY suggest saving a new reference whenever the conversation involves figuring out how a library, API, or tool works — especially after debugging, reading docs, or solving a non-obvious integration problem. A good prompt — "Want me to save this as a reference for next time?" |
Jack References
Personal technical reference library at ~/git/references. Each file is a focused Markdown cheatsheet for a library, API, or tool.
Shared Setup: Resolve Repo Path
First, resolve the absolute path to the references repo:
echo $HOME/git/references
Use the output of this command (e.g. /home/jack/git/references) as the literal path for all subsequent commands in this skill. Never use $HOME again after this step — always substitute the resolved absolute path.
Shared Setup: Clone/Pull
Check if the repo exists:
ls $HOME/git/references/.git 2>/dev/null && echo "exists" || echo "missing"
If missing: clone it:
mkdir -p $HOME/git
gh repo clone jackfranklin/references $HOME/git/references
If it exists: fetch and check if a pull is needed:
git -C $HOME/git/references fetch origin main --quiet
git -C $HOME/git/references rev-parse HEAD
git -C $HOME/git/references rev-parse origin/main
If the hashes differ, pull:
git -C $HOME/git/references pull --ff-only origin main
If they match, skip the pull.
Searching and Reading References
Parse search terms
The user provided: $ARGUMENTS
Split into individual search terms. If $ARGUMENTS is empty, infer relevant keywords from the current task or conversation context (e.g. the library, API, or technology being discussed).
Search for matching files
Run two searches and deduplicate.
Search A — filename match:
ls $HOME/git/references/*.md 2>/dev/null
A file matches if any search term appears in its name after treating hyphens as word separators. For example, "speech" matches browser-speech-to-text.md; "genai" matches google-genai.md.
Search B — content grep (case-insensitive, filenames only):
For each search term:
grep -ril "TERM" $HOME/git/references/
Combine results from A and B, removing duplicates. Keep only .md files.
If more than 4 files matched, prefer files that matched on both filename and content, then filename-only, then content-only. Read the top 4.
Read matched files
Use the Read tool to read each matched file in full. Reference files are intentionally small and self-contained — always read the complete file, never truncate.
Fallback — no matches found
If the search returned nothing, list all available reference files:
ls $HOME/git/references/*.md 2>/dev/null
Display as a bullet list (strip the path prefix and .md suffix for readability) and ask the user which one to read, or pick the most likely candidate based on context.
Return the reference content
Explain which file(s) you found and why they're relevant, then present the full reference content in a way that directly addresses the current task. Do not summarize or truncate — complete, accurate reference material is the deliverable.
If multiple files matched, separate their contents with a heading per file.
Adding a New Reference
Use this when the user wants to save a new reference guide, or when you've just figured out how something works and it's worth capturing for future use.
1. Determine the filename
Use lowercase kebab-case based on the topic: <technology-or-topic>.md. Examples: openai-responses-api.md, deno-kv.md, css-container-queries.md.
Check it doesn't already exist:
ls $HOME/git/references/<proposed-name>.md 2>/dev/null && echo "exists" || echo "new"
If a file already exists for this topic, offer to update it instead of creating a duplicate.
2. Write the file
Reference files follow this structure:
# <Title>
Brief one-line description of what this is.
## Key concepts / API
...focused, practical content...
## Examples
...real usage examples...
## Gotchas / notes
...anything non-obvious...
Keep it dense and practical — these are personal cheatsheets, not tutorials. No padding.
Use the Write tool to create $HOME/git/references/<filename>.md.
3. Commit and push
git -C $HOME/git/references add <filename>.md
git -C $HOME/git/references commit -m "add <filename>"
git -C $HOME/git/references push origin main
Confirm the push succeeded and report the filename back to the user.
