Initial commit

skills/fast-repo-context/EXAMPLES.md

@@ -0,0 +1,57 @@
+# Fast Repo Context - Examples
+
+## Basic Usage
+
+### Find authentication flow
+```bash
+~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "how user authentication and login works"
+```
+
+### Find where data is validated
+```bash
+~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "input validation before saving to database"
+```
+
+### Find error handling
+```bash
+~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "how API errors are handled and returned to client"
+```
+
+### Find component rendering logic
+```bash
+~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "conditional rendering based on user permissions"
+```
+
+## Real-World Scenarios
+
+### Scenario 1: Debug a feature
+
+**User:** "Find where the cart total is calculated incorrectly"
+
+```bash
+~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "shopping cart total calculation with discounts and taxes"
+```
+
+Then read the specific files from results.
+
+---
+
+### Scenario 2: Understand architecture
+
+**User:** "How does the payment system work?"
+
+```bash
+~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "payment processing flow from checkout to confirmation"
+```
+
+---
+
+### Scenario 3: Find similar patterns
+
+**User:** "Find all places that call external APIs"
+
+```bash
+~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "HTTP requests to external services with error handling"
+```
+
+

skills/fast-repo-context/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: fast-repo-context
+description: "Semantic code search using sgrep. Use when: exploring code, search code snippets, finding implementations by intent, understanding how features work. Triggers(semantic or similiar meaning): [fast context], [search code], [find where], [how does X work], [understand codebase], [research codebase], [find X], [locate X], [code search], [grep code], [where is], [let me search]."
+---
+
+# Fast Repo Context
+
+Semantic grep (`sgrep script`) for code search with natural language queries. Note: it only give code snippets/what/where, not how or code explanations, so your query need to be focus on what/where.
+
+## Tool
+
+```bash
+bash ~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "<natural language query>"
+```
+
+**Safety:** Script checks if current directory is a git repo before running to prevent accidental indexing of large/wrong directories.
+
+**Options:**
+- `--json` - Structured JSON output (recommended for agents)
+- `-n, --limit <N>` - Max results (default: 10)
+- `-c, --context` - Show extra context around matches
+- `--glob <GLOB>` - Restrict to file patterns (repeatable)
+- `--filters <FILTERS>` - Filter by metadata (e.g., `lang=rust`)
+
+## When to Use
+
+- Exploring unfamiliar codebases
+- Finding code by intent/behavior (not just keywords)
+- Understanding how features are implemented
+- Locating related code across files
+- Find something in another project/repo on disk
+
+## Workflow
+
+1. **Use sgrep script** for semantic search
+2. **Read specific files** from results for details
+3. **(Optional)** Query `kg` from our knowledge graph for additional context
+
+## Examples
+
+### Find authentication logic
+```bash
+~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "user login and session management"
+```
+
+### Find in another project/repo
+
+Use bash `exa --tree -D -L 2 ~/workspace` to get all projects in ~/workspace.
+
+```
+cd another-dir-abs-path && ~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "file upload handling that use api foo/bar"
+```
+
+### Find error handling patterns
+```bash
+~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "how errors are caught and reported to users"
+```
+
+### Find API endpoints
+```bash
+~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "REST endpoints for user profile operations"
+```
+
+### Find database queries
+```bash
+~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "queries that fetch user data with pagination"
+```
+
+### Find React hooks usage
+```bash
+~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json "custom hooks for form validation"
+```
+
+### With filters
+```bash
+~/.claude/skills/fast-repo-context/scripts/sgrep.sh --json --glob "*.ts" --limit 5 "error handling middleware"
+```
+
+## Tips
+
+- **Be descriptive**: "function that validates email format" > "email validation"
+- **Describe intent**: "code that prevents duplicate submissions" > "debounce"
+- **Ask questions**: "where is the shopping cart total calculated?"
+

skills/fast-repo-context/scripts/sgrep.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Wrapper for sgrep search with safety checks
+# Prevents accidental indexing of large/wrong directories
+# Supports both jj and git repositories
+
+REPO_ROOT=""
+
+# Check for jj repository first (jj often operates atop git)
+if jj root &>/dev/null; then
+    REPO_ROOT=$(jj root)
+# Check for git repository
+elif git rev-parse --git-dir &>/dev/null; then
+    REPO_ROOT=$(git rev-parse --show-toplevel)
+fi
+
+if [[ -z "$REPO_ROOT" ]]; then
+    echo "ERROR: Not inside a git or jj repository!"
+    echo ""
+    echo "Current directory: $(pwd)"
+    echo ""
+    echo "sgrep will index the entire directory which can be slow for large folders."
+    echo "Please cd into the correct repository before running this command."
+    exit 1
+fi
+
+echo "Repo: $REPO_ROOT"
+echo ""
+
+exec sgrep search "$@"