AI Assistant Guide

install_agent_guide(; tool=:claude, scope=:project, track=false,
                      overwrite=false, dir=pwd()) -> String

Install a hierarchical, version-stamped guide to the JuliaSMLM ecosystem for an AI coding assistant, so it has the APIs of SMLMAnalysis and every sub-package on hand.

The guide is assembled at call time from the versions resolved in the current environment — each package's api_overview.md (falling back to README.md) is read from its pkgdir and copied into a reference/ bundle, with a top-level map linking them. Re-running refreshes it against whatever is currently installed.

Follows the lab skills-installer convention: the install carries a provenance stamp (x-installer, x-source-version, x-source-commit), so re-running refreshes only this installer's own install, and uninstall_agent_guide / agent_guide_status act only on stamped installs. Ownership of a reference file is decided per file, not by a manifest: a file counts as ours iff it is a regular (non-symlink) file whose first line carries the install header this package has always written, so a refresh regenerates only files it wrote and anything you add inside reference/ yourself survives. An existing file at one of our names that lacks that header is refused unless overwrite=true. A symlinked target, wrapper, reference directory, reference file, .gitignore, or AGENTS.md is never written through — it is refused with an ArgumentError rather than mutated; a directory (or any other non-regular file) at one of those paths is refused the same way, and the .gitignore / AGENTS.md side-effect files are checked before anything is written, so a refusal never leaves a half-installed guide behind. All installer writes are atomic (temp file

• rename), so an existing hardlink at one of our paths is replaced as a directory entry

rather than truncated in place.

Keyword arguments

• tool::Symbol = :claude — target assistant:
  • :claude writes a Claude Code skill (.claude/skills/smlma-ecosystem/SKILL.md
    • reference/*.md).
  • :codex writes a smlm-agent-guide/ bundle and a managed block in AGENTS.md.
• scope::Symbol = :project — :project → into dir (the repo); :user → into your home (~/.claude / ~/.codex, applying to every project you open).
• track::Bool = false — project scope only. When false (default) the installed files are added to the repo's .gitignore, keeping the guide out of history. Pass track=true to commit and share it. Ignored (with a warning) for scope=:user.
• overwrite::Bool = false — replace a target that was not installed by this installer (a hand-made skill, or another package's install). Refreshing our own stamped install never needs it.
• dir::AbstractString = pwd() — the repo root for scope=:project.

Returns the path of the installed skill/bundle directory.

Examples

using SMLMAnalysis
install_agent_guide()                    # Claude skill in ./.claude, gitignored
install_agent_guide(track=true)          # …and committed to the repo
install_agent_guide(tool=:codex)         # Codex AGENTS.md + bundle in this repo
install_agent_guide(scope=:user)         # Claude skill for all your projects

uninstall_agent_guide(; tool=:claude, scope=:project, dir=pwd()) -> Vector{String}

Remove a guide previously installed by SMLMAnalysis. Acts only on a target carrying SMLMAnalysis's own provenance stamp — a hand-made skill or another package's install is left untouched — and even then removes only SKILL.md/GUIDE.md, the reference files carrying this package's per-file install header, and — for tool=:codex — this package's managed block in AGENTS.md. Anything else, including files you added inside reference/ yourself, is preserved; reference/ and the install directory are removed only when nothing else remains in them, and a non-empty directory is left in place and reported with @info. A symlinked target, SKILL.md/GUIDE.md, or reference/ directory is never followed — it is left untouched with a @warn (and, for tool=:codex, the AGENTS.md block is then also left in place). Returns the paths removed (empty if nothing of ours was found, including when the target is unsafe to touch).

agent_guide_status(; tool=:claude, scope=:project, dir=pwd()) -> NamedTuple

Doctor: report an installed guide's state — (; installed, path, source_version, source_commit, current_version, stale). stale is true when the stamped source_version differs from the version currently resolved in this environment (re-run install_agent_guide to refresh).