Repository navigation
Add Agent Skills for Magpylib users and contributors - #984
Closed
Alexboiboi wants to merge 4 commits into
Closed
Alexboiboi wants to merge 4 commits into
Alexboiboi wants to merge 4 commits into
Conversation
AI coding assistants write Magpylib code from pre-v5 memory: millimetres and millitesla, `magnetization` where v5 wants `polarization`. Nothing raises — the answer is simply wrong by a factor of 1e3 to 1e9. Adds an Agent Skill (https://agentskills.io) at `src/magpylib/.agents/skills/magpylib/`, so it travels inside the wheel and stays in sync with the installed version. Users pick it up with `uvx library-skills` (https://library-skills.io), which symlinks it into their project's `.agents/skills/`. FastAPI, Streamlit, Typer and SQLModel already ship skills at exactly this path; no scientific Python package does yet. SKILL.md covers units, sources, field computation and output shapes, sensors, paths, collections, `getFT()` and `show()`, then closes with the gotchas that cost the most: silent v4 unit errors, `squeeze` changing the output rank, `rotate()` appending to a path rather than transforming it, and `meshing` being mandatory for force targets. Four files under `references/` hold the detail and are loaded on demand, per the spec's progressive disclosure. Every API claim was executed against this tree rather than recalled, and the skill validates against the reference implementation from the agentskills repo. The new tests assert the skill is packaged, that its frontmatter meets the spec, and that its relative links resolve. Note for contributors: do not run `library-skills install` at the repo root. The symlink it creates points back into `src/magpylib`, and hatchling then records the skill under that symlink in the sdist while dropping it from `src/magpylib` — an sdist install would ship no skill at all. The wheel is unaffected, and these tests would not catch it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Reviewed every claim against the 494 docstring examples and the 145 code cells in docs/_pages, and ran the skill's own code blocks. Fixes: - The backend section claimed matplotlib cannot animate. It can — all three built-in backends declare `supports_animation` and `supports_subplots`. What actually differs is `supports_colorgradient` (not matplotlib), `supports_animation_output` (pyvista only) and `supports_native_traces` (not pyvista), now given as the capability table from the registry. - "Datasheet remanence B_r is a polarization" skipped the part that matters: a real magnet demagnetises itself, so the value to use sits a few percent below B_r — the J at the working point. Additions, all of them things the docs use and the skill did not mention: - Path-varying properties are now a section of their own rather than a closing sentence, with the three rules that govern them — what you set is what is stored, lengths reconcile at computation time by edge-padding on a temporary copy, derived properties gain the path axis — plus end-slicing and mismatched lengths in the reference. This is the newest part of the library and the least represented in the docs, so it is the part an agent is least likely to know. - The `rotate_from_angax/rotvec/euler/quat/matrix/mrp` family, which the docs use throughout and which is far more ergonomic than building a scipy Rotation. - `getJ()`/`getM()` return the material's own polarization/magnetization inside the body and zero outside; inside a magnet, H opposes J. - A `Collection` passed as `sources` counts as one source and superposes its children, while a list of the same children keeps the source axis. - `TriangularMesh.from_pyvista/from_ConvexHull/from_triangles/from_mesh` for CAD and STL geometry, `CustomSource(field_func=...)` for measured or interpolated data, `copy(**kwargs)`, subclassing `Collection` for compounds, and the `graphics.model3d.make_*` helpers for custom 3D representations. Every example was executed against this tree: `path_properties` output, the (3, 3) result of a 3-step current against a 2-step position with the position attribute left at length 2, `dipole_moment` gaining the path axis, and the J/M/B/H values inside and outside a magnet. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Alexboiboi
marked this pull request as draft
August 27, 2026 20:30
This was referenced Aug 29, 2026
Member
Author
|
Superseded — split into four PRs so each part can be reviewed against its own risk profile rather than as one 1873-line diff.
The split matters because the array-API skill is a prerequisite for reorganising #792, and it was gated here behind review of a document that ships inside the wheel. Those need very different scrutiny. All content is carried over byte-identically, with one deliberate change in #989: items 1 and 2 of "Establish the contract" asserted a target version and a dependency stance while items 3–5 posed them as questions. All five now pose the decision with a recommended default, so merging the skill ratifies nothing — the answers belong in #792. Closing this and deleting |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds Agent Skills for both Magpylib users and repository contributors.
magpylibuser skill inside the package atsrc/magpylib/.agents/skills/magpylib/, installed asmagpylib/.agents/skills/magpylib/in wheels and sdists..agents/skills/for implementation, review, testing, documentation, research, design, maintenance, and contributor workflows.Why
Assistants can otherwise generate plausible Magpylib code from pre-v5 assumptions: millimetres instead of metres, millitesla instead of tesla, or
magnetizationwhere v5 expectspolarization. These mistakes often execute successfully while producing results wrong by factors of 1e3 to 1e9.The packaged user skill is version-pinned to the installed Magpylib release. The repository skills separately encode contributor workflows and project-specific validation without shipping that development-only context to end users.
Packaged user skill
The 309-line
SKILL.mdcovers units, sources, field computation and output shapes, sensors, paths, path-varying properties, collections, force and torque, visualization, and common silent failure modes.Four progressively disclosed references cover:
Three package tests verify that the skill is included, its frontmatter meets the Agent Skills specification, and all relative references resolve.
Users can discover and install it with
uvx library-skillsfrom library-skills.io.Repository contributor skills
The repository-local suite covers:
These files remain under
.agents/skills/and are not package data.Array API development skill
The dedicated workflow defines:
array-api-compatat the audit date;The inventory records that all 13 open direct Array API PRs were conflicted and had zero checks at the audit date. They are treated as design evidence rather than merge-ready implementations.
Verification
skills-ref validate: valid packaged skill.uvx library-skills scandiscovers the installed skill andinstalllinks it correctly.uvx nox -s lint: passed.Repository-root installation caveat
Do not run
library-skills installat the repository root. Its generated symlink points back intosrc/magpylib; Hatch can then record the skill under the symlink in the sdist while omitting the real package path. Install from a separate consumer project when testing discovery.