* feat(skill): replace skill-pack with per-harness conditional compiler
skillbuild compiles the skill tree into per-target harness builds:
- <!-- skill:if omp,!claude --> blocks include text only for matching
targets; name-list conditions only, no else/nesting, fail-loud on
unknown targets and unpaired/nested directives
- fence-aware: directive-looking lines inside code fences are literal
- layout is the filesystem; tree root configured in skillproj.toml
- post-build assertion: zero directive residue, SKILL.md frontmatter
name check
Migration to the new model:
- docs/skill/ becomes the self-contained source root (SKILL.md,
references/, generated api/stdlib/core/guides now under
references/docs/; SDK_OVERVIEW/LICENSE/inspect are ordinary tree
files)
- auto_docs_gen output redirected into the tree (docs/api ->
docs/skill/references/docs/api, likewise stdlib)
- skills/simplecadapi/ is now the compiled omp target output;
dist/generic/simplecadapi the generic target
- dropped skill-pack entry point (plus dangling evolve/make-export
entries and their orphaned test), release workflow builds via
skillbuild + tar; README updated
First real conditional block: harness reading paths in SKILL.md
(skill:// mount on omp vs disk-relative on generic).
Verified: 59 tests pass (skillbuild 31, auto_docs_gen 19, persistence
regression 9); both targets build; outputs residue-clean; full suite
collects (1376 tests).
* refactor(tools): auto_docs_gen moves out of the installed package
tools/ scripts are repo-checkout dev scripts, not packaged CLIs:
- auto_docs_gen.py now lives in tools/ beside the other generators;
auto_tools/ package removed entirely
- path resolution simplifies: repo root = parent of tools/, fail-loud
if pyproject.toml missing; site-packages/cwd fallback branches were
dead code once the script stopped shipping in the wheel
- auto-docs-gen console script dropped from [project.scripts];
release.yml and README invoke python tools/auto_docs_gen.py
- MANIFEST.in stale src/auto_tools include removed; CadQuery-free
runtime scan no longer needs the auto_tools filter
- run_examples.py retired (user removal): README example-runner text
updated to direct examples/ scripts; dangling runner-contract test
(runpy.run_path into the deleted script) removed
Verified: 53 tests pass (auto_docs_gen + skill_build + ocp runtime
scan) and test_example_model_contract passes; regeneration from
tools/ is byte-identical (zero docs drift).
* refactor(skill): strip harness and build-tool content from the skill tree
The skill is plain harness-neutral content again:
- SKILL.md 'Reading skill files' section removed (the omp skill://
mount block and its !omp complement were the only conditional
blocks; the tree compiles identically for every target now)
- references/README.md: build-tool meta removed ('per-harness
conditional compilation', skillbuild packaging/validation claims —
link validation was never implemented, so the claim was false)
- live test now asserts the tree stays harness-neutral (zero blocks)
- skillproj.toml targets aligned with the user's output table
(omp -> skills/simplecadapi-omp, opencode -> skills/simplecadapi-opencode;
leftover 'generic' entry had no output and failed the build)
- compiled outputs are regenerable artifacts: skills/simplecadapi/
untracked from git, skills/simplecadapi-*/ gitignored, release.yml
and README build via skillbuild and tar the omp output directly
(bsdtar has no --transform; inner dir keeps its suffixed name)
Verified: 49 tests pass; both targets build 372 files with zero
conditional blocks; no omp/conditional/directive residue in the tree
or outputs.
* chore(docs): drop stale architecture review and design notes
3.3 KiB
Skill Documentation Structure
This directory is the task-routed skill layer. It sits between the SDK's generated
docs/skill/
domains/ stable, reusable capability modules
workflows/ goal-oriented compositions of domains
discipline/ mechanical modeling knowledge and invariants
Layering
SKILL.md (generated router)
→ workflows/<scenario>.md what to run, in what order
→ domains/<capability>.md capability boundaries and API groups
→ discipline/<topic>.md why: modeling reasoning and invariants
→ docs/api|stdlib|core/ exact signatures (auto-generated)
Load top-down and only what the current task triggers. No task reads the whole API index up front.
Domains
| Domain | Owns |
|---|---|
requirement-refinement |
request → brief (dimensions, units, datums, validation targets) |
part-modeling |
single-solid parts: primitives, profiles, features, booleans, transforms |
sketch-and-features |
declarative constrained sketches and promotion |
assembly-and-product |
parts, placements, connectors, constraints, @part/@assemble, cache, .scadpkg |
standard-parts |
stdlib gears, ring gears, racks, cycloidal discs, bearings |
step-inspection |
STEP/BREP evidence, comparison, reconstruction evaluation |
export-and-translation |
STEP/STL/OBJ/MJCF export, FreeCAD/Fusion/SolidWorks translation |
Cross-cutting capabilities — QL grounding, semantic tags, GraphSession replay, units/tolerances, incremental validation — are not routing targets; each workflow pulls them in as conditions require.
Workflows
| Workflow | Scenario |
|---|---|
single-part-modeling |
one physical part from brief to validated solid |
sketch-feature-modeling |
constraint-driven profile as the design intent |
assembly-product-build |
multi-part product with connectors/constraints and package capture |
step-reconstruction |
editable rebuild from a target STEP with tiered acceptance |
standard-part-assembly |
mechanisms composed from stdlib components |
export-and-translation |
downstream formats from a validated package |
Each workflow states: goal/scope, task decomposition (required/optional domains, artifacts, validation gates, repair routes), ordered steps with the domain/discipline/API references to load, failure routes, and deliverables.
Discipline
Modeling reasoning and invariants, independent of any single API:
mechanical-modeling (construction strategy), requirement-and-cad-brief
(input precedence, drawings), datums-and-coordinate-systems,
feature-ordering (operation order and boolean tool geometry),
assembly-positioning (mating/motion intent), geometric-validation
(validity vs volume, incremental grounding, spec-driven measurement),
failure-and-repair (failure classes and the repair loop),
manufacturing-boundaries (defaults and what geometry never proves).
Authoring rules
- Domain files say what a capability owns, when to use it, when to route elsewhere, and which API pages to read — they do not restate signatures.
- Workflow files compose domains; they never duplicate discipline content.
- Discipline files state reasoning and invariants; they avoid CLI- or tool-specific detail that belongs in domains/workflows.
- Every
references/...path written here must exist in the packaged skill.