Back to Details

skill-system-graph

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill System Graph

Skill System 技能图谱

skill-system-graph
is an AI-first navigation layer for skill dependencies. It reads 
SKILL.spec.yaml
from each skill directory and normalizes 
depends_on
+ 
delegates_to
into a queryable behavior graph in PostgreSQL.
This skill is SKILL.spec.yaml-first. It does not read 
SKILL.behavior.yaml
for canonical graph construction.
skill-system-graph
是一个以AI为核心的技能依赖导航层。它会读取每个技能目录下的
SKILL.spec.yaml
文件，并将其中的
depends_on
和
delegates_to
字段标准化为PostgreSQL中可查询的行为图谱。
该Skill遵循以SKILL.spec.yaml为核心的原则。在构建标准图谱时，它不会读取
SKILL.behavior.yaml
文件。

Purpose

用途

  • Answer dependency questions quickly: what depends on what, and what changes may cascade.
  • Provide CLI primitives where 
    show
    reads the current spec-scan model and 
    neighbors
    /
    path
    /
    impact
    query persisted edges.
  • Keep behavior discovery fast via incremental refresh using source hashes.
  • 快速解答依赖相关问题：比如谁依赖谁，以及变更可能引发的连锁反应。
  • 提供CLI基础操作：
    show
    命令读取当前的规范扫描模型，
    neighbors
    /
    path
    /
    impact
    命令查询持久化的关联边。
  • 通过基于源文件哈希的增量刷新，确保行为发现的高效性。

Output Contract

输出约定

Agents should run with 
--format json
by default for stable automation.
  • json
    output: machine-readable object, one record per command.
  • text
    output: human-readable fallback only.
为实现稳定的自动化执行，Agent默认应使用
--format json
参数运行。
  • json
    输出：机器可读的对象，每个命令对应一条记录。
  • text
    输出：仅作为人类可读的备选格式。

Core Operations

核心操作

skill-system-graph
exposes 
graph
subcommands in 
scripts/
.
skill-system-graph
在
scripts/
目录下提供了
graph
子命令。

graph show

graph show
命令

Display all known nodes and edges from the current 
SKILL.spec.yaml
scan model.
bash
python3 "$(pwd)/skills/skill-system-graph/scripts/graph_cli.py" show [--skills-dir skills] [--format json|text]
JSON shape (agent-facing):
json
{
  "status": "ok",
  "nodes": [{"skill_name": "...", "description": "...", "spec_path": "...", "operations_count": 0, "content_hash": "...", "stub": false}],
  "edges": [{"source": "...", "target": "...", "edge_type": "depends_on|delegates_to"}],
  "node_count": 0,
  "edge_count": 0
}
显示当前
SKILL.spec.yaml
扫描模型中的所有已知节点和关联边。
bash
python3 "$(pwd)/skills/skill-system-graph/scripts/graph_cli.py" show [--skills-dir skills] [--format json|text]
JSON格式（面向Agent）：
json
{
  "status": "ok",
  "nodes": [{"skill_name": "...", "description": "...", "spec_path": "...", "operations_count": 0, "content_hash": "...", "stub": false}],
  "edges": [{"source": "...", "target": "...", "edge_type": "depends_on|delegates_to"}],
  "node_count": 0,
  "edge_count": 0
}

graph neighbors <skill_name>

graph neighbors <skill_name>
命令

List incoming and outgoing direct neighbors for a specific skill.
bash
python3 "$(pwd)/skills/skill-system-graph/scripts/graph_cli.py" neighbors skill-system-router [--format json|text]
JSON shape:
json
{
  "skill": "skill-system-router",
  "outgoing": [{"skill_name": "skill-system-postgres", "edge_type": "depends_on"}],
  "incoming": [{"skill_name": "skill-system-tkt", "edge_type": "delegates_to"}],
  "status": "ok"
}
列出指定技能的直接关联技能（入边和出边）。
bash
python3 "$(pwd)/skills/skill-system-graph/scripts/graph_cli.py" neighbors skill-system-router [--format json|text]
JSON格式：
json
{
  "skill": "skill-system-router",
  "outgoing": [{"skill_name": "skill-system-postgres", "edge_type": "depends_on"}],
  "incoming": [{"skill_name": "skill-system-tkt", "edge_type": "delegates_to"}],
  "status": "ok"
}

graph path <from_skill> <to_skill>

graph path <from_skill> <to_skill>
命令

