@gleanwork/configure-agents gives gleanwork library and SDK repos a consistent, AI-friendly setup and keeps it from drifting. It scaffolds a small baseline into a repo and drift-checks that baseline in CI. It also ships the authoring rubric that constrains how the per-repo skills are written.

Why

Teach consumers' AI to use our libraries. Each opted-in repo carries a skill under skills/ (one directory per skill: skills/<name>/SKILL.md) that teaches a consuming AI how to use that library correctly, so we stop hand-feeding the same context. Distribution is handled by skills.sh fetching from GitHub — this tool owns none of it.
Consistency across repos. A uniform structure plus a scaffold to create it and a CI check to sustain it is what makes the setup maintainable across many repos.

The baseline

Each opted-in repo gets:

AGENTS.md — the repo's real agent instructions.
CLAUDE.md — a thin pointer to AGENTS.md.
skills/<name>/SKILL.md — teaches a consuming AI to use the library; distributed via skills.sh.
.github/workflows/agent-baseline.yml — CI that runs the drift check on every PR.

Agent skills

This repository ships agent skill(s) under skills/. Install them into your AI agent with npx skills:

npx skills add -g gleanwork/configure-agents   # global — available in every repo
npx skills add gleanwork/configure-agents      # or scoped to the current repo

Once it's installed, ask your agent to onboard a repo (below) — you won't invoke the CLI by hand.

Workflow (skill-driven)

The intended path is AI-driven, through the configure-agents skill installed above. Ask the AI to onboard a repo; it will:

Scaffold — npx -y @gleanwork/configure-agents init
Author the skill (skills/<name>/SKILL.md) against the rubric (the one rule below)
Verify — npx -y @gleanwork/configure-agents check
Open a PR with the result

Every step is safe to re-run.

Commands

`init`

Scaffolds the baseline into the current repo. Idempotent: it creates missing files and never overwrites your content.

--lang <ts|python|go|java> — override language detection (otherwise detected from the repo's manifest)
--package <name> — package name for the templates (defaults to the detected manifest name)
--dryRun — show what would be created without writing anything

`check`

Verifies the baseline structure and exits non-zero on violations (used by CI).

It checks, structurally only, that: the required files exist; at least one skills/<name>/SKILL.md exists, each with valid name/description frontmatter and the required sections; AGENTS.md has its required sections; and CLAUDE.md imports AGENTS.md. It does not — and cannot — validate that the skill's content is correct or current. That is the job of the rubric and of review.

`migrate`

For a repo set up before this baseline (e.g. a CLAUDE.md written by claude /init, with no AGENTS.md), promotes the existing CLAUDE.md into AGENTS.md and rewrites CLAUDE.md as a pointer. Ensures the required AGENTS.md sections; refuses if an AGENTS.md already exists (reconcile by hand). --dryRun previews. Run init to scaffold the rest, then refine the promoted AGENTS.md. init also detects this case and won't drop a competing stub.

The one rule (the rubric)

A skill's value is the complement of the API surface. Whatever the language's authoritative, ships-with-the-code definition already expresses — signatures, parameters, enums, return shapes — reference it; never transcribe it. A copied fact rots on the next release; a pointer to the types never does.

Language	Point the skill at
TypeScript / JS	the `.d.ts` referenced by `types`/`exports` in `package.json`
Python	inline type hints, `.pyi` stubs, the `py.typed` marker
Go	exported identifiers in source / godoc
Java	public classes and their Javadoc