Index Knowledge

tursodatabase/turso/.claude/skills/index-knowledge

作者 tursodatabaseff97ec42cdef无许可证24K 个星标收录于 2026年10月9日更新于 2026年10月8日仓库今天更新

Generate hierarchical AGENTS.md knowledge base for a codebase. Creates root + complexity-scored subdirectory documentation.

仅含说明AI & Agents

AI 生成的概览

为代码库生成分层 AGENTS.md 知识库文件，包括根文件与按复杂度评分的子目录文件。

功能: 该技能遍历代码库，通过 shell 命令、可选的 LSP 符号查询以及并行探索代理分析其结构，然后为每个目录的复杂度打分。它会写入根目录 AGENTS.md，并为通过评分阈值的目录写入子目录 AGENTS.md，内容涵盖概览、结构、查找位置、约定、反模式和命令。它支持更新模式和从头重新生成的 create-new 模式，最后进行去重与精简的审查。
适用场景: 当代码库需要面向代理的、持久的结构与约定文档时使用。适用于将代码库接入代理工作流，或在结构发生重大变化后刷新过期的 AGENTS.md 文件。
运行要求: 需要能够运行 shell 命令、读写文件并启动并行子代理的代理环境。可选的 LSP 工具可增强符号分析，但并非必需。该技能不附带脚本，仅为指令。

index-knowledge

Generate hierarchical AGENTS.md files. Root + complexity-scored subdirectories.

Usage

--create-new   # Read existing → remove all → regenerate from scratch--max-depth=2  # Limit directory depth (default: 5)

--create-new   # Read existing → remove all → regenerate from scratch--max-depth=2  # Limit directory depth (default: 5)

Default: Update mode (modify existing + create new where warranted)

Workflow (High-Level)

Discovery + Analysis (concurrent)
- Launch parallel explore agents (multiple Task calls in one message)
- Main session: bash structure + LSP codemap + read existing AGENTS.md
Score & Decide - Determine AGENTS.md locations from merged findings
Generate - Root first, then subdirs in parallel
Review - Deduplicate, trim, validate

<critical>

TodoWrite ALL phases. Mark in_progress → completed in real-time.

TodoWrite([  { id: "discovery", content: "Fire explore agents + LSP codemap + read existing", status: "pending", priority: "high" },  { id: "scoring", content: "Score directories, determine locations", status: "pending", priority: "high" },  { id: "generate", content: "Generate AGENTS.md files (root + subdirs)", status: "pending", priority: "high" },  { id: "review", content: "Deduplicate, validate, trim", status: "pending", priority: "medium" }])

TodoWrite([  { id: "discovery", content: "Fire explore agents + LSP codemap + read existing", status: "pending", priority: "high" },  { id: "scoring", content: "Score directories, determine locations", status: "pending", priority: "high" },  { id: "generate", content: "Generate AGENTS.md files (root + subdirs)", status: "pending", priority: "high" },  { id: "review", content: "Deduplicate, validate, trim", status: "pending", priority: "medium" }])

</critical>

Phase 1: Discovery + Analysis (Concurrent)

Mark "discovery" as in_progress.

Launch Parallel Explore Agents

Multiple Task calls in a single message execute in parallel. Results return directly.

// All Task calls in ONE message = parallel execution
Task(  description="project structure",  subagent_type="explore",  prompt="Project structure: PREDICT standard patterns for detected language → REPORT deviations only")
Task(  description="entry points",  subagent_type="explore",  prompt="Entry points: FIND main files → REPORT non-standard organization")
Task(  description="conventions",  subagent_type="explore",  prompt="Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) → REPORT project-specific rules")
Task(  description="anti-patterns",  subagent_type="explore",  prompt="Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments → LIST forbidden patterns")
Task(  description="build/ci",  subagent_type="explore",  prompt="Build/CI: FIND .github/workflows, Makefile → REPORT non-standard patterns")
Task(  description="test patterns",  subagent_type="explore",  prompt="Test patterns: FIND test configs, test structure → REPORT unique conventions")

