diff --git a/.git-ai/lancedb.tar.gz b/.git-ai/lancedb.tar.gz
index 2932208..b6f72d7 100644
--- a/.git-ai/lancedb.tar.gz
+++ b/.git-ai/lancedb.tar.gz
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:91a96b77017b3dcdf69cbfd6fd59e87ae9a60e6aa5cb0c40c287b9aa694245b8
-size 255609
+oid sha256:4e10bce0e9fec7311be79f4b9d97892dde3284a012ea1dc544c95c54e616a245
+size 268186
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index cdf2ef0..d5063c1 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -10,10 +10,16 @@ on:
         description: "Tag name to release (e.g. v1.2.3). If empty, skip release/publish steps."
         required: false
         type: string
+      npm_only:
+        description: "Only publish to npm (skip GitHub Packages)"
+        required: false
+        type: boolean
+        default: false
 
 permissions:
   contents: write
   packages: write
+  id-token: write
 
 jobs:
   build-and-publish:
@@ -33,13 +39,16 @@ jobs:
       - name: Setup Node (build/test)
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: "22"
           cache: "npm"
           cache-dependency-path: package-lock.json
 
       - name: Install
         run: npm ci
 
+      - name: Build
+        run: npm run build
+
       - name: Test
         run: npm test
 
@@ -68,33 +77,55 @@ jobs:
         with:
           tag_name: ${{ env.RELEASE_TAG }}
           files: ${{ steps.pack.outputs.tarball }}
+          generate_release_notes: true
 
       - name: Setup Node (GitHub Packages)
-        if: ${{ env.RELEASE_TAG != '' }}
+        if: ${{ env.RELEASE_TAG != '' && inputs.npm_only != true }}
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: "22"
           registry-url: "https://npm.pkg.github.com"
           scope: "@${{ github.repository_owner }}"
 
-      - name: Publish to GitHub Packages (npm.pkg.github.com)
-        if: ${{ env.RELEASE_TAG != '' }}
+      - name: Publish to GitHub Packages
+        if: ${{ env.RELEASE_TAG != '' && inputs.npm_only != true }}
         run: |
           npm pkg set name="@${{ github.repository_owner }}/git-ai"
           npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Restore package name for npmjs
+        if: ${{ env.RELEASE_TAG != '' }}
+        run: |
+          npm pkg set name="git-ai"
+
       - name: Setup Node (npmjs.org)
         if: ${{ env.RELEASE_TAG != '' }}
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: "22"
           registry-url: "https://registry.npmjs.org"
 
-      - name: Publish to npmjs.org (optional)
+      - name: Publish to npmjs.org
+        if: ${{ env.RELEASE_TAG != '' }}
+        run: |
+          npm publish --access public --provenance
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        if: ${{ env.RELEASE_TAG != '' && env.NODE_AUTH_TOKEN != '' }}
+
+      - name: Publish Summary
+        if: ${{ env.RELEASE_TAG != '' }}
         run: |
-          npm publish --access public
+          echo "## Release Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** ${{ env.RELEASE_TAG }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Published to:" >> $GITHUB_STEP_SUMMARY
+          echo "- [x] GitHub Packages: \`@${{ github.repository_owner }}/git-ai\`" >> $GITHUB_STEP_SUMMARY
+          echo "- [x] npmjs.org: \`git-ai\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Install:" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "npm install -g git-ai" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
diff --git a/README.md b/README.md
index b3e99f4..83616f6 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="docs/logo.png" alt="git-ai logo" width="200"/>
+</p>
+
 # git-ai
 
 [![ci](https://github.com/mars167/git-ai-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/mars167/git-ai-cli/actions/workflows/ci.yml)
diff --git a/docs/logo.png b/docs/logo.png
new file mode 100644
index 0000000..c9d36d9
Binary files /dev/null and b/docs/logo.png differ
diff --git a/install.sh b/install.sh
new file mode 100755
index 0000000..92b7c5d
--- /dev/null
+++ b/install.sh
@@ -0,0 +1,183 @@
+#!/bin/bash
+#
+# git-ai Quick Install Script
+# 
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/mars167/git-ai-cli/main/install.sh | bash
+#
+# Or with options:
+#   curl -fsSL https://raw.githubusercontent.com/mars167/git-ai-cli/main/install.sh | bash -s -- --with-skill
+#
+# This script installs:
+#   1. git-ai CLI tool (via npm)
+#   2. Optionally: git-ai-mcp skill for AI agents
+#
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+BOLD='\033[1m'
+
+# Banner
+print_banner() {
+    echo -e "${CYAN}"
+    echo '   ____   _   _             _    ___ '
+    echo '  / ___| (_) | |_          / \  |_ _|'
+    echo ' | |  _  | | | __|  ___   / _ \  | | '
+    echo ' | |_| | | | | |_  |___| / ___ \ | | '
+    echo '  \____| |_|  \__|      /_/   \_\___|'
+    echo -e "${NC}"
+    echo -e "${BOLD}Semantic Code Understanding for AI Agents${NC}"
+    echo ""
+}
+
+# Logging functions
+info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+success() {
+    echo -e "${GREEN}[OK]${NC} $1"
+}
+
+warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+    exit 1
+}
+
+# Check if command exists
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Parse arguments
+INSTALL_SKILL=false
+GLOBAL_INSTALL=true
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --with-skill|-s)
+            INSTALL_SKILL=true
+            shift
+            ;;
+        --local|-l)
+            GLOBAL_INSTALL=false
+            shift
+            ;;
+        --help|-h)
+            echo "Usage: install.sh [OPTIONS]"
+            echo ""
+            echo "Options:"
+            echo "  --with-skill, -s    Also install git-ai-mcp skill for AI agents"
+            echo "  --local, -l         Install locally instead of globally"
+            echo "  --help, -h          Show this help message"
+            exit 0
+            ;;
+        *)
+            warn "Unknown option: $1"
+            shift
+            ;;
+    esac
+done
+
+# Main installation
+main() {
+    print_banner
+    
+    # Check prerequisites
+    info "Checking prerequisites..."
+    
+    if ! command_exists node; then
+        error "Node.js is required but not installed. Please install Node.js 18+ first."
+    fi
+    
+    NODE_VERSION=$(node -v | cut -d'v' -f2 | cut -d'.' -f1)
+    if [ "$NODE_VERSION" -lt 18 ]; then
+        error "Node.js 18+ is required. Current version: $(node -v)"
+    fi
+    success "Node.js $(node -v) detected"
+    
+    if ! command_exists npm; then
+        error "npm is required but not installed."
+    fi
+    success "npm $(npm -v) detected"
+    
+    # Install git-ai
+    info "Installing git-ai CLI..."
+    
+    if [ "$GLOBAL_INSTALL" = true ]; then
+        npm install -g git-ai
+        success "git-ai installed globally"
+    else
+        npm install git-ai
+        success "git-ai installed locally"
+    fi
+    
+    # Verify installation
+    if command_exists git-ai; then
+        success "git-ai $(git-ai --version 2>/dev/null || echo 'installed')"
+    else
+        warn "git-ai command not found in PATH. You may need to restart your terminal."
+    fi
+    
+    # Install skill if requested
+    if [ "$INSTALL_SKILL" = true ]; then
+        info "Installing git-ai-mcp skill..."
+        
+        if ! command_exists npx; then
+            warn "npx not found. Skipping skill installation."
+        else
+            # Check if skills CLI is available
+            if npx skills --version >/dev/null 2>&1; then
+                npx skills add mars167/git-ai-cli@git-ai-mcp -g -y
+                success "git-ai-mcp skill installed"
+            else
+                info "Installing skills CLI..."
+                npx skills add mars167/git-ai-cli@git-ai-mcp -g -y
+                success "git-ai-mcp skill installed"
+            fi
+        fi
+    fi
+    
+    # Print next steps
+    echo ""
+    echo -e "${GREEN}${BOLD}Installation Complete!${NC}"
+    echo ""
+    echo -e "${BOLD}Quick Start:${NC}"
+    echo ""
+    echo "  1. Initialize index in your project:"
+    echo -e "     ${CYAN}cd your-project${NC}"
+    echo -e "     ${CYAN}git-ai ai index --overwrite${NC}"
+    echo ""
+    echo "  2. Search code semantically:"
+    echo -e "     ${CYAN}git-ai ai semantic \"user authentication\"${NC}"
+    echo ""
+    echo "  3. Analyze call graphs:"
+    echo -e "     ${CYAN}git-ai ai graph callers functionName${NC}"
+    echo ""
+    
+    if [ "$INSTALL_SKILL" = false ]; then
+        echo -e "${BOLD}For AI Agent Integration:${NC}"
+        echo ""
+        echo "  Install the MCP skill for Claude/Cursor/etc:"
+        echo -e "     ${CYAN}curl -fsSL https://raw.githubusercontent.com/mars167/git-ai-cli/main/install.sh | bash -s -- --with-skill${NC}"
+        echo ""
+    fi
+    
+    echo -e "${BOLD}Documentation:${NC}"
+    echo "  https://github.com/mars167/git-ai-cli"
+    echo ""
+}
+
+# Run main
+main
diff --git a/package.json b/package.json
index ebf2de7..52e765c 100644
--- a/package.json
+++ b/package.json
@@ -19,9 +19,23 @@
     "docs/**",
     "assets/**",
     "templates/**",
