add

QMD Add: Clone + Index a GitHub Repo

ultrathink

You are a reference library curator. Your job is to clone external repos, detect their structure, index them for search, and verify they're ready for retrieval. You care about file type detection, mask correctness, and index health. You execute every step and verify its output before proceeding.

Current State

!qmd status 2>/dev/null || echo "No QMD index yet"

Current Config

!cat "${XDG_CONFIG_HOME:-$HOME/.config}/qmd/index.yml" 2>/dev/null || echo "No config yet"

Arguments

• $ARGUMENTS first token is URL or owner/repo shorthand (required)
• $ARGUMENTS containing --name: Override collection name (must be [a-zA-Z0-9_-] only)
• $ARGUMENTS containing --mask: Skip auto-detection, use provided glob pattern
• $ARGUMENTS containing --dest: Override clone destination (default: ~/Developer/refs/)
• $ARGUMENTS containing --full: Clone with full history (not shallow)
• $ARGUMENTS containing --defer-embed: Skip embedding step, run /qmd:update later
• $ARGUMENTS containing --dry-run: Preview only. Run Steps 1-3, print plan, exit

Constraints

• Execute commands, not suggestions. No dry-run prose
• Stop immediately on any step failure. Do not continue with broken state
• Never delete anything. Use trash (if available), never rm
• Refs directory: --dest value if provided, otherwise ~/Developer/refs/. All steps below reference this as REFS
• QMD config: ${XDG_CONFIG_HOME:-~/.config}/qmd/index.yml
• If --dry-run: exit after Step 3. No cloning, no indexing, no embedding
• If embed fails: report error, print retry command (qmd embed), exit

---

Step 1: Parse input

• Full URL: https://github.com/owner/repo → name = repo
• Shorthand: owner/repo → URL = https://github.com/owner/repo, name = repo
• --name overrides (must be [a-zA-Z0-9_-] only)
• --dest: override clone destination directory (default: ~/Developer/refs/)
• --full: clone with complete history (default is shallow --depth 1)
• --defer-embed: skip embedding, run /qmd:update later to embed in batch
• --mask: skip auto-detection, use provided glob pattern
• --dry-run: run Steps 1-3 only, print execution plan, exit without side effects

Step 2: Clone or pull

mkdir -p $REFS

If $REFS/<name> already exists:

git -C $REFS/<name> pull --ff-only

If pull fails with fatal: Not possible to fast-forward:

• Report: "Branch diverged from remote. Re-run with manual resolution or run git -C $REFS/<name> pull --rebase."
• Stop. Do not continue.

Otherwise, shallow clone (default):

git clone --depth 1 https://github.com/<owner>/<repo> $REFS/<name>

If --full: omit --depth 1.

Step 3: Detect mask

If --mask provided, use it and skip to Step 4.

Detect from the repo root:

detected = []

if package.json exists OR any .ts/.tsx files:
    detected += "typescript"
if Cargo.toml exists OR any .rs files:
    detected += "rust"
if go.mod exists OR any .go files:
    detected += "go"
if pyproject.toml exists OR any .py files:
    detected += "python"
if Package.swift exists OR any .swift files:
    detected += "swift"

if len(detected) == 0:
    STOP → "Could not detect project type. Re-run with --mask '<glob>'."
if len(detected) > 1:
    WARN → "Multiple types detected: {detected}. Merging masks."
    mask = union of all matched type extensions
if len(detected) == 1:
    mask = extensions for the single matched type

Extension table (for building **/*.{...} mask):

Type	Extensions
typescript	md,mdx,txt,ts,tsx,js,jsx,json,yaml,yml,css
rust	md,txt,rs,toml,yaml,yml
go	md,txt,go,mod,yaml,yml
python	md,txt,py,toml,yaml,yml,cfg
swift	md,txt,swift,yaml,yml

Print detected type(s) and final mask before proceeding.

Dry-run gate

If --dry-run: print the execution plan (the commands Steps 4-8 would run) and exit. Do not clone, add collections, edit config, or embed.

Step 4: Add collection

qmd collection add $REFS/<name> --name <name> --mask "<mask>"

If collection already exists (command errors), remove first then re-add:

qmd collection remove <name>
qmd collection add $REFS/<name> --name <name> --mask "<mask>"

Step 5: Set auto-pull

qmd collection update-cmd <name> "git -C $REFS/<name> pull --ff-only"

Step 6: Add context

Read the repo's README.md. Extract the first non-empty paragraph after the H1 heading (skip badges, blank lines, shields.io links). Truncate to one sentence.

qmd context add qmd://<name>/ "<one-sentence description>"

Step 7: Embed

If --defer-embed: skip. Print: "Embedding deferred. Run /qmd:update to embed."

Otherwise:

qmd embed

First run downloads models (~2GB) automatically, or manually via qmd pull. If interrupted, retry.

Embedding uses 900 tokens/chunk with 15% overlap.

Step 8: Verify

qmd status

Confirm: non-zero document count for the new collection. If embed was not deferred, confirm zero pending embeddings.

If embed ran, run a sample search to verify the mask indexed useful content:

qmd search "<keyword from README>" --collection <name> --limit 3

Zero results after successful embedding means the mask missed the important files. Re-run with --mask to fix.

Report: collection name, document count, mask used, clone type (shallow/full).

Known Limitations

• First run downloads ~2GB of GGUF models (embeddinggemma-300M, qwen3-reranker-0.6b, qmd-expand GRPO). If interrupted mid-download, retry qmd embed or qmd pull manually.
• --depth 1 (default) saves disk but loses git history. Use --full if you need blame or log.
• git clone will fail without SSH keys or tokens configured. The skill does not handle authentication, that's an environment concern.
• Always clones the default branch. To index a specific release, clone manually and use /qmd:add with --mask.
• Requires Node.js 22+ or Bun to run qmd CLI.

Recovery

This skill is idempotent. If it fails partway through, re-run /qmd:add with the same arguments. Step 2 pulls instead of re-cloning, Step 4 removes and re-adds the collection.

Situation	Recovery
Clone failed (network)	Re-run. Step 2 retries the clone
Detection failed	Re-run with --mask "<glob>" to skip detection
Collection add failed	Re-run. Step 4 removes then re-adds
Update-cmd failed	Re-run qmd collection update-cmd <name> "<cmd>"
Embed interrupted	Run qmd embed to resume
Wrong mask indexed	Re-run with --mask. The skill is idempotent

---

Gotchas

• Collections must be re-indexed after upstream docs change (/qmd:update).
• Embeddings must be regenerated after model updates (/qmd:embed).
• --mask glob must match actual file extensions. Wrong mask = empty collection.
• Large repos (>1000 files) take several minutes to embed. Use --defer-embed and run /qmd:embed separately.

---

Reference

• For usage examples, see examples.md