|
| 1 | +# ClickGraph Agent Skills |
| 2 | + |
| 3 | +Agent skills for querying ClickGraph databases using natural language. Built on the `cg` CLI — no MCP server or running ClickGraph server required. |
| 4 | + |
| 5 | +## Skills |
| 6 | + |
| 7 | +| Skill | File | What it does | |
| 8 | +|-------|------|--------------| |
| 9 | +| `/cypher` | `cypher.md` | Translate natural language → Cypher → SQL → execute | |
| 10 | +| `/graph-schema` | `graph-schema.md` | Show graph schema (nodes, relationships, properties) | |
| 11 | + |
| 12 | +## Prerequisites |
| 13 | + |
| 14 | +1. **`cg` binary** — download from [GitHub Releases](https://github.com/genezhang/clickgraph/releases/latest) or build: |
| 15 | + ```bash |
| 16 | + cargo build --release -p clickgraph-tool |
| 17 | + # binary at: target/release/cg |
| 18 | + ``` |
| 19 | + |
| 20 | +2. **Schema file** — your graph schema YAML. Set once and forget: |
| 21 | + ```bash |
| 22 | + export CG_SCHEMA="/path/to/schema.yaml" |
| 23 | + # or add to ~/.config/cg/config.toml: |
| 24 | + # [schema] |
| 25 | + # path = "/path/to/schema.yaml" |
| 26 | + ``` |
| 27 | + |
| 28 | +3. **LLM API key** (for `/cypher` NL translation): |
| 29 | + ```bash |
| 30 | + export ANTHROPIC_API_KEY="sk-ant-..." |
| 31 | + # or for OpenAI-compatible: |
| 32 | + # export CG_LLM_PROVIDER=openai |
| 33 | + # export OPENAI_API_KEY="sk-..." |
| 34 | + ``` |
| 35 | + |
| 36 | +4. **ClickHouse URL** (optional — for query execution): |
| 37 | + ```bash |
| 38 | + export CG_CLICKHOUSE_URL="http://localhost:8123" |
| 39 | + export CG_CLICKHOUSE_USER="default" |
| 40 | + export CG_CLICKHOUSE_PASSWORD="" |
| 41 | + ``` |
| 42 | + |
| 43 | +## Installation by Framework |
| 44 | + |
| 45 | +### Claude Code |
| 46 | + |
| 47 | +Copy skill files into your project's `.claude/commands/` directory: |
| 48 | + |
| 49 | +```bash |
| 50 | +mkdir -p .claude/commands |
| 51 | +curl -L https://raw.githubusercontent.com/genezhang/clickgraph/main/skills/cypher.md \ |
| 52 | + -o .claude/commands/cypher.md |
| 53 | +curl -L https://raw.githubusercontent.com/genezhang/clickgraph/main/skills/graph-schema.md \ |
| 54 | + -o .claude/commands/graph-schema.md |
| 55 | +``` |
| 56 | + |
| 57 | +Then use directly in Claude Code: |
| 58 | +``` |
| 59 | +/cypher find users with more than 10 followers |
| 60 | +/graph-schema |
| 61 | +``` |
| 62 | + |
| 63 | +### Claude Desktop / any MCP client |
| 64 | + |
| 65 | +Use the skills as reference prompts, or pair with the ClickGraph MCP server (see [AI-Assistant-Integration-MCP.md](../docs/wiki/AI-Assistant-Integration-MCP.md)). |
| 66 | + |
| 67 | +### LangChain / AutoGen / CrewAI / custom agents |
| 68 | + |
| 69 | +Use the skill file content as a system prompt or tool description. The `cg` CLI is the execution backend — call it as a subprocess: |
| 70 | + |
| 71 | +```python |
| 72 | +import subprocess |
| 73 | + |
| 74 | +def nl_to_cypher(query: str, schema: str, ch_url: str = None) -> dict: |
| 75 | + cmd = ["cg", "--schema", schema, "nl", query] |
| 76 | + if ch_url: |
| 77 | + cmd = ["cg", "--schema", schema, "--clickhouse", ch_url, |
| 78 | + "query", query] # use cg nl first, then query |
| 79 | + result = subprocess.run(cmd, capture_output=True, text=True) |
| 80 | + return {"output": result.stdout, "error": result.stderr} |
| 81 | +``` |
| 82 | + |
| 83 | +### OpenAI function calling |
| 84 | + |
| 85 | +```json |
| 86 | +{ |
| 87 | + "name": "clickgraph_query", |
| 88 | + "description": "Translate natural language to Cypher and execute against a ClickGraph database", |
| 89 | + "parameters": { |
| 90 | + "type": "object", |
| 91 | + "properties": { |
| 92 | + "query": { |
| 93 | + "type": "string", |
| 94 | + "description": "Natural language description of the graph query" |
| 95 | + } |
| 96 | + }, |
| 97 | + "required": ["query"] |
| 98 | + } |
| 99 | +} |
| 100 | +``` |
| 101 | + |
| 102 | +Implement the function by calling `cg nl "$query"` (and optionally `cg query`). |
| 103 | + |
| 104 | +## Configuration Reference |
| 105 | + |
| 106 | +All configuration can be set via environment variables, CLI flags, or `~/.config/cg/config.toml`. |
| 107 | + |
| 108 | +```toml |
| 109 | +# ~/.config/cg/config.toml |
| 110 | +[schema] |
| 111 | +path = "/path/to/schema.yaml" |
| 112 | + |
| 113 | +[clickhouse] |
| 114 | +url = "http://localhost:8123" |
| 115 | +user = "default" |
| 116 | +password = "" |
| 117 | + |
| 118 | +[llm] |
| 119 | +provider = "anthropic" # or "openai" |
| 120 | +model = "claude-sonnet-4-6" |
| 121 | +# api_key = "sk-..." # or set ANTHROPIC_API_KEY |
| 122 | +# base_url = "..." # for OpenRouter, Groq, Ollama, etc. |
| 123 | +``` |
| 124 | + |
| 125 | +See [clickgraph-tool/AGENTS.md](../clickgraph-tool/AGENTS.md) for the full `cg` CLI reference. |
0 commit comments