Skip to content

docs: commit the agent configuration (AGENTS.md, .agents/skills, .claude symlinks) - #24

Merged
junwen94 merged 1 commit into
mainfrom
issue-23-agent-config
Sep 3, 2026
Merged

docs: commit the agent configuration (AGENTS.md, .agents/skills, .claude symlinks)#24
junwen94 merged 1 commit into
mainfrom
issue-23-agent-config

Conversation

@junwen94

@junwen94 junwen94 commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

Commits an agent configuration written for this repository, and stops
gitignoring it.

goldilocks-ml and goldilocks-core both commit .agents/ and AGENTS.md;
this repository listed them in .gitignore, so anyone other than the original
developer — and any agent — started here with no project instructions and no
skills.

The local copy could not be committed as-is

It was a half-adapted copy of goldilocks-core's configuration:

File Problem
AGENTS.md opened with # goldilocks-core and described core's Load → Analyse → Advise → Select → Generate pipeline, which does not exist here
github-cli/SKILL.md hard-coded --repo stfc/goldilocks-core in ~15 commands, so an agent files issues against the wrong repository
catchup/SKILL.md same, in 4 commands
write-a-test/SKILL.md ran coverage as --cov=goldilocks_core
write-docs/SKILL.md inspected src/goldilocks_core, referenced docs/architecture.md (absent), documented a goldilocks-kmesh CLI (the console script is goldilocks-data), and invoked a mermaid validator at /home/sigil/.pi/...
dft-basics/SKILL.md described itself as being for goldilocks-core

What is here

AGENTS.md — written for goldilocks-data: the generate/analyse/publish
sequence, ecosystem position, the package/campaign boundary ("a private path
must never reach the package API"), the real layout, and the commands from
README.md including ruff check src tests campaigns/qe/kpoints/scripts and
the --extra aiida --extra kmesh campaign invocation.

It also records the k-index convention, which cost real effort to establish:
k_index is 0-based with rung 0 the Γ-only (1, 1, 1) mesh; the ladder comes
from the k-distances where ceil(|b_i| / k_distance) changes; and the
enumeration cap on n is applied per axis, so the ladder is a complete set of
meshes only for k_distance >= max(|b_i|) / n_max and silently skips reachable
meshes below that. Any recomputed or published k_index column must state the
cap it used.

.agents/skills/ — 12 skills, every goldilocks-core reference corrected.
write-docs is rewritten against the real docs tree and now warns that a new
page must be added to the mkdocs.yml nav or --strict fails. use-uv gains
an Extras section: AiiDA and pymatgen are optional extras, so an AiiDA import
error usually means a missing --extra, not a broken environment. triage is
ported from goldilocks-ml with its ML-specific classification rule replaced by
a campaign/package one.

.claude/skills/<name> — relative symlinks to ../../.agents/skills/<name>,
stored as git mode 120000, the mechanism goldilocks-ml uses. Codex reads
AGENTS.md and .agents/; Claude Code discovers .claude/skills/; both read
the same files, so they cannot drift.

No CLAUDE.md — neither sibling repository has one, and .gitignore still
excludes it. The existing local one pulled all twelve SKILL.md files into
every session's context through @ imports; the symlinks do the same job
without that cost.

Verification

  • No goldilocks-core / goldilocks_core / goldilocks-kmesh reference and no
    foreign absolute path survives, except two deliberate ecosystem
    cross-references in AGENTS.md
  • All 12 skills have a matching symlink, and all 12 resolve to a SKILL.md
  • No code, test, or packaging file is touched

Closes #23


Written by an agent on behalf of @junwen94.

goldilocks-ml and goldilocks-core both commit theirs; this repository
gitignored it, so anyone but the original developer started here with no
project instructions and no skills.

The local copy could not be committed as-is: it was a half-adapted copy of
goldilocks-core's configuration. AGENTS.md opened with '# goldilocks-core'
and described core's Load/Analyse/Advise/Select/Generate pipeline, which
does not exist here; github-cli hard-coded --repo stfc/goldilocks-core in
about fifteen commands; write-a-test ran --cov=goldilocks_core; write-docs
inspected src/goldilocks_core, documented a goldilocks-kmesh CLI, and
called a mermaid validator by an absolute path on someone else's machine.

AGENTS.md is written for this repository, and records the k-index
convention including the per-axis enumeration cap that bounds where the
ladder is complete. write-docs is rewritten against the real docs tree.
triage is ported from goldilocks-ml. .claude/skills symlinks into
.agents/skills so Claude Code and Codex read one source.

.gitignore keeps CLAUDE.md local; neither sibling repository has one.

Closes #23
@junwen94
junwen94 merged commit 9617125 into main Sep 3, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Commit the agent configuration (AGENTS.md, .agents/skills, .claude symlinks)

1 participant