Add

QMD Add: Clone + Index a GitHub Repo

ultrathink

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):

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.

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.