Find the shortest dependency path between two skills.
bash
python3 "$(pwd)/skills/skill-system-graph/scripts/graph_cli.py" path skill-system-memory skill-system-postgres [--max-depth 10] [--format json|text]
JSON shape:
json
{
  "from_skill": "skill-system-memory",
  "to_skill": "skill-system-postgres",
  "path": ["skill-system-memory", "skill-system-router", "skill-system-postgres"],
  "found": true,
  "max_depth": 10
}
查找两个技能之间的最短依赖路径。
bash
python3 "$(pwd)/skills/skill-system-graph/scripts/graph_cli.py" path skill-system-memory skill-system-postgres [--max-depth 10] [--format json|text]
JSON格式：
json
{
  "from_skill": "skill-system-memory",
  "to_skill": "skill-system-postgres",
  "path": ["skill-system-memory", "skill-system-router", "skill-system-postgres"],
  "found": true,
  "max_depth": 10
}

graph impact <skill_name>

graph impact <skill_name>
命令

Return transitive dependents (all skills that (transitively) depend on the given one).
bash
python3 "$(pwd)/skills/skill-system-graph/scripts/graph_cli.py" impact skill-system-postgres [--max-depth 10] [--format json|text]
JSON shape:
json
{
  "skill": "skill-system-postgres",
  "impact": [
    {"impact_skill": "skill-system-memory", "depth": 1, "path": ["skill-system-memory", "skill-system-postgres"]},
    {"impact_skill": "skill-system-gui", "depth": 2, "path": ["skill-system-gui", "skill-system-memory", "skill-system-postgres"]}
  ],
  "impact_count": 2,
  "max_depth": 10,
  "status": "ok"
}
返回指定技能的所有传递依赖项（即所有直接或间接依赖该技能的技能）。
bash
python3 "$(pwd)/skills/skill-system-graph/scripts/graph_cli.py" impact skill-system-postgres [--max-depth 10] [--format json|text]
JSON格式：
json
{
  "skill": "skill-system-postgres",
  "impact": [
    {"impact_skill": "skill-system-memory", "depth": 1, "path": ["skill-system-memory", "skill-system-postgres"]},
    {"impact_skill": "skill-system-gui", "depth": 2, "path": ["skill-system-gui", "skill-system-memory", "skill-system-postgres"]}
  ],
  "impact_count": 2,
  "max_depth": 10,
  "status": "ok"
}

graph refresh

graph refresh
命令

Rebuild and sync the graph from 
SKILL.spec.yaml
in one command.
bash
python3 "$(pwd)/skills/skill-system-graph/scripts/graph_cli.py" refresh [--skills-dir skills] [--force] [--format json|text]
JSON shape:
json
{
  "status": "ok",
  "parsed": 12,
  "inserted": 12,
  "updated": 0,
  "skipped": 0,
  "removed": 0
}
通过一条命令从
SKILL.spec.yaml
重建并同步图谱。
bash
python3 "$(pwd)/skills/skill-system-graph/scripts/graph_cli.py" refresh [--skills-dir skills] [--force] [--format json|text]
JSON格式：
json
{
  "status": "ok",
  "parsed": 12,
  "inserted": 12,
  "updated": 0,
  "skipped": 0,
  "removed": 0
}

Internal helper operations

内部辅助操作

  • parse-specs
    : scans 
    SKILL.spec.yaml
    , builds canonical graph model, returns parse summary.
  • sync-graph
    : persists graph model into PostgreSQL with hash-aware upserts.
The orchestrator (
skill-system-router
) is expected to use these primitives to keep data fresh before calls that require persistence guarantees.
  • parse-specs
    ：扫描
    SKILL.spec.yaml
    文件，构建标准图谱模型，返回解析摘要。
  • sync-graph
    ：通过哈希感知的更新插入操作，将图谱模型持久化到PostgreSQL中。
编排器（
skill-system-router
）应在需要持久化保证的调用前，使用这些基础操作来保持数据的最新状态。

Dependency Direction and Effect

依赖方向与影响

This skill delegates to no further skill for execution (
delegates_to: []
) and depends on:
  • skill-system-postgres
    for persisted graph storage
  • skill-system-behavior
    for spec schema and behavior tooling context
该Skill在执行时无需委托给其他Skill（
delegates_to: []
），它依赖于：
  • skill-system-postgres
    ：用于持久化图谱存储
  • skill-system-behavior
    ：提供规范 schema 和行为工具上下文

Notes for AI Use

AI使用注意事项

  • Prefer 
    --format json
    in automation scripts.
  • Use text mode for quick operator inspection during debugging.
  • Treat 
    graph refresh
    as the authoritative source update step before long-running dependency calculations.
