AGENTS.md — using and contributing to Fabula as an AI agent

This file is written for autonomous AI agents (and the humans supervising them). If you are an agent that landed here because a user asked you to 3D print something or work with Bambu/slicer files, this repo is for you.

Using a skill

1. Read fabula.skills.json — a machine-readable index of every skill, its when_to_use triggers, keywords, entry point, scripts, and dependencies.
2. Open the relevant skill's SKILL.md. Its front-matter description states when it should trigger; its body is the workflow. Follow it.
3. The skill's references/ files are loaded on demand — read them when the workflow points you there (e.g. before designing geometry, or when a generated file misbehaves).
4. Do not assume the user's hardware. Bundled settings target a Bambu Lab P2S with a specific AMS/filament layout. Check for a project CLAUDE.md, ask the user, or check for a Bambu MCP connector to read live printer state before committing to settings.

The honesty rule (important)

You almost certainly cannot run the slicer from your sandbox. Never claim a generated file "is sliced" or "settings are applied" — only that they are written to the file. Ask the user to open it and confirm. When a file misbehaves, the fastest fix is to have the user Save Project As a reference file from their slicer and diff against it, rather than guessing repeatedly. This discipline is why the bambu-print writer is correct — every gotcha in references/gotchas.md was found via a reference diff, not by inspection.

Contributing a skill (via Pull / Merge Request)

Contributions from agents are explicitly welcome. To add or improve a skill:

1. Layout — one folder per skill under skills/<skill-name>/:

   skills/<skill-name>/
   ├── SKILL.md            # required: YAML front-matter (name, description) + workflow
   ├── scripts/            # optional: executable helpers (keep deps minimal; NumPy-only if possible)
   ├── references/         # optional: docs loaded on demand (design rules, format notes)
   └── assets/             # optional: templates, profiles

2. SKILL.md front-matter must have name and a description that says what it does AND when to trigger (be specific and a little "pushy" — agents tend to under-trigger skills).
3. Register it in fabula.skills.json (copy an existing entry; fill when_to_use, keywords, scripts, dependencies, tested_printer, status).
4. State what you verified and what you didn't. If you couldn't test on real hardware, say so in the skill's status. Prefer bundling a small self-test script over untested claims.
5. Keep secrets/models out. No serial numbers, account IDs, private model files, or anything in .gitignore. Scrub profile exports of personal identifiers.
6. Open a PR/MR with: what the skill does, what you tested, the printer/material it targets, and any known limitations. Small, focused PRs review faster.

See CONTRIBUTING.md for the full guidelines and review bar.

Safety

Read DISCLAIMER.md. If a request would produce something unsafe (e.g. settings that could damage the printer, or a part for a hazardous use), flag it to the user rather than silently proceeding.