+    "skills/**",
+    "install.sh",
     "README.md"
   ],
-  "keywords": [],
+  "keywords": [
+    "git",
+    "ai",
+    "semantic-search",
+    "mcp",
+    "code-search",
+    "code-understanding",
+    "vector-search",
+    "graph-database",
+    "cli",
+    "code-indexing",
+    "knowledge-graph"
+  ],
   "author": "mars167",
   "license": "MIT",
   "description": "A git-compatible CLI with AI indexing/search and an MCP server.",
@@ -36,6 +50,15 @@
   "engines": {
     "node": ">=18"
   },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/mars167"
+  },
   "dependencies": {
     "@lancedb/lancedb": "0.22.3",
     "@modelcontextprotocol/sdk": "^1.25.2",
diff --git a/skills/git-ai-mcp/SKILL.md b/skills/git-ai-mcp/SKILL.md
new file mode 100644
index 0000000..96efa26
--- /dev/null
+++ b/skills/git-ai-mcp/SKILL.md
@@ -0,0 +1,86 @@
+---
+name: git-ai-mcp
+description: |
+  Efficient codebase understanding and navigation using git-ai MCP tools. Use when working with code repositories that have git-ai indexed, including: (1) Understanding project structure and architecture, (2) Searching for symbols, functions, or semantic concepts, (3) Analyzing code relationships and call graphs, (4) Tracking symbol evolution and change history via DSR, (5) Reading and navigating code files. Triggers: "understand this project", "find function X", "who calls X", "what does X call", "history of X", "where is X implemented".
+---
+
+# git-ai MCP Skill
+
+Guide for using git-ai MCP tools to understand and navigate codebases efficiently.
+
+## Overview
+
+git-ai provides semantic code understanding through:
+
+- **Hyper RAG**: Vector + Graph + DSR retrieval
+- **AST Analysis**: Symbol relationships and call graphs
+- **DSR**: Deterministic Semantic Records for change tracking
+
+## Workflow
+
+Understanding a codebase involves these steps:
+
+1. Get global view (run `repo_map`)
+2. Check index status (run `check_index`, rebuild if needed)
+3. Locate code (run `search_symbols` or `semantic_search`)
+4. Analyze relationships (run `ast_graph_callers/callees/chain`)
+5. Trace history (run `dsr_symbol_evolution`)
+6. Read code (run `read_file`)
+
+## Tool Selection
+
+| Task | Tool | Key Parameters |
+|------|------|----------------|
+| Project overview | `repo_map` | `path`, `max_files: 20` |
+| Find by name | `search_symbols` | `path`, `query`, `mode: substring` |
+| Find by meaning | `semantic_search` | `path`, `query`, `topk: 10` |
+| Who calls X | `ast_graph_callers` | `path`, `name` |
+| What X calls | `ast_graph_callees` | `path`, `name` |
+| Call chain | `ast_graph_chain` | `path`, `name`, `direction`, `max_depth` |
+| Symbol history | `dsr_symbol_evolution` | `path`, `symbol`, `limit` |
+| Read code | `read_file` | `path`, `file`, `start_line`, `end_line` |
+| Index health | `check_index` | `path` |
+| Rebuild index | `rebuild_index` | `path` |
+
+## Critical Rules
+
+**MUST follow:**
+
+1. **Always pass `path` explicitly** - Never rely on implicit working directory
+2. **Check index before search** - Run `check_index` before using search/graph tools
+3. **Read before modify** - Use `read_file` to understand code before making changes
+4. **Use DSR for history** - Never manually parse git log; use `dsr_symbol_evolution`
+
+**NEVER do:**
+
+- Assume symbol locations without searching
+- Modify files without reading them first
+- Search when index is missing or incompatible
+- Ignore DSR risk levels (high risk = extra review needed)
+
+## Examples
+
+**Find authentication code:**
+```js
+semantic_search({ path: "/repo", query: "user authentication logic", topk: 10 })
+```
+
+**Find who calls a function:**
+```js
+ast_graph_callers({ path: "/repo", name: "handleRequest", limit: 50 })
+```
+
+**Trace call chain upstream:**
+```js
+ast_graph_chain({ path: "/repo", name: "processOrder", direction: "upstream", max_depth: 3 })
+```
+
+**View symbol history:**
+```js
+dsr_symbol_evolution({ path: "/repo", symbol: "authenticateUser", limit: 50 })
+```
+
+## References
+
+- **Tool details**: See [references/tools.md](references/tools.md) for complete tool documentation
+- **Constraints**: See [references/constraints.md](references/constraints.md) for behavioral rules
diff --git a/skills/git-ai-mcp/references/constraints.md b/skills/git-ai-mcp/references/constraints.md
new file mode 100644
index 0000000..3f49663
--- /dev/null
+++ b/skills/git-ai-mcp/references/constraints.md
@@ -0,0 +1,143 @@
+# git-ai MCP Behavioral Constraints
+
+Rules and constraints for using git-ai MCP tools effectively and safely.
+
+## Must-Follow Rules (Error Level)
+
+### 1. explicit_path
+
+**Rule:** Every MCP tool call MUST include an explicit `path` parameter.
+
+**Why:** Ensures atomic, reproducible calls. Never rely on process state or working directory.
+
+**Good:**
+```js
+search_symbols({ path: "/abs/path/to/repo", query: "handleRequest" })
+```
+
+**Bad:**
+```js
+search_symbols({ query: "handleRequest" })  // Missing path!
+```
+
+### 2. check_index_first
+
+**Rule:** Before using `search_symbols`, `semantic_search`, or any `ast_graph_*` tool, MUST call `check_index` to verify index is ready.
+
+**Why:** These tools depend on the index. Searching with a missing/incompatible index gives unreliable results.
+
+**Workflow:**
+```js
+// Step 1: Check index
+const status = check_index({ path: "/repo" })
+
+// Step 2: Rebuild if needed
+if (!status.compatible) {
+  rebuild_index({ path: "/repo" })
+}
+
+// Step 3: Now safe to search
+search_symbols({ path: "/repo", query: "..." })
+```
+
+### 3. understand_before_modify
+
+**Rule:** Before modifying any file, MUST:
+1. Use `search_symbols` to locate the code
+2. Use `read_file` to understand the implementation
+3. Use `ast_graph_callers` to assess impact
+4. Only then make changes
+
+**Why:** Prevents breaking changes and ensures informed modifications.
+
+### 4. use_dsr_for_history
+
+**Rule:** When tracing symbol history, MUST use `dsr_symbol_evolution`. NEVER manually parse git log or diff.
+
+**Why:** DSR provides structured, semantic change information that raw git commands don't.
+
+## Warning-Level Rules
+
+### 5. repo_map_before_large_change
+
+**Rule:** Before large refactoring or architectural changes, use `repo_map` to understand project structure.
+
+**Why:** Provides context for planning changes and identifying affected areas.
+
+### 6. respect_dsr_risk
+
+**Rule:** When DSR reports `risk_level: high`, exercise extra caution. Operations like `delete` and `rename` require additional review.
+
+**Risk levels:**
+- `low`: Safe, routine changes
+- `medium`: Review recommended
+- `high`: Extra scrutiny required
+
+## Recommended Practices
+
+### prefer_semantic_search
+
+For understanding functional intent, prefer `semantic_search` over `search_symbols`.
+
+**Use `semantic_search` when:**
+- Looking for conceptual functionality
+- Query is in natural language
+- Exact name is unknown
+
+**Use `search_symbols` when:**
+- Exact or partial name is known
+- Looking for specific identifiers
+
+### use_call_chain_for_complex_flow
+
+For complex flows spanning multiple functions, use `ast_graph_chain` instead of manually chaining `callers`/`callees` calls.
+
+```js
+// Good: Single call for complete chain
+ast_graph_chain({ path: "/repo", name: "processPayment", direction: "upstream", max_depth: 5 })
+
+// Avoid: Manual recursive calls
+ast_graph_callers({ path: "/repo", name: "processPayment" })
+// then for each result...
+ast_graph_callers({ path: "/repo", name: result.name })
+// etc.
+```
+
+### incremental_dsr_generation
+
+Generate DSR on-demand for specific commits rather than batch-generating for entire history.
+
+```js
+// Good: Generate for specific commit when needed
+dsr_generate({ path: "/repo", commit: "abc123" })
+
+// Avoid: Generating for all historical commits upfront
+```
+
+## Prohibited Actions
+
+| Action | Reason |
+|--------|--------|
+| Assume symbol location without searching | Always confirm via search |
+| Modify unread files | Must read and understand first |
+| Manual git log parsing for history | Use DSR tools instead |
+| Search with missing index | Rebuild index first |
+| Ignore high risk DSR warnings | Requires extra review |
+| Omit `path` parameter | Every call must be explicit |
+
+## Tool-Specific Constraints
+
+| Tool | Precondition | Required Params |
+|------|--------------|-----------------|
+| `repo_map` | None | `path` |
+| `check_index` | None | `path` |
+| `rebuild_index` | None | `path` |
+| `search_symbols` | `check_index` passed | `path`, `query` |
+| `semantic_search` | `check_index` passed | `path`, `query` |
+| `ast_graph_callers` | `check_index` passed | `path`, `name` |
+| `ast_graph_callees` | `check_index` passed | `path`, `name` |
+| `ast_graph_chain` | `check_index` passed | `path`, `name` |
+| `dsr_context` | None | `path` |
+| `dsr_generate` | None | `path`, `commit` |
+| `dsr_symbol_evolution` | DSR exists for commits | `path`, `symbol` |
+| `read_file` | None | `path`, `file` |
diff --git a/skills/git-ai-mcp/references/tools.md b/skills/git-ai-mcp/references/tools.md
new file mode 100644
index 0000000..42106ae
--- /dev/null
+++ b/skills/git-ai-mcp/references/tools.md
@@ -0,0 +1,263 @@
+# git-ai MCP Tools Reference
+
+Complete documentation for all git-ai MCP tools.
+
+## Index Management
+
+### check_index
+
+Check if repository index is ready and compatible.
+
+```js
+check_index({ path: "/abs/path/to/repo" })
+```
+
+**Returns:** Index status, compatibility info, and recommendations.
+
+**When to use:** Before any search or graph operation.
+
+### rebuild_index
+
+Rebuild the repository index from scratch.
+
+```js
+rebuild_index({ path: "/abs/path/to/repo" })
+```
+
+**Parameters:**
+- `path` (required): Absolute path to repository root
+- `overwrite` (optional): Whether to overwrite existing index (default: true)
+- `dim` (optional): Vector dimension (default: 256)
+
+**Note:** Can be slow for large repositories. Use when index is missing or incompatible.
+
+### pack_index / unpack_index
+
+Package index for storage or distribution.
+
+```js
+pack_index({ path: "/repo", lfs: true })  // Pack with LFS tracking
+unpack_index({ path: "/repo" })            // Restore from archive
+```
+
+## Search Tools
+
+### repo_map
+
+Get a high-level overview of repository structure.
+
+```js
+repo_map({
+  path: "/abs/path/to/repo",
+  max_files: 20,      // Top files by importance
+  max_symbols: 5      // Top symbols per file
+})
+```
+
+**When to use:** First contact with a repository, before large changes.
+
+### search_symbols
+
+Search for symbols by name pattern.
+
+```js
+search_symbols({
+  path: "/repo",
+  query: "handleRequest",
+  mode: "substring",   // substring | prefix | wildcard | regex | fuzzy
+  limit: 50,
+  case_insensitive: false
+})
+```
+
+**Modes:**
+- `substring`: Match anywhere in name (default)
+- `prefix`: Match start of name
+- `wildcard`: Use `*` and `?` wildcards
+- `regex`: Full regex support
+- `fuzzy`: Typo-tolerant matching
+
+### semantic_search
+
+Search code by meaning using vector similarity.
+
+```js
+semantic_search({
+  path: "/repo",
+  query: "user authentication and session management",
+  topk: 10,
+  lang: "auto"  // auto | all | java | ts
+})
+```
+
+**When to use:** Understanding functional intent, finding conceptually related code.
+
+## AST Graph Tools
+
+### ast_graph_find
+
+Find symbols by name prefix in the AST graph.
+
+```js
+ast_graph_find({
+  path: "/repo",
+  prefix: "handle",
+  limit: 50
+})
+```
+
+### ast_graph_callers
+
+Find all functions that call a given function.
+
+```js
+ast_graph_callers({
+  path: "/repo",
+  name: "authenticateUser",
+  limit: 200
+})
+```
+
+**When to use:** Impact analysis before refactoring, understanding usage patterns.
+
+### ast_graph_callees
+
+Find all functions called by a given function.
+
+```js
+ast_graph_callees({
+  path: "/repo",
+  name: "processOrder",
+  limit: 200
+})
+```
+
+**When to use:** Understanding implementation details, dependency analysis.
+
+### ast_graph_chain
+
+Trace complete call chain in either direction.
+
+```js
+ast_graph_chain({
+  path: "/repo",
+  name: "handlePayment",
+  direction: "downstream",  // downstream | upstream
+  max_depth: 3,
+  limit: 500
+})
+```
+
+**Directions:**
+- `downstream`: What does this function call? (implementation details)
+- `upstream`: Who calls this function? (usage/impact)
+
+**When to use:** Complex flow analysis, understanding system architecture.
+
+### ast_graph_children
+
+List direct children in AST containment (file → symbols, class → methods).
+
+```js
+ast_graph_children({
+  path: "/repo",
+  id: "src/auth/service.ts",
+  as_file: true  // Treat id as file path
+})
+```
+
+### ast_graph_refs
+
+Find all references to a name (calls, new expressions, type references).
+
+```js
+ast_graph_refs({
+  path: "/repo",
+  name: "UserService",
+  limit: 200
+})
+```
+
+## DSR Tools (Deterministic Semantic Records)
+
+### dsr_context
+
+Get repository Git context and DSR directory state.
+
+```js
+dsr_context({ path: "/repo" })
+```
+
+**Returns:** Branch info, commit status, DSR availability.
+
+### dsr_generate
+
+Generate DSR for a specific commit.
+
+```js
+dsr_generate({
+  path: "/repo",
+  commit: "HEAD"  // or specific commit hash
+})
+```
+
+**When to use:** Before querying history for commits without DSR.
+
+### dsr_symbol_evolution
+
+Track how a symbol changed over time.
+
+```js
+dsr_symbol_evolution({
+  path: "/repo",
+  symbol: "authenticateUser",
+  limit: 50,
+  contains: false,  // true for substring match
+  all: false        // true to traverse all refs, not just HEAD
+})
+```
+
+**Returns:** List of changes with:
+- `commit`: Commit hash
+- `operation`: add | modify | delete | rename
+- `risk_level`: low | medium | high
+- `details`: Change description
+
+**When to use:** Understanding design evolution, finding when/why something changed.
+
+### dsr_rebuild_index
+
+Rebuild DSR index from DSR files.
+
+```js
+dsr_rebuild_index({ path: "/repo" })
+```
+
+## File Operations
+
+### read_file
+
+Read file content with optional line range.
+
+```js
+read_file({
+  path: "/repo",
+  file: "src/auth/service.ts",  // Relative to repo root
+  start_line: 1,
+  end_line: 200
+})
+```
+
+**Best practice:** Use with `start_line`/`end_line` for large files.
+
+### list_files
+
+List repository files by glob pattern.
+
+```js
+list_files({
+  path: "/repo",
+  pattern: "src/**/*.ts",
+  limit: 500
+})
+```
diff --git a/templates/agents/common/rules/git-ai-mcp/RULE.md b/templates/agents/common/rules/git-ai-mcp/RULE.md
deleted file mode 100644
index 60ba5c8..0000000
--- a/templates/agents/common/rules/git-ai-mcp/RULE.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# git-ai-mcp Rule
-
-Agent 使用 git-ai MCP 工具的行为约束。
-
-## 必须遵守
-
-### explicit_path
-- **级别**: error
-- **规则**: 每次 MCP 工具调用必须显式传 `path` 参数。禁止依赖进程状态或工作目录隐式推断仓库位置。
-
-### check_index_first
-- **级别**: error
-- **规则**: 使用 `search_symbols`、`semantic_search`、`ast_graph_*` 前，必须先调用 `check_index` 确认索引就绪。索引不兼容时必须重建，禁止在索引缺失时进行符号搜索。
-
-### doc_index_scope
-- **级别**: warning
-- **规则**: 文档与规则模板已纳入索引（Markdown/YAML）。涉及 MCP、Skill、Rule 等问题时，优先使用 `semantic_search` 检索相关文档，再给出结论。
-
-### understand_before_modify
-- **级别**: error
-- **规则**: 修改代码前必须先理解现有实现。流程：`search_symbols` 定位 → `read_file` 精读 → `ast_graph_callers` 确认影响范围 → 修改。禁止直接修改未读过的文件。
-
-### use_dsr_for_history
-- **级别**: warning
-- **规则**: 追溯符号变更历史必须使用 `dsr_symbol_evolution`。禁止手动解析 git log 或 diff 来推断符号变更。
-
-### repo_map_before_large_change
-- **级别**: warning
-- **规则**: 大型变更前必须使用 `repo_map` 确认影响范围。了解项目结构、关键文件、主要符号后再规划修改。
-
-### respect_dsr_risk
-- **级别**: warning
-- **规则**: DSR 报告 `risk_level` 为 `high` 的变更必须谨慎对待。涉及 `delete`、`rename` 操作的变更需要额外审查。
-
-## 推荐策略
-
-- **优先语义搜索**: 理解功能意图时优先使用 `semantic_search`，精确定位时使用 `search_symbols`。
-- **使用调用链**: 复杂调用链路使用 `ast_graph_chain` 追踪，避免手动递归查找 callers/callees。
-- **按需生成 DSR**: 需要历史分析时，按需生成 DSR，避免一次性生成所有历史提交的 DSR。
-- **附带上下文**: 复杂查询可附带 `repo_map`，帮助建立全局上下文。
-
-## 禁止事项
-
-| 行为 | 原因 |
-|------|------|
-| 假设符号位置而不搜索 | 必须通过 `search_symbols` 或 `semantic_search` 确认符号位置 |
-| 直接修改未读过的文件 | 必须先 `read_file` 理解实现，避免破坏性变更 |
-| 手动解析 git 历史 | 必须使用 `dsr_symbol_evolution` 追溯符号变更 |
-| 在索引缺失时进行符号搜索 | 索引是符号搜索的前提，缺失时必须重建 |
-| 忽略 DSR 风险等级 | high 风险变更需要额外审查，不能盲目应用 |
-| 省略 `path` 参数 | 每次调用必须显式传 path，保证原子性和可复现性 |
-
-## 工具使用约束
-
-| 工具 | 使用时机 | 必传参数 | 前置检查 |
-|------|----------|----------|----------|
-| `repo_map` | 首次接触仓库、大型变更前 | `path` | - |
-| `check_index` | 任何符号搜索前 | `path` | - |
-| `rebuild_index` | 索引不兼容或缺失时 | `path` | - |
-| `search_symbols` | 按名称查找符号 | `path`, `query` | `check_index` 通过 |
-| `semantic_search` | 按语义查找代码 | `path`, `query` | `check_index` 通过 |
-| `ast_graph_callers` | 查找调用者 | `path`, `name` | `check_index` 通过 |
-| `ast_graph_callees` | 查找被调用者 | `path`, `name` | `check_index` 通过 |
-| `ast_graph_chain` | 追踪调用链 | `path`, `name` | `check_index` 通过 |
-| `dsr_context` | 了解仓库 Git 状态和 DSR 情况 | `path` | - |
-| `dsr_generate` | 为特定提交生成 DSR | `path`, `commit` | - |
-| `dsr_symbol_evolution` | 追溯符号变更历史 | `path`, `symbol` | 相关 DSR 已生成 |
-| `read_file` | 精读代码 | `path`, `file` | - |
diff --git a/templates/agents/common/rules/git-ai.yaml b/templates/agents/common/rules/git-ai.yaml
deleted file mode 100644
index 83b1661..0000000
--- a/templates/agents/common/rules/git-ai.yaml
+++ /dev/null
@@ -1,141 +0,0 @@
-name: git-ai-mcp
-version: "2.0.0"
-description: |
-  Agent 使用 git-ai MCP 工具的行为约束。
-  确保 Agent 高效、安全、准确地帮助开发者理解和修改代码。
-
-must_follow:
-  - id: explicit_path
-    severity: error
-    rule: |
-      每次 MCP 工具调用必须显式传 path 参数。
-      禁止依赖进程状态或工作目录隐式推断仓库位置。
-
-  - id: check_index_first
-    severity: error
-    rule: |
-      使用 search_symbols、semantic_search、ast_graph_* 前，
-      必须先调用 check_index 确认索引就绪。
-      索引不兼容时必须重建，禁止在索引缺失时进行符号搜索。
-
-  - id: understand_before_modify
-    severity: error
-    rule: |
-      修改代码前必须先理解现有实现。
-      流程：search_symbols 定位 → read_file 精读 → ast_graph_callers 确认影响范围 → 修改。
-      禁止直接修改未读过的文件。
-
-  - id: use_dsr_for_history
-    severity: warning
-    rule: |
-      追溯符号变更历史必须使用 dsr_symbol_evolution。
-      禁止手动解析 git log 或 diff 来推断符号变更。
-
-  - id: repo_map_before_large_change
-    severity: warning
-    rule: |
-      大型变更前必须使用 repo_map 确认影响范围。
-      了解项目结构、关键文件、主要符号后再规划修改。
-
-  - id: respect_dsr_risk
-    severity: warning
-    rule: |
-      DSR 报告 risk_level 为 high 的变更必须谨慎对待。
-      涉及 delete、rename 操作的变更需要额外审查。
-
-recommended:
-  - id: prefer_semantic_search
-    rule: |
-      理解功能意图时优先使用 semantic_search，
-      精确定位时使用 search_symbols。
-
-  - id: use_call_chain_for_complex_flow
-    rule: |
-      复杂调用链路使用 ast_graph_chain 追踪，
-      避免手动递归查找 callers/callees。
-
-  - id: incremental_dsr_generation
-    rule: |
-      需要历史分析时，按需生成 DSR，
-      避免一次性生成所有历史提交的 DSR。
-
-  - id: attach_repo_map_for_context
-    rule: |
-      复杂查询可附带 repo_map，
-      帮助建立全局上下文。
-
-prohibited:
-  - action: "假设符号位置而不搜索"
-    reason: "必须通过 search_symbols 或 semantic_search 确认符号位置"
-
-  - action: "直接修改未读过的文件"
-    reason: "必须先 read_file 理解实现，避免破坏性变更"
-
-  - action: "手动解析 git 历史"
-    reason: "必须使用 dsr_symbol_evolution 追溯符号变更"
-
-  - action: "在索引缺失时进行符号搜索"
-    reason: "索引是符号搜索的前提，缺失时必须重建"
-
-  - action: "忽略 DSR 风险等级"
-    reason: "high 风险变更需要额外审查，不能盲目应用"
-
-  - action: "省略 path 参数"
-    reason: "每次调用必须显式传 path，保证原子性和可复现性"
-
-tool_usage_constraints:
-  repo_map:
-    when: "首次接触仓库、大型变更前"
-    must_pass: ["path"]
-
-  check_index:
-    when: "任何符号搜索前"
-    must_pass: ["path"]
-
-  rebuild_index:
-    when: "索引不兼容或缺失时"
-    must_pass: ["path"]
-    note: "可能耗时较长，大型仓库谨慎使用"
-
-  search_symbols:
-    when: "按名称查找符号"
-    must_pass: ["path", "query"]
-    precheck: "check_index 必须通过"
-
-  semantic_search:
-    when: "按语义查找代码"
-    must_pass: ["path", "query"]
-    precheck: "check_index 必须通过"
-
-  ast_graph_callers:
-    when: "查找调用者"
-    must_pass: ["path", "name"]
-    precheck: "check_index 必须通过"
-
-  ast_graph_callees:
-    when: "查找被调用者"
-    must_pass: ["path", "name"]
-    precheck: "check_index 必须通过"
-
-  ast_graph_chain:
-    when: "追踪调用链"
-    must_pass: ["path", "name"]
-    precheck: "check_index 必须通过"
-
-  dsr_context:
-    when: "了解仓库 Git 状态和 DSR 情况"
-    must_pass: ["path"]
-
-  dsr_generate:
-    when: "为特定提交生成 DSR"
-    must_pass: ["path", "commit"]
-
-  dsr_symbol_evolution:
-    when: "追溯符号变更历史"
-    must_pass: ["path", "symbol"]
-    precheck: "相关提交的 DSR 必须已生成"
-
-  read_file:
-    when: "精读代码"
-    must_pass: ["path", "file"]
-    note: "建议结合 start_line/end_line 限制范围"
diff --git a/templates/agents/common/skills/git-ai-mcp/SKILL.md b/templates/agents/common/skills/git-ai-mcp/SKILL.md
index 25a0096..96efa26 100644
--- a/templates/agents/common/skills/git-ai-mcp/SKILL.md
+++ b/templates/agents/common/skills/git-ai-mcp/SKILL.md
@@ -1,143 +1,86 @@
-# git-ai-mcp Skill
+---
+name: git-ai-mcp
+description: |
+  Efficient codebase understanding and navigation using git-ai MCP tools. Use when working with code repositories that have git-ai indexed, including: (1) Understanding project structure and architecture, (2) Searching for symbols, functions, or semantic concepts, (3) Analyzing code relationships and call graphs, (4) Tracking symbol evolution and change history via DSR, (5) Reading and navigating code files. Triggers: "understand this project", "find function X", "who calls X", "what does X call", "history of X", "where is X implemented".
+---
 
-指导 Agent 使用 git-ai MCP 工具高效理解和操作代码库。
+# git-ai MCP Skill
 
-## 目标用户
+Guide for using git-ai MCP tools to understand and navigate codebases efficiently.
 
-使用 Claude Desktop、Trae 等支持 MCP 的本地 Code Agent 的开发者。
+## Overview
 
-## 核心能力
+git-ai provides semantic code understanding through:
 
-1. **仓库全局理解** - 通过 `repo_map` 快速获取项目结构和关键文件概览
-2. **符号检索** - 使用 `search_symbols` 和 `semantic_search` 定位代码
-3. **代码关系分析** - 通过 `ast_graph_callers/callees/chain` 理解调用关系
-4. **变更历史追溯** - 使用 `dsr_symbol_evolution` 追踪符号演变
-5. **代码精读** - 使用 `read_file` 深入理解关键代码片段
-6. **索引管理** - 按需重建索引，确保检索准确性
-7. **文档/规则检索** - 索引 Markdown/YAML 文档（含 skills/rules 模板）并支持语义检索
+- **Hyper RAG**: Vector + Graph + DSR retrieval
+- **AST Analysis**: Symbol relationships and call graphs
+- **DSR**: Deterministic Semantic Records for change tracking
 
-## 推荐工作流
+## Workflow
 
-### 1. 首次接触仓库
+Understanding a codebase involves these steps:
 
-获取全局视图，了解项目结构：
+1. Get global view (run `repo_map`)
+2. Check index status (run `check_index`, rebuild if needed)
+3. Locate code (run `search_symbols` or `semantic_search`)
+4. Analyze relationships (run `ast_graph_callers/callees/chain`)
+5. Trace history (run `dsr_symbol_evolution`)
+6. Read code (run `read_file`)
 
-```js
-repo_map({ path: "/ABS/PATH/TO/REPO", max_files: 20, max_symbols: 5 })
-```
-
-### 2. 检查索引状态
-
-确保索引就绪，否则重建：
-
-```js
-check_index({ path: "/ABS/PATH/TO/REPO" })
-// 如果不兼容，重建：
-rebuild_index({ path: "/ABS/PATH/TO/REPO" })
-```
-
-### 3. 定位目标代码
-
-按名称查找：
+## Tool Selection
 
-```js
-search_symbols({ path: "/ABS/PATH/TO/REPO", query: "handleRequest", mode: "substring", limit: 20 })
-```
-
-按语义查找：
-
-```js
-semantic_search({ path: "/ABS/PATH/TO/REPO", query: "用户认证逻辑在哪里", topk: 10 })
-```
-
-查找文档/规则说明：
-
-```js
-semantic_search({ path: "/ABS/PATH/TO/REPO", query: "MCP 规则约束", topk: 10, lang: "markdown" })
-```
+| Task | Tool | Key Parameters |
+|------|------|----------------|
+| Project overview | `repo_map` | `path`, `max_files: 20` |
+| Find by name | `search_symbols` | `path`, `query`, `mode: substring` |
+| Find by meaning | `semantic_search` | `path`, `query`, `topk: 10` |
+| Who calls X | `ast_graph_callers` | `path`, `name` |
+| What X calls | `ast_graph_callees` | `path`, `name` |
+| Call chain | `ast_graph_chain` | `path`, `name`, `direction`, `max_depth` |
+| Symbol history | `dsr_symbol_evolution` | `path`, `symbol`, `limit` |
+| Read code | `read_file` | `path`, `file`, `start_line`, `end_line` |
+| Index health | `check_index` | `path` |
+| Rebuild index | `rebuild_index` | `path` |
 
-### 4. 理解代码关系
+## Critical Rules
 
-查找调用者：
+**MUST follow:**
 
-```js
-ast_graph_callers({ path: "/ABS/PATH/TO/REPO", name: "handleRequest", limit: 50 })
-```
+1. **Always pass `path` explicitly** - Never rely on implicit working directory
+2. **Check index before search** - Run `check_index` before using search/graph tools
+3. **Read before modify** - Use `read_file` to understand code before making changes
+4. **Use DSR for history** - Never manually parse git log; use `dsr_symbol_evolution`
 
-查找被调用者：
+**NEVER do:**
 
-```js
-ast_graph_callees({ path: "/ABS/PATH/TO/REPO", name: "handleRequest", limit: 50 })
-```
+- Assume symbol locations without searching
+- Modify files without reading them first
+- Search when index is missing or incompatible
+- Ignore DSR risk levels (high risk = extra review needed)
 
-追踪调用链：
+## Examples
 
+**Find authentication code:**
 ```js
-ast_graph_chain({ path: "/ABS/PATH/TO/REPO", name: "handleRequest", direction: "upstream", max_depth: 3 })
+semantic_search({ path: "/repo", query: "user authentication logic", topk: 10 })
 ```
 
-### 5. 追溯变更历史
-
-查看符号的历史变更：
-
+**Find who calls a function:**
 ```js
-dsr_symbol_evolution({ path: "/ABS/PATH/TO/REPO", symbol: "handleRequest", limit: 50 })
+ast_graph_callers({ path: "/repo", name: "handleRequest", limit: 50 })
 ```
 
-模糊匹配：
-
+**Trace call chain upstream:**
 ```js
-dsr_symbol_evolution({ path: "/ABS/PATH/TO/REPO", symbol: "Request", contains: true, limit: 100 })
+ast_graph_chain({ path: "/repo", name: "processOrder", direction: "upstream", max_depth: 3 })
 ```
 
-### 6. 精读代码
-
+**View symbol history:**
 ```js
-read_file({ path: "/ABS/PATH/TO/REPO", file: "src/auth.ts", start_line: 1, end_line: 100 })
+dsr_symbol_evolution({ path: "/repo", symbol: "authenticateUser", limit: 50 })
 ```
 
-### 7. 提供建议
-
-基于完整的代码理解，提供修改建议或生成代码。
-
-## 工具选择指南
-
-| 场景 | 工具 | 关键参数 |
-|------|------|----------|
-| 了解项目结构 | `repo_map` | `path`, `max_files`, `max_symbols` |
-| 按名称查找符号 | `search_symbols` | `path`, `query`, `mode`, `limit` |
-| 按语义查找代码 | `semantic_search` | `path`, `query`, `topk` |
-| 查找文档/规则 | `semantic_search` | `path`, `query`, `topk`, `lang: "markdown"|"yaml"` |
-| 查找调用者 | `ast_graph_callers` | `path`, `name`, `limit` |
-| 查找被调用者 | `ast_graph_callees` | `path`, `name`, `limit` |
-| 追踪调用链 | `ast_graph_chain` | `path`, `name`, `direction`, `max_depth` |
-| 查看符号历史 | `dsr_symbol_evolution` | `path`, `symbol`, `limit` |
-| 生成 DSR | `dsr_generate` | `path`, `commit` |
-| 读取代码 | `read_file` | `path`, `file`, `start_line`, `end_line` |
-
-## 最佳实践
-
-1. **每次调用必须显式传 `path` 参数**，保证调用原子性
-2. **优先使用高层语义工具**（symbol search）而非低层文件遍历
-3. **修改代码前必须先理解现有实现**，避免破坏性变更
-4. **使用 DSR 工具理解历史变更**，而非手动 git log
-5. **大型变更前先 `repo_map` 确认影响范围**
-6. **索引不兼容时及时重建**，确保检索准确性
-
-## 常见陷阱
-
-- ❌ 不要假设符号位置，必须通过 search 确认
-- ❌ 不要直接修改未读过的文件
-- ❌ 不要手动解析 git 历史，使用 DSR 工具
-- ❌ 不要在索引缺失时进行符号搜索
-- ❌ 不要忽略 DSR 的风险等级提示
-
-## 触发模式
-
-当用户说以下话时，使用对应工具：
+## References
 
-- "帮我理解这个项目" / "项目结构是什么" → `repo_map`
-- "查找 XX 函数" / "搜索 XX 方法" → `search_symbols`
-- "XX 在哪里实现" / "XX 怎么调用" → `semantic_search` + `ast_graph_callers`
-- "XX 的变更历史" / "XX 什么时候修改" → `dsr_symbol_evolution`
-- "重构 XX" / "修改 XX" → 先 `callers/callees/chain` 确认影响范围
+- **Tool details**: See [references/tools.md](references/tools.md) for complete tool documentation
+- **Constraints**: See [references/constraints.md](references/constraints.md) for behavioral rules
diff --git a/templates/agents/common/skills/git-ai-mcp/references/constraints.md b/templates/agents/common/skills/git-ai-mcp/references/constraints.md
new file mode 100644
index 0000000..3f49663
--- /dev/null
+++ b/templates/agents/common/skills/git-ai-mcp/references/constraints.md
@@ -0,0 +1,143 @@
+# git-ai MCP Behavioral Constraints
+
+Rules and constraints for using git-ai MCP tools effectively and safely.
+
+## Must-Follow Rules (Error Level)
+
+### 1. explicit_path
+
+**Rule:** Every MCP tool call MUST include an explicit `path` parameter.
+
+**Why:** Ensures atomic, reproducible calls. Never rely on process state or working directory.
+
+**Good:**
+```js
+search_symbols({ path: "/abs/path/to/repo", query: "handleRequest" })
+```
+
+**Bad:**
+```js
+search_symbols({ query: "handleRequest" })  // Missing path!
+```
+
+### 2. check_index_first
+
+**Rule:** Before using `search_symbols`, `semantic_search`, or any `ast_graph_*` tool, MUST call `check_index` to verify index is ready.
+
+**Why:** These tools depend on the index. Searching with a missing/incompatible index gives unreliable results.
+
+**Workflow:**
+```js
+// Step 1: Check index
+const status = check_index({ path: "/repo" })
+
+// Step 2: Rebuild if needed
+if (!status.compatible) {
+  rebuild_index({ path: "/repo" })
+}
+
+// Step 3: Now safe to search
+search_symbols({ path: "/repo", query: "..." })
+```
+
+### 3. understand_before_modify
+
+**Rule:** Before modifying any file, MUST:
+1. Use `search_symbols` to locate the code
+2. Use `read_file` to understand the implementation
+3. Use `ast_graph_callers` to assess impact
+4. Only then make changes
+
+**Why:** Prevents breaking changes and ensures informed modifications.
+
+### 4. use_dsr_for_history
+
+**Rule:** When tracing symbol history, MUST use `dsr_symbol_evolution`. NEVER manually parse git log or diff.
+
+**Why:** DSR provides structured, semantic change information that raw git commands don't.
+
+## Warning-Level Rules
+
+### 5. repo_map_before_large_change
+
+**Rule:** Before large refactoring or architectural changes, use `repo_map` to understand project structure.
+
+**Why:** Provides context for planning changes and identifying affected areas.
+
+### 6. respect_dsr_risk
+
+**Rule:** When DSR reports `risk_level: high`, exercise extra caution. Operations like `delete` and `rename` require additional review.
+
+**Risk levels:**
+- `low`: Safe, routine changes
+- `medium`: Review recommended
+- `high`: Extra scrutiny required
+
+## Recommended Practices
+
+### prefer_semantic_search
+
+For understanding functional intent, prefer `semantic_search` over `search_symbols`.
+
+**Use `semantic_search` when:**
+- Looking for conceptual functionality
+- Query is in natural language
+- Exact name is unknown
+
+**Use `search_symbols` when:**
+- Exact or partial name is known
+- Looking for specific identifiers
+
+### use_call_chain_for_complex_flow
+
+For complex flows spanning multiple functions, use `ast_graph_chain` instead of manually chaining `callers`/`callees` calls.
+
+```js
+// Good: Single call for complete chain
+ast_graph_chain({ path: "/repo", name: "processPayment", direction: "upstream", max_depth: 5 })
+
+// Avoid: Manual recursive calls
+ast_graph_callers({ path: "/repo", name: "processPayment" })
+// then for each result...
+ast_graph_callers({ path: "/repo", name: result.name })
+// etc.
+```
+
+### incremental_dsr_generation
+
+Generate DSR on-demand for specific commits rather than batch-generating for entire history.
+
+```js
+// Good: Generate for specific commit when needed
+dsr_generate({ path: "/repo", commit: "abc123" })
+
+// Avoid: Generating for all historical commits upfront
+```
+
+## Prohibited Actions
+
+| Action | Reason |
+|--------|--------|
+| Assume symbol location without searching | Always confirm via search |
+| Modify unread files | Must read and understand first |
+| Manual git log parsing for history | Use DSR tools instead |
+| Search with missing index | Rebuild index first |
+| Ignore high risk DSR warnings | Requires extra review |
+| Omit `path` parameter | Every call must be explicit |
+
+## Tool-Specific Constraints
+
+| Tool | Precondition | Required Params |
+|------|--------------|-----------------|
+| `repo_map` | None | `path` |
+| `check_index` | None | `path` |
+| `rebuild_index` | None | `path` |
+| `search_symbols` | `check_index` passed | `path`, `query` |
+| `semantic_search` | `check_index` passed | `path`, `query` |
+| `ast_graph_callers` | `check_index` passed | `path`, `name` |
+| `ast_graph_callees` | `check_index` passed | `path`, `name` |
+| `ast_graph_chain` | `check_index` passed | `path`, `name` |
+| `dsr_context` | None | `path` |
+| `dsr_generate` | None | `path`, `commit` |
+| `dsr_symbol_evolution` | DSR exists for commits | `path`, `symbol` |
+| `read_file` | None | `path`, `file` |
diff --git a/templates/agents/common/skills/git-ai-mcp/references/tools.md b/templates/agents/common/skills/git-ai-mcp/references/tools.md
new file mode 100644
index 0000000..42106ae
--- /dev/null
+++ b/templates/agents/common/skills/git-ai-mcp/references/tools.md
@@ -0,0 +1,263 @@
+# git-ai MCP Tools Reference
+
+Complete documentation for all git-ai MCP tools.
+
+## Index Management
+
+### check_index
+
+Check if repository index is ready and compatible.
+
+```js
+check_index({ path: "/abs/path/to/repo" })
+```
+
+**Returns:** Index status, compatibility info, and recommendations.
+
+**When to use:** Before any search or graph operation.
+
+### rebuild_index
+
+Rebuild the repository index from scratch.
+
+```js
+rebuild_index({ path: "/abs/path/to/repo" })
+```
+
+**Parameters:**
+- `path` (required): Absolute path to repository root
+- `overwrite` (optional): Whether to overwrite existing index (default: true)
+- `dim` (optional): Vector dimension (default: 256)
+
+**Note:** Can be slow for large repositories. Use when index is missing or incompatible.
+
+### pack_index / unpack_index
+
+Package index for storage or distribution.
+
+```js
+pack_index({ path: "/repo", lfs: true })  // Pack with LFS tracking
+unpack_index({ path: "/repo" })            // Restore from archive
+```
+
+## Search Tools
+
+### repo_map
+
+Get a high-level overview of repository structure.
+
+```js
+repo_map({
+  path: "/abs/path/to/repo",
+  max_files: 20,      // Top files by importance
+  max_symbols: 5      // Top symbols per file
+})
+```
+
+**When to use:** First contact with a repository, before large changes.
+
+### search_symbols
+
+Search for symbols by name pattern.
+
+```js
+search_symbols({
+  path: "/repo",
+  query: "handleRequest",
+  mode: "substring",   // substring | prefix | wildcard | regex | fuzzy
+  limit: 50,
+  case_insensitive: false
+})
+```
+
+**Modes:**
+- `substring`: Match anywhere in name (default)
+- `prefix`: Match start of name
+- `wildcard`: Use `*` and `?` wildcards
+- `regex`: Full regex support
+- `fuzzy`: Typo-tolerant matching
+
+### semantic_search
+
+Search code by meaning using vector similarity.
+
+```js
+semantic_search({
+  path: "/repo",
+  query: "user authentication and session management",
+  topk: 10,
+  lang: "auto"  // auto | all | java | ts
+})
+```
+
+**When to use:** Understanding functional intent, finding conceptually related code.
+
+## AST Graph Tools
+
+### ast_graph_find
+
+Find symbols by name prefix in the AST graph.
+
+```js
+ast_graph_find({
+  path: "/repo",
+  prefix: "handle",
+  limit: 50
+})
+```
+
+### ast_graph_callers
+
+Find all functions that call a given function.
+
+```js
+ast_graph_callers({
+  path: "/repo",
+  name: "authenticateUser",
+  limit: 200
+})
+```
+
+**When to use:** Impact analysis before refactoring, understanding usage patterns.
+
+### ast_graph_callees
+
+Find all functions called by a given function.
+
+```js
+ast_graph_callees({
+  path: "/repo",
+  name: "processOrder",
+  limit: 200
+})
+```
+
+**When to use:** Understanding implementation details, dependency analysis.
+
+### ast_graph_chain
+
+Trace complete call chain in either direction.
+
+```js
+ast_graph_chain({
+  path: "/repo",
+  name: "handlePayment",
+  direction: "downstream",  // downstream | upstream
+  max_depth: 3,
+  limit: 500
+})
+```
+
+**Directions:**
+- `downstream`: What does this function call? (implementation details)
+- `upstream`: Who calls this function? (usage/impact)
+
+**When to use:** Complex flow analysis, understanding system architecture.
+
+### ast_graph_children
+
+List direct children in AST containment (file → symbols, class → methods).
+
+```js
+ast_graph_children({
+  path: "/repo",
+  id: "src/auth/service.ts",
+  as_file: true  // Treat id as file path
+})
+```
+
+### ast_graph_refs
+
+Find all references to a name (calls, new expressions, type references).
+
+```js
+ast_graph_refs({
+  path: "/repo",
+  name: "UserService",
+  limit: 200
+})
+```
+
+## DSR Tools (Deterministic Semantic Records)
+
+### dsr_context
+
+Get repository Git context and DSR directory state.
+
+```js
+dsr_context({ path: "/repo" })
+```
+
+**Returns:** Branch info, commit status, DSR availability.
+
+### dsr_generate
+
+Generate DSR for a specific commit.
+
+```js
+dsr_generate({
+  path: "/repo",
+  commit: "HEAD"  // or specific commit hash
+})
+```
+
+**When to use:** Before querying history for commits without DSR.
+
+### dsr_symbol_evolution
+
+Track how a symbol changed over time.
+
+```js
+dsr_symbol_evolution({
+  path: "/repo",
+  symbol: "authenticateUser",
+  limit: 50,
+  contains: false,  // true for substring match
+  all: false        // true to traverse all refs, not just HEAD
+})
+```
+
+**Returns:** List of changes with:
+- `commit`: Commit hash
+- `operation`: add | modify | delete | rename
+- `risk_level`: low | medium | high
+- `details`: Change description
+
+**When to use:** Understanding design evolution, finding when/why something changed.
+
+### dsr_rebuild_index
+
+Rebuild DSR index from DSR files.
+
+```js
+dsr_rebuild_index({ path: "/repo" })
+```
+
+## File Operations
+
+### read_file
+
+Read file content with optional line range.
+
+```js
+read_file({
+  path: "/repo",
+  file: "src/auth/service.ts",  // Relative to repo root
+  start_line: 1,
+  end_line: 200
+})
+```
+
+**Best practice:** Use with `start_line`/`end_line` for large files.
+
+### list_files
+
+List repository files by glob pattern.
+
+```js
+list_files({
+  path: "/repo",
+  pattern: "src/**/*.ts",
+  limit: 500
+})
+```
diff --git a/templates/agents/common/skills/git-ai/skill.yaml b/templates/agents/common/skills/git-ai/skill.yaml
deleted file mode 100644
index 5c46ff3..0000000
--- a/templates/agents/common/skills/git-ai/skill.yaml
+++ /dev/null
@@ -1,124 +0,0 @@
-name: git-ai-mcp
-version: "2.0.0"
-description: |
-  指导 Agent 使用 git-ai MCP 工具高效理解和操作代码库。
-  适用于 Claude Desktop、Trae 等支持 MCP 的本地 Code Agent。
-
-role: |
-  你是开发者的智能助手，专注于帮助开发者快速理解代码库结构、
-  定位关键代码、分析代码关系、追溯变更历史，并提供精准的代码修改建议。
-
-core_capabilities:
-  - 仓库全局理解：通过 repo_map 快速获取项目结构和关键文件概览
-  - 符号检索：使用 search_symbols 和 semantic_search 定位代码
-  - 代码关系分析：通过 ast_graph_callers/callees/chain 理解调用关系
-  - 变更历史追溯：使用 dsr_symbol_evolution 追踪符号演变
-  - 代码精读：使用 read_file 深入理解关键代码片段
-  - 索引管理：按需重建索引，确保检索准确性
-
-recommended_workflow:
-  - step: 1
-    name: "首次接触仓库"
-    action: |
-      调用 repo_map({ path, max_files: 20, max_symbols: 5 }) 获取全局视图。
-      了解项目结构、关键文件、主要符号，为后续分析建立上下文。
-
-  - step: 2
-    name: "检查索引状态"
-    action: |
-      调用 check_index({ path }) 检查索引是否就绪。
-      如果索引不兼容或缺失，调用 rebuild_index({ path }) 重建。
-
-  - step: 3
-    name: "定位目标代码"
-    action: |
-      使用 search_symbols({ path, query, mode: 'substring', limit: 20 }) 
-      或 semantic_search({ path, query, topk: 10 }) 定位相关代码。
-      优先使用语义搜索理解功能意图，使用符号搜索精确定位。
-
-  - step: 4
-    name: "理解代码关系"
-    action: |
-      找到关键符号后，使用 ast_graph_callers/callees 分析调用关系。
-      对于复杂链路，使用 ast_graph_chain 追踪上下游调用链。
-
-  - step: 5
-    name: "追溯变更历史"
-    action: |
-      使用 dsr_symbol_evolution({ path, symbol, limit: 50 }) 
-      了解符号的历史变更，包括修改类型、风险等级、操作详情。
-
-  - step: 6
-    name: "精读代码"
-    action: |
-      使用 read_file({ path, file, start_line, end_line }) 
-      精读关键代码片段，理解实现细节。
-
-  - step: 7
-    name: "提供建议"
-    action: |
-      基于完整的代码理解，提供修改建议或生成代码。
-
-best_practices:
-  - "每次工具调用必须显式传 path 参数，保证调用原子性"
-  - "优先使用高层语义工具（symbol search）而非低层文件遍历"
-  - "修改代码前必须先理解现有实现，避免破坏性变更"
-  - "使用 DSR 工具理解历史变更，而非手动 git log"
-  - "大型变更前先 repo_map 确认影响范围"
-  - "索引不兼容时及时重建，确保检索准确性"
-
-tool_selection_guide:
-  - scenario: "了解项目结构"
-    tool: repo_map
-    params: { path, max_files: 20, max_symbols: 5 }
-
-  - scenario: "按名称查找符号"
-    tool: search_symbols
-    params: { path, query, mode: 'substring|prefix|wildcard', limit: 50 }
-
-  - scenario: "按语义查找代码"
-    tool: semantic_search
-    params: { path, query, topk: 10 }
-
-  - scenario: "查找调用者"
-    tool: ast_graph_callers
-    params: { path, name, limit: 50 }
-
-  - scenario: "查找被调用者"
-    tool: ast_graph_callees
-    params: { path, name, limit: 50 }
-
-  - scenario: "追踪调用链"
-    tool: ast_graph_chain
-    params: { path, name, direction: 'upstream|downstream', max_depth: 3 }
-
-  - scenario: "查看符号历史"
-    tool: dsr_symbol_evolution
-    params: { path, symbol, limit: 50, contains: false }
-
-  - scenario: "生成 DSR"
-    tool: dsr_generate
-    params: { path, commit: 'HEAD' }
-
-  - scenario: "读取代码"
-    tool: read_file
-    params: { path, file, start_line: 1, end_line: 200 }
-
-common_pitfalls:
-  - "不要假设符号位置，必须通过 search 确认"
-  - "不要直接修改未读过的文件"
-  - "不要手动解析 git 历史，使用 DSR 工具"
-  - "不要在索引缺失时进行符号搜索"
-  - "不要忽略 DSR 的风险等级提示"
-
-triggers:
-  - pattern: "帮我理解这个项目|项目结构是什么"
-    action: "使用 repo_map 获取全局视图"
-  - pattern: "查找.*函数|搜索.*方法"
-    action: "使用 search_symbols 定位符号"
-  - pattern: ".*在哪里实现|.*怎么调用"
-    action: "使用 semantic_search + ast_graph_callers 定位并分析"
-  - pattern: ".*的变更历史|.*什么时候修改"
-    action: "使用 dsr_symbol_evolution 追溯历史"
-  - pattern: "重构.*|修改.*"
-    action: "先使用 callers/callees/chain 确认影响范围，再修改"