// All Task calls in ONE message = parallel execution
Task(  description="project structure",  subagent_type="explore",  prompt="Project structure: PREDICT standard patterns for detected language → REPORT deviations only")
Task(  description="entry points",  subagent_type="explore",  prompt="Entry points: FIND main files → REPORT non-standard organization")
Task(  description="conventions",  subagent_type="explore",  prompt="Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) → REPORT project-specific rules")
Task(  description="anti-patterns",  subagent_type="explore",  prompt="Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments → LIST forbidden patterns")
Task(  description="build/ci",  subagent_type="explore",  prompt="Build/CI: FIND .github/workflows, Makefile → REPORT non-standard patterns")
Task(  description="test patterns",  subagent_type="explore",  prompt="Test patterns: FIND test configs, test structure → REPORT unique conventions")

<dynamic-agents>

DYNAMIC AGENT SPAWNING: After bash analysis, spawn ADDITIONAL explore agents based on project scale:

Factor	Threshold	Additional Agents
Total files	>100	+1 per 100 files
Total lines	>10k	+1 per 10k lines
Directory depth	≥4	+2 for deep exploration
Large files (>500 lines)	>10 files	+1 for complexity hotspots
Monorepo	detected	+1 per package/workspace
Multiple languages	>1	+1 per language

bash

# Measure project scale firsttotal_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)total_lines=$(find . -type f \( -name "*.ts" -o -name "*.py" -o -name "*.go" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')large_files=$(find . -type f \( -name "*.ts" -o -name "*.py" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}')max_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)

# Measure project scale firsttotal_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)total_lines=$(find . -type f \( -name "*.ts" -o -name "*.py" -o -name "*.go" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')large_files=$(find . -type f \( -name "*.ts" -o -name "*.py" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}')max_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)

Example spawning (all in ONE message for parallel execution):

// 500 files, 50k lines, depth 6, 15 large files → spawn additional agentsTask(  description="large files",  subagent_type="explore",  prompt="Large file analysis: FIND files >500 lines, REPORT complexity hotspots")
Task(  description="deep modules",  subagent_type="explore",  prompt="Deep modules at depth 4+: FIND hidden patterns, internal conventions")
Task(  description="cross-cutting",  subagent_type="explore",  prompt="Cross-cutting concerns: FIND shared utilities across directories")// ... more based on calculation

// 500 files, 50k lines, depth 6, 15 large files → spawn additional agentsTask(  description="large files",  subagent_type="explore",  prompt="Large file analysis: FIND files >500 lines, REPORT complexity hotspots")
Task(  description="deep modules",  subagent_type="explore",  prompt="Deep modules at depth 4+: FIND hidden patterns, internal conventions")
Task(  description="cross-cutting",  subagent_type="explore",  prompt="Cross-cutting concerns: FIND shared utilities across directories")// ... more based on calculation

</dynamic-agents>

Main Session: Concurrent Analysis

While Task agents execute, main session does:

1. Bash Structural Analysis

bash

# Directory depth + file countsfind . -type d -not -path '*/\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c
# Files per directory (top 30)find . -type f -not -path '*/\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30
# Code concentration by extensionfind . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.go" -o -name "*.rs" \) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20
# Existing AGENTS.md / CLAUDE.mdfind . -type f \( -name "AGENTS.md" -o -name "CLAUDE.md" \) -not -path '*/node_modules/*' 2>/dev/null

# Directory depth + file countsfind . -type d -not -path '*/\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c
# Files per directory (top 30)find . -type f -not -path '*/\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30
# Code concentration by extensionfind . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.go" -o -name "*.rs" \) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20
# Existing AGENTS.md / CLAUDE.mdfind . -type f \( -name "AGENTS.md" -o -name "CLAUDE.md" \) -not -path '*/node_modules/*' 2>/dev/null

2. Read Existing AGENTS.md

For each existing file found:  Read(filePath=file)  Extract: key insights, conventions, anti-patterns  Store in EXISTING_AGENTS map

