CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repository is

This is a documentation/prompt-engineering repository, not a codebase with source files to build, lint, or test. It's a library of "skills" — structured Markdown files that teach an AI agent how to correctly call the SkyCiv API (structural engineering modeling, analysis, drawing, and reporting) instead of guessing at request shapes and units. There is no build system, package manifest, linter, or test suite — the only artifacts are SKILL.md files and their supporting assets.

Read CHANGELOG.md before making changes. It lists the significant changes to this repo, newest first, so you can tell a settled convention from one that moved recently. Add a row to it for any significant change you make.

Repository structure

Each top-level folder is one self-contained skill:

<skill-name>/
  SKILL.md       # required — skill instructions and API reference
  assets/         # optional — example inputs, catalogues, templates

Current skills: skyciv-api-v3, s3d-api, s3d-apps, analysis-results, cloudcad-api, load-gen-api, load-combinations, run-quick-design, build-quick-design-calculator, baseplate, foundation-api, renderer, schema-agent, section-selector, qa-engineer, skill-writer. There is also a prototypes/ folder holding runnable example apps built on these skills (Node/Express), not SKILL.md files — currently prototypes/glass-balustrade-configurator and prototypes/truss-designer. Note: a reporting-engineer skill is planned but the folder does not yet exist in this repo — don't assume it does.

Some SKILL.md files have YAML frontmatter (name, description, argument-hint) so agent harnesses can discover them; others (e.g. skyciv-api-v3, s3d-api, load-gen-api, run-quick-design) are documentation-only and omit it. Match the style of the skill you're editing.

How the skills compose

Skills are designed to be chained in a typical structural workflow:

schema-agent          → interpret a floor plan into a structural schema
  ↓
s3d-api / cloudcad-api → build the 3D model / 2D drawing
  ↓
load-gen-api           → pull wind / snow / seismic loads for the site
  ↓
load-combinations      → factor those loads into code-correct combinations on the model
  ↓
s3d-api                → solve
  ↓
analysis-results       → fetch and interpret the results
  ↓
s3d-api (S3D.design)   → steel/CFS/timber member design via S3D.design.member.check (preferred where the code is supported);
                         run-quick-design for concrete, connections, and codes Member Design does not cover;
                         baseplate for column base plate / anchor bolt checks
  ↓
renderer               → visualize the model and results
  ↓
qa-engineer            → independent review of the results

skyciv-api-v3 is the foundation every *-api skill depends on — it covers auth, session management (S3D.session.start), and the shared request/response envelope ({ auth, options, functions }) that every other API skill's calls are built on. Any skill that calls the SkyCiv API states this prerequisite at the top of its SKILL.md.

