Agent skill
graph-query
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/graph-query
SKILL.md
/graph-query
Query the vault's knowledge graph index using natural language or structured queries.
Usage
/graph-query ADRs with status proposed
/graph-query high priority tasks
/graph-query orphaned notes
/graph-query broken links
/graph-query backlinks to Project - MyProject
/graph-query --type=Adr --status=accepted
Instructions
When the user invokes /graph-query or asks to query the graph index:
Phase 1: Ensure Index Exists
Before executing any query, check if the graph index exists:
-
Check if
.graph/index.jsonexists -
If not found, inform the user and offer to build it:
The graph index needs to be generated first. Running: npm run graph:buildExecute:
npm run graph:build -
If index exists but is stale (>1 day old), optionally suggest rebuilding
Phase 2: Parse the Query
Understand what the user is asking for. The query system supports:
Natural Language Patterns:
| Pattern | Interpretation |
|---|---|
| "ADRs with status proposed" | --type=Adr --status=proposed |
| "high priority tasks" | --type=Task --priority=high |
| "active projects" | --type=Project --status=active |
| "orphaned notes" | --orphans |
| "broken links" | --broken-links |
| "stale notes" | --stale |
| "meetings about kafka" | --type=Meeting --search=kafka |
| "backlinks to X" | --backlinks="X" |
| "notes mentioning aws" | --search=aws |
Structured Parameters:
| Parameter | Description | Example |
|---|---|---|
--type= |
Filter by note type | --type=Adr, --type=Project |
--status= |
Filter by status | --status=proposed, --status=active |
--priority= |
Filter by priority | --priority=high |
--search= |
BM25 relevance search (ranked results) | --search="kafka integration" |
--backlinks= |
Find notes linking to target | --backlinks="Project - MyProject" |
--orphans |
List orphaned notes | |
--broken-links |
List broken wiki-links | |
--stale |
List notes >6 months old | |
--stats |
Show index statistics | |
--json |
Output as JSON with scores |
Phase 3: Execute Query via CLI
Run the appropriate command:
# Natural language query
node scripts/graph-query.js "ADRs with status proposed"
# Structured query
node scripts/graph-query.js --type=Adr --status=proposed
# Special queries
node scripts/graph-query.js --orphans
node scripts/graph-query.js --broken-links
node scripts/graph-query.js --stats
# JSON output (for further processing)
node scripts/graph-query.js --type=Task --priority=high --json
Phase 4: Format Response
Present results as a markdown table. For search queries, results are ranked by BM25 relevance score:
## Search Results
Found **X** result(s) for: "kafka integration"
| Score | Type | Title |
|-------|------|-------|
| 14.65 | Page | Kafka Integration Solution Architecture |
| 11.32 | Integration | ERP → Data Lake |
| 9.45 | System | Data Platform |
*Results ranked by BM25 relevance score (higher = more relevant)*
For type/status queries (no search term), show standard format:
## Query Results
Found **X** result(s) for: "ADRs with status proposed"
| Type | Status | Priority | Title |
|------|--------|----------|-------|
| Adr | proposed | high | ADR - API Gateway Selection |
| Adr | proposed | medium | ADR - Event Streaming Platform |
### Quick Actions
- View a note: `[[ADR - API Gateway Selection]]`
- Find related: `/graph-query backlinks to "ADR - API Gateway Selection"`
- Check quality: `/graph-query --stats`
For special queries like orphans or broken links, format appropriately:
## Orphaned Notes Report
Found **8** orphaned notes (notes with no backlinks)
| Type | Title | Last Modified |
|------|-------|---------------|
| Page | Database Migration Checklist | 2025-11-15 |
| Project | Research - Event-Driven Architecture | 2025-10-20 |
### Recommendations
- Consider linking from relevant MOCs
- Archive if no longer needed
- Use `/archive <note>` to soft-archive
Query Examples
By Type
/graph-query all ADRs
/graph-query projects
/graph-query active tasks
/graph-query meetings
By Status/Priority
/graph-query ADRs with status proposed
/graph-query high priority tasks
/graph-query completed projects
/graph-query draft ADRs
Search
/graph-query notes about kafka
/graph-query mentions of aws bedrock
/graph-query "integration pattern"
Relationships
/graph-query backlinks to Project - MyProject
/graph-query orphaned notes
/graph-query broken links
Quality
/graph-query stale notes
/graph-query --stats
Notes
- The graph index is stored in
.graph/directory (git-ignored) - Index is automatically excluded from vault searches
- Rebuild index after major changes:
npm run graph:build - Use
npm run graph:watchfor automatic rebuilding during active work - Results are limited to 50 items by default; use
--jsonfor full results - Search uses BM25 ranking - results are sorted by relevance score, not just filtered
- BM25 weights rare terms higher (IDF) and normalises for document length
- JSON output includes relevance scores for programmatic use
Related Skills
/orphans- Dedicated orphan analysis with recommendations/broken-links- Detailed broken link analysis with fixes/quality-report- Comprehensive vault quality report/vault-maintenance- Full maintenance check including graph analysis
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?