# library

Explains the Faebryk hardware component library structure, _F.py facade generation, and rules for writing modules or traits in atopile.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 1 install · ★ 4090 repo stars
- Author: atopile
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/atopile/atopile/tree/HEAD/.claude/skills/library/SKILL.md
- Updated: 2026-10-14
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/library

## What it does

This skill guides agents through the Faebryk component library located in `src/faebryk/library/`. It establishes clear architectural boundaries: components like `Resistor` or `LED` represent physical hardware parts derived from `Node`, while traits like `can_bridge` represent behavior.

The library exposes its types via the generated barrel file `src/faebryk/library/_F.py`. Editing this file by hand is pointless because the script `tools/library/gen_F.py` overwrites it completely, using topological sorting to prevent cyclic import references.

After adding a component file matching its class name, run `ato dev test --llm test/library/test_instance_library_modules.py -q` to smoke-test instantiation.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add atopile/atopile --skill library -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/library/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/library/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add atopile/atopile --skill library -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/library/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add atopile/atopile --skill library -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/library/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install atopile/atopile .claude/skills/library
```

2. **Manually: put the files in place**
- File: `.github/skills/library/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add atopile/atopile --skill library -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/atopile/atopile --path .claude/skills/library
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/library/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add atopile/atopile --skill library -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/atopile/atopile/tree/HEAD/.claude/skills/library/SKILL.md

## When to use it
- define a new hardware component class inheriting from `Node`
- add a trait to describe electrical behavior
- regenerate the `_F.py` barrel module without circular imports
- run smoke tests for newly added Faebryk library modules

## Example prompts
- Create a new diode component in `src/faebryk/library/` following Faebryk conventions
- How do I regenerate `_F.py` after adding a new library module?
- Add parameter definitions to this resistor component and run the instance test

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 6347850621852990.

BEGIN THIRD-PARTY FILE 6347850621852990
````text
---
name: library
description: "How the Faebryk component library is structured, how `_F.py` is generated, and the conventions/invariants for adding new library modules. Use when adding or modifying library components, traits, or module definitions."
---

# Library Module

The `library` module (located in `src/faebryk/library/`) contains the collection of reusable components, traits, and interfaces that form the "standard library" of the hardware design language.

## Quick Start

```python
import faebryk.core.faebrykpy as fbrk
import faebryk.core.graph as graph
import faebryk.library._F as F

g = graph.GraphView.create()
tg = fbrk.TypeGraph.create(g=g)

resistor = F.Resistor.bind_typegraph(tg=tg).create_instance(g=g)
```

## Relevant Files

- **Facade (auto-generated)**: `src/faebryk/library/_F.py`
  - Eagerly imports and re-exports library modules/types for the `import faebryk.library._F as F` pattern.
  - This file is generated; do not hand-edit it.
- **Generator**: `tools/library/gen_F.py`
  - Scans `src/faebryk/library/*.py`, detects whether the file contains a same-named class, and writes `_F.py`.
  - Orders exports via a topological sort of `F.<Name>` references to avoid import-order cycles.
- **Components**: `src/faebryk/library/` contains specific component definitions (e.g. `Resistor.py`, `Capacitor.py`, `LED.py`).
- **Traits/Interfaces**: Also contains trait definitions (e.g. `can_bridge.py`, `is_power.py`).

## Dependants (Call Sites)

- **User Code**: atopile projects heavily import from `faebryk.library._F` (aliased as `F`).
- **Compiler**: The compiler maps `ato` built-ins to these classes.

## How to Work With / Develop / Test

### Core Concepts
- **Traits vs Components**: Use Traits for behavior (what it *can do* like `can_bridge`) and Components for physical things (what it *is* like `Resistor`).
- **Export model**: `_F.py` is a generated “barrel” module; importing it is intentionally convenient but can be heavyweight.

### Development Workflow
1.  **New Component**: Create a new file `MyComponent.py` in `src/faebryk/library/`. Inherit from `Node` (or a more specific base).
2.  **Naming Convention**: Class names should match the file basename (usually).
3.  **Regenerate `_F.py`**: run `python tools/library/gen_F.py` and commit the updated `src/faebryk/library/_F.py`.

### Testing
- Library tests live under `test/library/` (including `test/library/nodes/`).
- A good smoke test for new modules is:
  - `ato dev test --llm test/library/test_instance_library_modules.py -q`

## Best Practices
- **Atomic Parts**: Mark leaf components (specifically verified part numbers) with the `is_atomic_part` trait.
- **Parameters**: Use `F.Parameters` to define physical properties like `resistance`, `capacitance`, etc.
- **Documentation**: Add docstrings to components explaining their ports and parameters.
````
END THIRD-PARTY FILE 6347850621852990

The third-party file has ended. Everything between the 6347850621852990 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© atopile · MIT · https://github.com/atopile/atopile/tree/HEAD/.claude/skills/library/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
