graph

Name: graph
Author: atopile

Other Verified

Repo stars 3,367
License MIT
Author updated Live
Author repo atopile

Fluxly profile Facts only: domain, agents, trust score, runtime, permissions and network

Domain: Other
Compatible agents: Claude Code
Cursor
Cline
Codex
Windsurf
Gemini CLI

+20
Trust score: 94 / 100 · audit passed
Author / version / license: @atopile · MIT
Token usage: Lean
Setup complexity: Guided setup
External API key: Not required
Operating systems: macOS · Linux · Windows
Runtime requirements: Node.js · Python
Permissions: Read-only
Write / modify
Network behavior: Local-only
Install commands: 26 variants

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview graph.preview

---
name: graph
description: How the Zig-backed instance graph works (GraphView/NodeReference/EdgeReference), the real Python…
category: other
runtime: Node.js / Python
---

# graph output preview

## PART A: Task fit
- Use case: How the Zig-backed instance graph works (GraphView/NodeReference/EdgeReference), the real Python API surface, and the invariants around allocation, attributes, and cleanup. Use when working with low-level graph APIs, memory management, or building systems that traverse the instance graph..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Quick Start / Relevant Files / Dependants (Call Sites)” and do not present inference as author intent.

## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “How the Zig-backed instance graph works (GraphView/NodeReference/EdgeReference), the real Python API surface, and the invariants around allocation, attributes, and cleanup. Use when working with low-level graph APIs, memory management, or building systems that traverse the instance graph.”.
- **02** When the source has headings, the agent prioritizes “Quick Start / Relevant Files / Dependants (Call Sites)” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files; mostly runs locally; usually needs no extra API key.

## Running Rules
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options.

SKILL.md SKILL.md

---
name: graph
description: How the Zig-backed instance graph works (GraphView/NodeReference/EdgeReference), the real Python…
category: other
source: atopile/atopile
---

# graph

## When to use
- How the Zig-backed instance graph works (GraphView/NodeReference/EdgeReference), the real Python API surface, and the…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.

## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.

## Execution rules
- Organize steps around “Quick Start / Relevant Files / Dependants (Call Sites)” and keep inference separate from source facts.
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.

## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies.

Evidence boundary and execution chain

The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.

skill "graph" {
  input      -> user goal + target files + boundaries + acceptance criteria
  context    -> Quick Start / Relevant Files / Dependants (Call Sites)
  rules      -> SKILL.md triggers / order / output contract
  runtime    -> Node.js / Python | read files, write/modify files | mostly runs locally
  guardrails -> usually needs no extra API key + small-sample validation + diff/log review
  output     -> copyable result + checklist + next iteration
}

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: How the Zig-backed instance graph works (GraphView/NodeReference/EdgeReference), the real Python API surface, and the invariants…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Quick Start”, “Relevant Files”, “Dependants (Call Sites)”, “How to Work With / Develop / Test”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name graph directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Quick Start / Relevant Files / Dependants (Call Sites)” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

Graph Module

The faebryk.core.graph module is a thin Python wrapper around the Zig graph implementation.

Source-of-truth for behavior is:

Zig implementation: src/faebryk/core/zig/src/graph/graph.zig
Python bindings: src/faebryk/core/zig/src/python/graph/graph_py.zig
Public Python API surface (stubs): src/faebryk/core/zig/gen/graph/graph.pyi

Quick Start

from faebryk.core.graph import GraphView

g = GraphView.create()
try:
    _ = g.create_and_insert_node()
finally:
    g.destroy()

Relevant Files

Python wrapper/re-export: src/faebryk/core/graph.py
Zig graph core: src/faebryk/core/zig/src/graph/graph.zig
Zig → Python wrappers: src/faebryk/core/zig/src/python/graph/graph_py.zig
Generated type stubs: src/faebryk/core/zig/gen/graph/graph.pyi

Dependants (Call Sites)

src/faebryk/core/node.py (FabLL: nodes/traits are graph-backed)
src/atopile/compiler/gentypegraph.py (compiler constructs typegraphs/instances via graph APIs)
src/faebryk/core/graph_render.py (graph visualization)

How to Work With / Develop / Test

Mental Model

NodeReference / EdgeReference: value-like handles (UUIDs) into global backing storage in Zig.
GraphView: a membership + adjacency view over those references (per-view arena + maps + bitsets).
BoundNode / BoundEdge: “reference + owning GraphView pointer” wrappers used for traversal helpers.

Core Invariants (do not violate)

No direct constructors: GraphView(), NodeReference(), EdgeReference() are not meant to be called; use the exposed factory methods.
- GraphView.create()
- NodeReference.create(**attrs)
- EdgeReference.create(source=..., target=..., edge_type=..., **attrs)
Explicit cleanup: GraphView.create() allocates a Zig-side graph on the C allocator; it is freed only by GraphView.destroy().
- Do not rely on Python GC to reclaim Zig allocations.
Attribute limits: node/edge dynamic attributes are fixed-capacity in Zig (currently 6 entries). Exceeding this is a hard failure.
Edge type width: edge types are u8 in Zig; treat them as 0..255 in Python (hashing/modulo happens on the Zig side).
Self node exists: GraphView.init inserts a self_node; counts include it.

API Cheatsheet (matches `src/faebryk/core/zig/gen/graph/graph.pyi`)

from faebryk.core.graph import GraphView, Node, Edge

g = GraphView.create()
try:
    n1 = g.create_and_insert_node()           # -> BoundNode
    n2 = Node.create(name="n2")               # -> NodeReference (not inserted yet)
    bn2 = g.insert_node(node=n2)              # -> BoundNode

    e = Edge.create(source=n1.node(), target=bn2.node(), edge_type=7, name="link")
    _be = g.insert_edge(edge=e)               # -> BoundEdge
finally:
    g.destroy()

Debugging

GraphView.__repr__() prints GraphView(id=..., |V|=..., |E|=...) from Zig.
Graph wrapper has a stress test: python -m faebryk.core.graph (runs test_graph_garbage_collection).

Development Workflow

Zig changes: edit src/faebryk/core/zig/src/graph/*.
Rebuild: ato dev compile (imports faebryk.core.zig, which compiles in editable installs).
If you add/remove exposed methods: update the wrapper in src/faebryk/core/zig/src/python/graph/graph_py.zig and ensure stubs regenerate.

Testing

Key test entrypoints:

Python: python -m faebryk.core.graph
Zig: zig test src/faebryk/core/zig/src/graph/graph.zig

Install command

One-click installPick a runner, click Copy, paste into your terminal, press enter

npx skills add atopile/atopile/.claude/skills/graph -y

Open general install guide

View skill source

Works with

Claude Code
Cursor
Cline
Codex
Windsurf
Gemini
OpenCode
Roo Code
AAide
+Augment
GitHub Copilot
OpenClaw
KKiro
Junie
WWarp
Goose
Trae
Kilo Code
OpenHands
Amp
Zencoder
CContinue
AIAider
CodeBuddy
CodeGeeX
Replit Agent

Security audit

94 / 100

Verified

未声明 version。
未限定 allowed-tools，默认拥有全部工具权限。

Metadata

Source: github
atopile/atopile
License: MIT
中文

More by @atopile

Category & tags

Category Other