For each existing file found:  Read(filePath=file)  Extract: key insights, conventions, anti-patterns  Store in EXISTING_AGENTS map

If --create-new: Read all existing first (preserve context) → then delete all → regenerate.

3. LSP Codemap (if available)

lsp_servers()  # Check availability
# Entry points (parallel)lsp_document_symbols(filePath="src/index.ts")lsp_document_symbols(filePath="main.py")
# Key symbols (parallel)lsp_workspace_symbols(filePath=".", query="class")lsp_workspace_symbols(filePath=".", query="interface")lsp_workspace_symbols(filePath=".", query="function")
# Centrality for top exportslsp_find_references(filePath="...", line=X, character=Y)

lsp_servers()  # Check availability
# Entry points (parallel)lsp_document_symbols(filePath="src/index.ts")lsp_document_symbols(filePath="main.py")
# Key symbols (parallel)lsp_workspace_symbols(filePath=".", query="class")lsp_workspace_symbols(filePath=".", query="interface")lsp_workspace_symbols(filePath=".", query="function")
# Centrality for top exportslsp_find_references(filePath="...", line=X, character=Y)

LSP Fallback: If unavailable, rely on explore agents + AST-grep.

Merge: bash + LSP + existing + Task agent results. Mark "discovery" as completed.

Phase 2: Scoring & Location Decision

Mark "scoring" as in_progress.

Scoring Matrix

Factor	Weight	High Threshold	Source
File count	3x	>20	bash
Subdir count	2x	>5	bash
Code ratio	2x	>70%	bash
Unique patterns	1x	Has own config	explore
Module boundary	2x	Has index.ts/init.py	bash
Symbol density	2x	>30 symbols	LSP
Export count	2x	>10 exports	LSP
Reference centrality	3x	>20 refs	LSP

Decision Rules

Output

AGENTS_LOCATIONS = [  { path: ".", type: "root" },  { path: "src/hooks", score: 18, reason: "high complexity" },  { path: "src/api", score: 12, reason: "distinct domain" }]

AGENTS_LOCATIONS = [  { path: ".", type: "root" },  { path: "src/hooks", score: 18, reason: "high complexity" },  { path: "src/api", score: 12, reason: "distinct domain" }]

Mark "scoring" as completed.

Phase 3: Generate AGENTS.md

Mark "generate" as in_progress.

Root AGENTS.md (Full Treatment)

markdown

# PROJECT KNOWLEDGE BASE
**Generated:** {TIMESTAMP}**Commit:** {SHORT_SHA}**Branch:** {BRANCH}
## OVERVIEW{1-2 sentences: what + core stack}
## STRUCTURE\`\`\`{root}/├── {dir}/    # {non-obvious purpose only}└── {entry}\`\`\`
## WHERE TO LOOK| Task | Location | Notes ||------|----------|-------|
## CODE MAP{From LSP - skip if unavailable or project <10 files}
| Symbol | Type | Location | Refs | Role |
## CONVENTIONS{ONLY deviations from standard}
## ANTI-PATTERNS (THIS PROJECT){Explicitly forbidden here}
## UNIQUE STYLES{Project-specific}
## COMMANDS\`\`\`bash{dev/test/build}\`\`\`
## NOTES{Gotchas}

# PROJECT KNOWLEDGE BASE
**Generated:** {TIMESTAMP}**Commit:** {SHORT_SHA}**Branch:** {BRANCH}
## OVERVIEW{1-2 sentences: what + core stack}
## STRUCTURE\`\`\`{root}/├── {dir}/    # {non-obvious purpose only}└── {entry}\`\`\`
## WHERE TO LOOK| Task | Location | Notes ||------|----------|-------|
## CODE MAP{From LSP - skip if unavailable or project <10 files}
| Symbol | Type | Location | Refs | Role |
## CONVENTIONS{ONLY deviations from standard}
## ANTI-PATTERNS (THIS PROJECT){Explicitly forbidden here}
## UNIQUE STYLES{Project-specific}
## COMMANDS\`\`\`bash{dev/test/build}\`\`\`
## NOTES{Gotchas}

