macaulay2-skillsSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

npx skills add youngsu-Kim/macaulay2-skills

skills/
macaulay2/
SKILL.md              # rules + traps + lookup ladder (kept small)
references/
index.tsv           # 5,704 rows: symbol -> blurb -> page -> package (prefix-grep ^name)
toc.md              # 2,016-node thematic outline of the 1.26 core docs
packages.md         # 299 bundled packages b

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: macaulay2
description: >-
  Write, fix, and verify Macaulay2 (M2) code and read its output: polynomial
  rings and ideals, Groebner bases, free resolutions, Betti tables, Hilbert
  series and polynomials, primary decomposition, packages. Use whenever a task
  involves Macaulay2 or an M2 kernel/MCP tool (m2_evaluate, iN:/oN= prompts,
  "no method for adjacent objects" errors, betti tables), even when the user
  only describes the algebra in words or LaTeX.
---

# Macaulay2 core skill

Version-pinned knowledge for **Macaulay2 1.26**. Every rule below was checked
against a real kernel; `references/index.tsv`, `toc.md`, and `packages.md` are
generated from the docs trees shipped inside the same pinned install — core
plus the packages loaded by default (see the provenance headers). If your
kernel reports a different version, prefer its own `m2_help`.

## 1. Lookup ladder — do this BEFORE guessing a function name

M2 errors from a wrong name are misleading; guessing burns many turns.
In order:

1. Rules and references in this skill.
2. **Check the name exists**: `grep -E '^NAME' references/index.tsv`
   (columns: `symbol <TAB> blurb <TAB> page <TAB> source-package`). Use a
   PREFIX match, not exact: many symbols have only signature rows
   (`saturate(Ideal,Ideal)`, `factor(RingElement)`...) — 78+ bases on 1.26.
   The index covers core **plus the 21 default-loaded packages** (trap #11).
   A miss means the name is SUSPECT, not dead: pure aliases (`res`) and
   symbols inside multi-topic pages get no row.
3. **`m2_help topic`** (when available through the macaulay2-mcp server) —
   resolves real kernel bindings, aliases included, against the same pinned
   corpus (`m2_help "res"` → documents `freeResolution`).
4. Full page: `$PREFIX/share/doc/Macaulay2/<PKG>/html/<page>` — `<PKG>` is the
   4th column; macaulay2.com serves the same paths.

Worked example of trap #2 below: `grep -E '^reduce' references/index.tsv` →
no relevant rows, and `m2_help "reduceGb"` finds nothing ⇒ `reduceGb` does
not exist ⇒ you already have the reduced basis from `generators gb I`.
Contrast: `grep -E '^saturate' index.tsv` hits 21 signature rows (package:
Saturation) ⇒ real, and no loadPackage needed — it is ⚡ default-loaded.

## 2. Statements and output discipline

```m2
R = QQ[x,y,z]
I = ideal(x^3 - y, x^4 - z)
print (I == ideal(x^3 - y, x^4 - z))
-- expect: true
```

- Separate statements with **newlines, not semicolons**. A trailing `;`
  SUPPRESSES that statement's displayed result (`x + 1;` computes, prints
  nothing). In batch/script runs, only some things print at all — prefer
  explicit `print`.
- `print` takes ONE expression: `print (a, b)` sequences them. `print a | b`
  parses as `(print a) | b`. Strings concatenate with `|`, and use **double
  quotes** (single quotes are invalid).
- `A; B` on one line shows only `B`.
- **Shared kernel hygiene:** the kernel is one global namespace. If other
  agents/sessions may share it, prefix YOUR definitions (`my_R = QQ[x,y,z]`)
  AND your ring variable names (trap #15), and never call `session_reset`/
  `interrupt` — build each task self-contained in one call.
- **Syntax errors are kernel-fatal:** a parse error (e.g. using a reserved
  word like `in` as a variable) can restart the kernel with TOTAL state
  loss — unlike runtime errors (trap #6 survives). After any syntax error or
  if a name suddenly behaves like an unbound `IndexedVariable`, assume a
  fresh kernel and re-send the whole self-contained block.

## 3. The traps that cost models the most turns

| # | Trap | Reality (verified on 1.26) |
|---|------|----------------------------|
| 1 | `gb I` | returns a **GroebnerBasis object**; to SEE the polynomials: `generators (gb I)` (synonym `gens`). They are **already sorted and auto-reduced** — there is NO `reduceGb`. |
| 2 | error `no method for adjacent objects: NAME (of class Symbol)` | means NAME itself is unknown/juxtaposed — the **name**, not the spacing, is wrong. Reformatting the call never fixes it; grep the index instead. |
| 3 | `dim S/I` | parses as `(dim S)/I` → error. Quotients need parens: `dim (S/I)`, `degree (S/I)`. Both `dim` and `degree` also accept the **ideal directly**: `degree I` ✓ (verified). |
| 4 | `res (R/I)` | classic mistake — `res` (freeResolution) takes **ideals/modules/maps**, not quotient rings: use `res I`. (`hilbertPolynomial (S/I)` however DOES take the quotient.) |
| 5 | assigning to `gb`, `res`, `betti`, `ideal`, ... | `error: assignment to protected global variable` — pick another name. |
| 6 | a line failed halfway | the kernel is a REPL: **no rollback**. Earlier statements already took effect (`x = 2` on a failing line still leaves `x = 2`). Fix forward; `:=` scopes per-iteration locals in loops: `for k from 1 to 5 list (J := ideal(...); <expr>)`. |
| 7 | name now holds a value | `x = symbol x` restores the bare symbol. Note expressions captured values at assignment time. |
| 8 | graded invariants (`betti` degrees, `hilbertSeries`) | require a **homogeneous** ideal; non-homogeneous input gives misleading or failed output. |
| 9 | `loadPackage "P"` answers "not reloaded; try Reload => true" | P is **already loaded** — just use it. Force-reloading is fragile (breaks on packages with `needsPackage` dependencies). |
| 10 | batch scripts: one unresolved symbol | poisons the whole script's `User` package: you ALSO get `mutable unexported unset symbol(s) in package User: 'T'` noise. The FIRST error line is the real signal. |
| 11 | "I must loadPackage first" | **21 packages are loaded at startup** (⚡ in `packages.md`): PrimaryDecomposition, Saturation, Elimination, IntegralClosure, MinimalPrimes, TangentCone, ReesAlgebra, InverseSystems, LLLBases, Polyhedra, Varieties, Truncations, Complexes, PushForward, Classic, ConwayPolynomials, Isomorphism, SimpleDoc, OnlineLookup, PackageCitations (+Core). `primaryDecomposition`, `saturate`, `integralClosure`, `tangentCone`, `minimalPrimes` ... work in a FRESH session — do not load 

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (3)

sudo add-apt-repository -y ppa:macaulay2/macaulay2

sudo apt-get update

sudo apt-get install -y macaulay2

Gates applied: no_behavioural_pass.