sexp

Name: sexp
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: Plug-and-play
External API key: Not required
Operating systems: Unspecified (assume cross-platform)
Runtime requirements: 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 sexp.preview

---
name: sexp
description: How the Zig S-expression engine and typed KiCad models work, how they are exposed to Python (pyz…
category: other
runtime: Python
---

# sexp output preview

## PART A: Task fit
- Use case: How the Zig S-expression engine and typed KiCad models work, how they are exposed to Python (pyzig_sexp), and the invariants around parsing, formatting, and freeing. Use when working with KiCad file parsing, S-expression generation, or layout sync..
- 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 S-expression engine and typed KiCad models work, how they are exposed to Python (pyzig_sexp), and the invariants around parsing, formatting, and freeing. Use when working with KiCad file parsing, S-expression generation, or layout sync.”.
- **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: sexp
description: How the Zig S-expression engine and typed KiCad models work, how they are exposed to Python (pyz…
category: other
source: atopile/atopile
---

# sexp

## When to use
- How the Zig S-expression engine and typed KiCad models work, how they are exposed to Python (pyzig_sexp), and the inva…
- 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 "sexp" {
  input      -> user goal + target files + boundaries + acceptance criteria
  context    -> Quick Start / Relevant Files / Dependants (Call Sites)
  rules      -> SKILL.md triggers / order / output contract
  runtime    -> 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 S-expression engine and typed KiCad models work, how they are exposed to Python (pyzig_sexp), and the invariants aro…
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 sexp 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.

Sexp Module

The sexp subsystem provides:

a fast S-expression tokenizer/parser/pretty-printer in Zig, and
typed Zig models for KiCad formats (PCB, footprint, netlist, symbol, schematic, fp_lib_table), exposed to Python via the pyzig_sexp extension module.

Source-of-truth docs and code:

src/faebryk/core/zig/README.md (high-level overview)
src/faebryk/core/zig/src/sexp/* (tokenizer/AST/structure)
src/faebryk/core/zig/src/python/sexp/sexp_py.zig (Python API + critical memory rules)

Quick Start

from pathlib import Path
from faebryk.libs.kicad.fileformats import kicad

pcb = kicad.loads(kicad.pcb.PcbFile, Path("board.kicad_pcb"))
_text = kicad.dumps(pcb)

Relevant Files

Zig core:
- src/faebryk/core/zig/src/sexp/tokenizer.zig (tokenization + line/column tracking)
- src/faebryk/core/zig/src/sexp/ast.zig (SExp tree + KiCad pretty formatting)
- src/faebryk/core/zig/src/sexp/structure.zig (decode/encode + error context)
- src/faebryk/core/zig/src/sexp/kicad/* (typed KiCad models)
Python extension entrypoint:
- src/faebryk/core/zig/src/python/sexp/init.zig (exports PyInit_pyzig_sexp)
- src/faebryk/core/zig/src/python/sexp/sexp_py.zig (module + type binding generation)
Generated Python stubs (what users “see”):
- src/faebryk/core/zig/gen/sexp/*.pyi
Convenience wrapper used throughout the codebase:
- src/faebryk/libs/kicad/fileformats.py (namespaces modules + caching + loads/dumps)

Dependants (Call Sites)

src/faebryk/libs/kicad/fileformats.py (primary integration layer)
KiCad exporters and layout sync:
- src/faebryk/exporters/pcb/kicad/*
- src/faebryk/exporters/pcb/layout/layout_sync.py
KiCad plugin workflow: src/atopile/kicad_plugin/*

How to Work With / Develop / Test

Core Concepts

Two-level model:
- raw SExp parsing/formatting (tokenizer.zig, ast.zig)
- typed KiCad decoding/encoding (structure.zig + sexp/kicad/*.zig)
Python API shape: the extension exposes per-format modules (e.g. pcb, netlist) with:
- module-level loads(data: str) -> File
- module-level dumps(file: File) -> str
- File.free(...) for releasing Zig-owned allocations
Convenience wrapper: faebryk.libs.kicad.fileformats.kicad wraps these modules and provides kicad.loads(...)/kicad.dumps(...).

Development Workflow

Modify Zig:
- parsing/formatting: src/faebryk/core/zig/src/sexp/*
- Python exposure: src/faebryk/core/zig/src/python/sexp/sexp_py.zig
Rebuild:
- ato dev compile (imports faebryk.core.zig)
If you changed the API:
- verify stubs under src/faebryk/core/zig/gen/sexp/*.pyi update accordingly
- adjust src/faebryk/libs/kicad/fileformats.py if needed

Testing

Best practical test is round-trip:
- load a known .kicad_pcb / .kicad_sch, dump it, and ensure KiCad accepts it (formatting-sensitive).
Zig unit tests (where present):
- zig test src/faebryk/core/zig/src/sexp/ast.zig
- zig test src/faebryk/core/zig/src/sexp/structure.zig

Best Practices

Prefer faebryk.libs.kicad.fileformats.kicad unless you explicitly need the raw module API.
Be mindful of shared-object caching in kicad.loads(...): path-based loads are cached and returned by reference (mutations are shared).

Memory & Lifetime Invariants (critical)

The Python bindings duplicate the input S-expression string into a persistent allocator because parsed structs contain pointers into the input buffer.

Implications:

Repeated loads(...) of large files can grow memory if you never call free(...) on the returned *File.
The convenience wrapper currently caches loaded objects by path; do not free(...) cached objects unless you also invalidate the cache.

Install command

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

npx skills add atopile/atopile/.claude/skills/sexp -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