• s3d-api — full s3d_model JSON schema; S3D.model, S3D.results, S3D.file, S3D.SB, S3D.design namespaces. S3D.design.member.check is the preferred method for steel, cold-formed steel and timber member design whenever it supports the design code. Concrete is the exception: always use the run-quick-design concrete calculators, never S3D.design.rc.check. It handles load combinations, effective lengths/bracing and grouping automatically. Only use run-quick-design member calculators when Member Design doesn't cover the code or edition. The rule and mapping table are in the "S3D.design Functions" section.
• s3d-apps — sits alongside this pipeline, not inside it: builds custom client-side mini-apps that run embedded inside the S3D application itself (S3D.structure.*, S3D.graphics.*, S3D.API.S3D2API), reusing the same s3d_model schema as s3d-api but with no auth/session calls (the app runs inside an already-open session).
• analysis-results — documentation-only skill for the analysis results object returned after a solve (reactions, per-station member/plate forces/stresses/displacements, min/max summaries); covers both the S3D.results.get API path and the S3D.solver.isSolved / S3D.results.getAll / S3D.API.output.S3D2API client-side S3D App path. No API namespace of its own — cross-linked from s3d-api and s3d-apps rather than duplicated there.
• cloudcad-api — 2D CAD drawing schema (cad_data); cloudcad.model.create / cloudcad.file.save. Detail lives in references/ (elements, pages & title blocks, S3D mapping); scripts/cad_helpers.js builds a page-wrapped drawing and lints it. Live-verified behaviour worth knowing before touching it: create opens its own session (no S3D.session.start needed) and accepts any payload with status: 0, so a success status proves nothing; a failing call returns a response.screenshot of the headless editor, which is the only way to see a render; save never returns public_link; file.open reports success even for missing files.
• load-gen-api — wind/snow/seismic lookups via standalone.loads. Always open the session with standalone.loads.start, not S3D.session.start — confirmed against the live API that the latter breaks standalone.loads.getLoads (a generic, non-obvious failure on the second call, not on session start itself). If an app needs both an S3D model and a load-gen-api lookup, run them as separate sessions, each with its own matching *.start call.
• load-combinations — documentation-only, single-file skill for the s3d_model load-combination data model (load_combinations, load_cases, load_combination_settings), with the generator's factor tables for ASCE 7-22 LRFD/ASD, AS/NZS 1170.0, NBCC 2020, EN 1990 and IS 800 (no assets/; the old JSON examples were removed because they held unusable wind combos). Combos are written directly into the model consumed by s3d-api, with the 7000-load-combination-generator Quick Design calculator as an optional generator. Behaviour verified live that's worth knowing before touching it: load_cases values must be the code's short symbols (D, Qdo, Wu, …), because "Dead: dead" shows every group as Dead in the UI; load_combination_settings.country/code pick the standard the UI reads (the default is ASCE-7-2022-LRFD); a combo without the SW1 key applies no self-weight; unknown group keys are silently ignored; the generator crashes on "Please Select" and without multi_dropdown_1; for NZ it takes AS-1170.0-2002 (with country_input: "australia", as the S3D UI sends), while the model keeps AS/NZS-1170.0-2002.
• baseplate — steel column base plate / anchor bolt / weld design via standalone.baseplate. Opens with its own standalone.baseplate.start (a check after S3D.session.start is rejected). Per-code value lists and factors live in baseplate/references/<code>.md, loaded only for the chosen design_code. Consumes base forces from an s3d-api solve (via analysis-results) as its loads. Live-verified behaviour worth knowing before touching it: invalid grade/diameter strings are silently replaced with defaults (status: 0), and a failing detailing check or a non-zero My hangs the call to the ~45 s timeout instead of returning an error.
• run-quick-design — a separate REST endpoint (POST https://qd.skyciv.com/run, its own API-token auth, not the skyciv-api-v3 envelope) that runs any of 154 standalone calculators by UID. Calling only; anything about writing a calc pack belongs in build-quick-design-calculator.
• build-quick-design-calculator — the authoring counterpart to run-quick-design: how to write a Quick Design calc pack (config.json input form, calculate.js logic/report, ui.js graphics, optional s3d_integration.js) and upload it to the Build Your Own Calculator builder. No API auth or envelope — the code runs on SkyCiv's servers. Full SkyCiv Quick Design docs are bundled under its assets/documentation/. S3D integration (s3d_integration.js, the hidden analysis_results custom_object input, hide_in_s3d, and the calculate.js switch that prefers analysis_results over the manual loads) is in references/s3d-integration.md, which supersedes the example in the bundled quick-design-s3d.md.
• renderer — client-side JS library (SKYCIV.renderer), not a server API; visualizes an s3d_model fetched via the API.
• schema-agent — vision/DXF interpretation persona feeding s3d-api.
• section-selector — section library lookup and injection helper for s3d-api; maps country/material/role to the correct load_section path from section_tree.json, or builds concrete sections as template-shape objects. Used whenever a model needs real section geometry.
• qa-engineer — independent-reviewer persona/checklist, not an API skill.

run-quick-design asset layout

This skill's calculator catalogue lives at run-quick-design/assets/catalogue.md, indexed by UID and grouped by category (Foundation, Steel, Concrete, Timber, Aluminium, Connections, Loads, etc.). Each catalogue entry links to a per-calculator folder under run-quick-design/assets/<uid>/ containing exactly:

schema.json         # input/output JSON schema for that calculator
sample_input.json   # minimal working example input
sample_output.json  # corresponding example output

When adding a new calculator, add all three files under a new assets/<uid>/ folder and add a row to catalogue.md in the correct category table.

Conventions when editing or adding a skill

These are enforced project conventions (from .github/copilot-instructions.md) — follow them when authoring or modifying any SKILL.md:

• Always update README.md when adding a new skill folder — add a row to the skills table, keeping it sorted alphabetically by folder name.
• State the prerequisite first: if a skill depends on S3D.session.start or another skill, call that out near the top of SKILL.md.
• Use tables for API parameters, not prose lists.
• Include a minimal working example: the smallest JSON payload that demonstrates the core use case.
• Cross-link related skills (e.g. s3d-api → skyciv-api-v3).
• Always state units (metric vs. imperial) and which field controls them — these skills exist specifically to stop agents guessing at units.
• Keep skill descriptions in README.md to a single line, non-technical enough for a first-time reader.

These skills are kept in sync with the live SkyCiv API (api/v3). If you notice a schema, example, or endpoint that looks stale, treat the live API docs as the source of truth over what's written here.

Prototyping tips

When prototyping a solution (or if vibe coding a solution) it's a good idea to stick to the following rules:

• Don't use result_filter key in the S3D.model.solve space unless you're 100% sure it will work
• Stick to a shorter timeout in the options key for the API (or leave as default), when prototyping if things go wrong it's easier to identify and test if things don't take >30s to fail.
• Don't call S3D.results.getAnalysisReport by default as part of a solve/results pipeline. It re-solves the model and renders every section across every load combination - slow (60-90s+, often timing out) - for a PDF report that's rarely used and usually isn't even surfaced in the app's UI. Only wire it up behind its own explicit button/endpoint if the user actually asks for a downloadable report, the same way a CAD-drawing generation step is kept separate from the main analyze call.
• If we're missing any key inputs that you would recommend, please let us know before you start coding. It's best to clarify any missing inputs. For example, in the wind load generator you will need certain key information - if the user misses this, please let them know before building the prototype.
• Collecting API credentials for standalone prototypes (a web app of our own, running outside the SkyCiv platform). Rather than the API credentials needing to be collected via .env, can you please:
  1. Have a settings button that collects this from the UI
  2. Stores in the localStorage so they don't have to continually add these keys
  3. If no key is provided, show the red bar and the settings popup prompting them to input this information
  4. API keys can be collected by logging in and visiting https://platform.skyciv.com/api please put this information in the popup
• This does NOT apply to in-app solutions (an S3D App or a S3D.UI.leftMenu panel — anything built on the s3d-apps skill). Those run inside a session the user is already signed in to, so never show them a settings/API-key popup: read the credentials with SKYCIV_UTILS.currentUser.getApiAuth(), which returns { "username": "example@skyciv.com", "key": "ExAmPlE" }. See the "Authentication" section of s3d-apps/SKILL.md.
• In-app solutions must also build their UI from Semantic UI components throughout (inputs, dropdowns, checkboxes, tabs, tables, messages — not just buttons), since S3D itself is Semantic UI. See the "UI" section of s3d-apps/SKILL.md.
• In-app solutions must pick sections from SB.library.getTree(), never from typed-in text. load_section is an exact-string-match lookup against the section library, so a typed path is a silent failure waiting to happen. The tree is available client-side and synchronously, in the same 4-level shape the path needs — drive cascading dropdowns off it. See the "Choosing sections" section of s3d-apps/SKILL.md.

Whenever a prototype is improved by the user, please also consider: is this a blind spot of the skills? Should this be included in the relevant skill to ensure the next prototype doesn't face this same issue.

User Context

• Engineers like transparency, so if you're going to transfer data, or can show some partial results, I would build that into the UI. It's handy to have both levels: a key results (for example critical utility ratio) AND results along the way + an easy way to see what key values went into subsequent API calls.
• Accordions of tabulated data is a nice clean way you can show this level of detail without cluttering up the user interface