Quality gates: 50-150 lines, no generic advice, no obvious info.

Subdirectory AGENTS.md (Parallel)

Launch general agents for each location in ONE message (parallel execution):

// All in single message = parallelTask(  description="AGENTS.md for src/hooks",  subagent_type="general",  prompt="Generate AGENTS.md for: src/hooks    - Reason: high complexity    - 30-80 lines max    - NEVER repeat parent content    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS    - Write directly to src/hooks/AGENTS.md")
Task(  description="AGENTS.md for src/api",  subagent_type="general",  prompt="Generate AGENTS.md for: src/api    - Reason: distinct domain    - 30-80 lines max    - NEVER repeat parent content    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS    - Write directly to src/api/AGENTS.md")// ... one Task per AGENTS_LOCATIONS entry

// All in single message = parallelTask(  description="AGENTS.md for src/hooks",  subagent_type="general",  prompt="Generate AGENTS.md for: src/hooks    - Reason: high complexity    - 30-80 lines max    - NEVER repeat parent content    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS    - Write directly to src/hooks/AGENTS.md")
Task(  description="AGENTS.md for src/api",  subagent_type="general",  prompt="Generate AGENTS.md for: src/api    - Reason: distinct domain    - 30-80 lines max    - NEVER repeat parent content    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS    - Write directly to src/api/AGENTS.md")// ... one Task per AGENTS_LOCATIONS entry

Results return directly. Mark "generate" as completed.

Phase 4: Review & Deduplicate

Mark "review" as in_progress.

For each generated file:

Remove generic advice
Remove parent duplicates
Trim to size limits
Verify telegraphic style

Mark "review" as completed.

Final Report

=== index-knowledge Complete ===
Mode: {update | create-new}
Files:  ✓ ./AGENTS.md (root, {N} lines)  ✓ ./src/hooks/AGENTS.md ({N} lines)
Dirs Analyzed: {N}AGENTS.md Created: {N}AGENTS.md Updated: {N}
Hierarchy:  ./AGENTS.md  └── src/hooks/AGENTS.md

=== index-knowledge Complete ===
Mode: {update | create-new}
Files:  ✓ ./AGENTS.md (root, {N} lines)  ✓ ./src/hooks/AGENTS.md ({N} lines)
Dirs Analyzed: {N}AGENTS.md Created: {N}AGENTS.md Updated: {N}
Hierarchy:  ./AGENTS.md  └── src/hooks/AGENTS.md

Anti-Patterns

Static agent count: MUST vary agents based on project size/depth
Sequential execution: MUST parallel (multiple Task calls in one message)
Ignoring existing: ALWAYS read existing first, even with --create-new
Over-documenting: Not every dir needs AGENTS.md
Redundancy: Child never repeats parent
Generic content: Remove anything that applies to ALL projects
Verbose style: Telegraphic or die

来源与署名

来源：tursodatabase/turso位于.claude/skills/index-knowledge提交ff97ec4

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Score	Action
Root (.)	ALWAYS create
>15	Create AGENTS.md
8-15	Create if distinct domain
<8	Skip (parent covers)

Index Knowledge

index-knowledge

Usage

Workflow (High-Level)

Phase 1: Discovery + Analysis (Concurrent)

Launch Parallel Explore Agents

Main Session: Concurrent Analysis

1. Bash Structural Analysis

2. Read Existing AGENTS.md

3. LSP Codemap (if available)

Phase 2: Scoring & Location Decision

Scoring Matrix

Decision Rules

Output

Phase 3: Generate AGENTS.md

Root AGENTS.md (Full Treatment)

Subdirectory AGENTS.md (Parallel)

Phase 4: Review & Deduplicate

Final Report

Anti-Patterns

来源与署名

更多来自 tursodatabase/turso 的技能

Transaction Correctness

Storage Format

Testing

Debugging

Mvcc

Differential Fuzzer

更多AI & Agents技能

Ppt Template Creator

Skill Development

Plugin Structure

Command Development

Claude Md Improver

Find Skills