jack-references

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.