skill
{
  "schema_version": "2.0",
  "id": "skill-system-graph",
  "version": "0.1.0",
  "capabilities": ["graph-navigation", "behavior-query", "dependency-analysis"],
  "effects": ["fs.read", "db.read", "db.write"],
  "operations": {
    "parse-specs": {
      "description": "Parse all skill SKILL.spec.yaml files into a normalized graph model.",
      "input": {
        "skills_dir": {"type": "string", "required": false, "description": "Root directory that contains skills/"},
        "include_invalid": {"type": "boolean", "required": false, "description": "Include malformed spec metadata in the parse report"}
      },
      "output": {
        "description": "Normalized graph model plus parse report.",
        "fields": {"graph": "object", "parse_report": "object"}
      },
      "entrypoints": {
        "agent": "Use scripts/graph_core.py parse helpers to scan SKILL.spec.yaml files only"
      }
    },
    "sync-graph": {
      "description": "Sync the normalized graph model into PostgreSQL graph tables.",
      "input": {
        "skills_dir": {"type": "string", "required": false, "description": "Root directory that contains skills/"},
        "force": {"type": "boolean", "required": false, "description": "Force rebuild ignoring cached hashes"}
      },
      "output": {
        "description": "Inserted, updated, skipped, and removed counters.",
        "fields": {"sync_result": "object"}
      },
      "entrypoints": {
        "agent": "Use scripts/graph_core.py sync helpers to upsert graph state into PostgreSQL"
      }
    },
    "show": {
      "description": "Display the full skill graph from the current spec-scan graph model.",
      "input": {
        "skills_dir": {"type": "string", "required": false, "description": "Root directory that contains skills/"},
        "format": {"type": "string", "required": false, "description": "Output format: json or text"}
      },
      "output": {
        "description": "Full graph view with nodes and edges.",
        "fields": {"graph_view": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/graph_cli.py", "show"],
        "windows": ["python", "{skill_dir}/scripts/graph_cli.py", "show"]
      }
    },
    "neighbors": {
      "description": "List direct neighbor skills for a target skill.",
      "input": {
        "skill_name": {"type": "string", "required": true, "description": "Skill id to inspect"},
        "format": {"type": "string", "required": false, "description": "Output format: json or text"}
      },
      "output": {
        "description": "Outgoing and incoming neighbors with edge types.",
        "fields": {"neighbors": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/graph_cli.py", "neighbors", "{skill_name}"],
        "windows": ["python", "{skill_dir}/scripts/graph_cli.py", "neighbors", "{skill_name}"]
      }
    },
    "path": {
      "description": "Find the shortest dependency path between two skills.",
      "input": {
        "from_skill": {"type": "string", "required": true, "description": "Source skill id"},
        "to_skill": {"type": "string", "required": true, "description": "Destination skill id"},
        "max_depth": {"type": "number", "required": false, "description": "Traversal depth guard"},
        "format": {"type": "string", "required": false, "description": "Output format: json or text"}
      },
      "output": {
        "description": "Shortest path list and found flag.",
        "fields": {"path_result": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/graph_cli.py", "path", "{from_skill}", "{to_skill}"],
        "windows": ["python", "{skill_dir}/scripts/graph_cli.py", "path", "{from_skill}", "{to_skill}"]
      }
    },
    "impact": {
      "description": "Find all transitive dependents for one skill.",
      "input": {
        "skill_name": {"type": "string", "required": true, "description": "Skill id whose dependents are requested"},
        "max_depth": {"type": "number", "required": false, "description": "Traversal depth guard"},
        "format": {"type": "string", "required": false, "description": "Output format: json or text"}
      },
      "output": {
        "description": "Transitive dependents with count plus depth/path metadata.",
        "fields": {"impact_result": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/graph_cli.py", "impact", "{skill_name}"],
        "windows": ["python", "{skill_dir}/scripts/graph_cli.py", "impact", "{skill_name}"]
      }
    },
    "refresh": {
      "description": "Rebuild graph from specs and refresh persistence in one command.",
      "input": {
        "skills_dir": {"type": "string", "required": false, "description": "Root directory that contains skills/"},
        "force": {"type": "boolean", "required": false, "description": "Force rebuild ignoring cached hashes"},
        "format": {"type": "string", "required": false, "description": "Output format: json or text"}
      },
      "output": {
        "description": "Parsed spec count plus sync counters.",
        "fields": {"refresh_result": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/graph_cli.py", "refresh"],
        "windows": ["python", "{skill_dir}/scripts/graph_cli.py", "refresh"]
      }
    }
  },
  "stdout_contract": {
    "last_line_json": true,
    "note": "CLI commands support stable JSON output for automation. Internal helper operations are agent-executed."
  }
}
  • 在自动化脚本中优先使用
    --format json
    参数。
  • 调试期间，使用文本模式便于操作人员快速查看。
  • 在执行长时间运行的依赖计算前，将
    graph refresh
    作为权威的源数据更新步骤。
skill
{
  "schema_version": "2.0",
  "id": "skill-system-graph",
  "version": "0.1.0",
  "capabilities": ["graph-navigation", "behavior-query", "dependency-analysis"],
  "effects": ["fs.read", "db.read", "db.write"],
  "operations": {
    "parse-specs": {
      "description": "Parse all skill SKILL.spec.yaml files into a normalized graph model.",
      "input": {
        "skills_dir": {"type": "string", "required": false, "description": "Root directory that contains skills/"},
        "include_invalid": {"type": "boolean", "required": false, "description": "Include malformed spec metadata in the parse report"}
      },
      "output": {
        "description": "Normalized graph model plus parse report.",
        "fields": {"graph": "object", "parse_report": "object"}
      },
      "entrypoints": {
        "agent": "Use scripts/graph_core.py parse helpers to scan SKILL.spec.yaml files only"
      }
    },
    "sync-graph": {
      "description": "Sync the normalized graph model into PostgreSQL graph tables.",
      "input": {
        "skills_dir": {"type": "string", "required": false, "description": "Root directory that contains skills/"},
        "force": {"type": "boolean", "required": false, "description": "Force rebuild ignoring cached hashes"}
      },
      "output": {
        "description": "Inserted, updated, skipped, and removed counters.",
        "fields": {"sync_result": "object"}
      },
      "entrypoints": {
        "agent": "Use scripts/graph_core.py sync helpers to upsert graph state into PostgreSQL"
      }
    },
    "show": {
      "description": "Display the full skill graph from the current spec-scan graph model.",
      "input": {
        "skills_dir": {"type": "string", "required": false, "description": "Root directory that contains skills/"},
        "format": {"type": "string", "required": false, "description": "Output format: json or text"}
      },
      "output": {
        "description": "Full graph view with nodes and edges.",
        "fields": {"graph_view": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/graph_cli.py", "show"],
        "windows": ["python", "{skill_dir}/scripts/graph_cli.py", "show"]
      }
    },
    "neighbors": {
      "description": "List direct neighbor skills for a target skill.",
      "input": {
        "skill_name": {"type": "string", "required": true, "description": "Skill id to inspect"},
        "format": {"type": "string", "required": false, "description": "Output format: json or text"}
      },
      "output": {
        "description": "Outgoing and incoming neighbors with edge types.",
        "fields": {"neighbors": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/graph_cli.py", "neighbors", "{skill_name}"],
        "windows": ["python", "{skill_dir}/scripts/graph_cli.py", "neighbors", "{skill_name}"]
      }
    },
    "path": {
      "description": "Find the shortest dependency path between two skills.",
      "input": {
        "from_skill": {"type": "string", "required": true, "description": "Source skill id"},
        "to_skill": {"type": "string", "required": true, "description": "Destination skill id"},
        "max_depth": {"type": "number", "required": false, "description": "Traversal depth guard"},
        "format": {"type": "string", "required": false, "description": "Output format: json or text"}
      },
      "output": {
        "description": "Shortest path list and found flag.",
        "fields": {"path_result": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/graph_cli.py", "path", "{from_skill}", "{to_skill}"],
        "windows": ["python", "{skill_dir}/scripts/graph_cli.py", "path", "{from_skill}", "{to_skill}"]
      }
    },
    "impact": {
      "description": "Find all transitive dependents for one skill.",
      "input": {
        "skill_name": {"type": "string", "required": true, "description": "Skill id whose dependents are requested"},
        "max_depth": {"type": "number", "required": false, "description": "Traversal depth guard"},
        "format": {"type": "string", "required": false, "description": "Output format: json or text"}
      },
      "output": {
        "description": "Transitive dependents with count plus depth/path metadata.",
        "fields": {"impact_result": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/graph_cli.py", "impact", "{skill_name}"],
        "windows": ["python", "{skill_dir}/scripts/graph_cli.py", "impact", "{skill_name}"]
      }
    },
    "refresh": {
      "description": "Rebuild graph from specs and refresh persistence in one command.",
      "input": {
        "skills_dir": {"type": "string", "required": false, "description": "Root directory that contains skills/"},
        "force": {"type": "boolean", "required": false, "description": "Force rebuild ignoring cached hashes"},
        "format": {"type": "string", "required": false, "description": "Output format: json or text"}
      },
      "output": {
        "description": "Parsed spec count plus sync counters.",
        "fields": {"refresh_result": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/graph_cli.py", "refresh"],
        "windows": ["python", "{skill_dir}/scripts/graph_cli.py", "refresh"]
      }
    }
  },
  "stdout_contract": {
    "last_line_json": true,
    "note": "CLI commands support stable JSON output for automation. Internal helper operations are agent-executed."
  }
}