Skip to content
Agents Inc

Configuration

Your installation is described by one file: .claude-src/config.ts. It’s plain TypeScript, it’s meant to be hand-edited, and it’s the source of truth npx agents-inc compile reads every time it rebuilds your sub-agents. Whichever front door you came through writes it on first run — the editor hands you an npx agents-inc init --from <id> command that does it, and npx agents-inc init on its own does it from the terminal wizard. Nothing in it is off-limits afterwards.

Quick start

Section titled “Quick start”

Open .claude-src/config.ts in your editor. The smallest change with a visible result is giving one sub-agent a different model — add two keys to its entry in the agents array:

const agents: AgentScopeConfig[] = [
  { name: 'web-developer', scope: 'project' },
  { name: 'api-developer', scope: 'project', model: 'opus', effort: 'high' },
]

Save, then rebuild:

npx agents-inc compile

Open .claude/agents/api-developer.md. Its frontmatter now reads model: opus and effort: high. That’s the whole loop — edit config.ts, compile, read the compiled agent.

The two files in .claude-src/

Section titled “The two files in .claude-src/”
File Who writes it Do you edit it?
config.ts init, edit, eject — and you Yes. This is the one.
config-types.ts generated, and regenerated on every compile No. Its first line is // AUTO-GENERATED by agents-inc — DO NOT EDIT.

config-types.ts holds narrowed type unions — SkillId, AgentName, Category, Domain — built from what’s actually installed. That’s what makes a typo in a skill id a TypeScript error in your own editor rather than something you find out about when you compile. Because it’s derived, losing it costs you nothing: the next npx agents-inc compile writes it again from config.ts.

Both arrive already formatted — single quotes, no semicolons, a 100-column width — so Prettier with those settings changes nothing.

The shape of config.ts

Section titled “The shape of config.ts”

Four fields can be lifted into named consts — skills, agents, stack and selectedDomains — and export default is a table of contents referencing them, with every other field written inline however long it is. An empty one stays inline as skills: [], so a config with nothing in it yet has fewer consts than a filled-in one:

import type { ProjectConfig, AgentScopeConfig, SkillConfig } from './config-types'


const skills: SkillConfig[] = [
  { id: 'web-framework-react', scope: 'project', origin: 'agents-inc' },
]


const agents: AgentScopeConfig[] = [{ name: 'web-developer', scope: 'project' }]


export default {
  name: 'my-project',
  agents,
  skills,
  marketplace: 'github:agents-inc/skills',
} satisfies ProjectConfig

Four fields carry the installation: skills is the install manifest, agents is the roster, stack maps skills onto sub-agents, and marketplace says where skills are fetched from. Seventeen exist in all — Config reference is the exhaustive list, and Editing your config walks those four as a task rather than as a table.

Key order is the writer’s, not the order you selected things in — top-level fields, the keys inside stack, and the keys inside each entry are all placed in a fixed order. Two configs holding the same values are therefore the same file, which is what keeps an edit that changed one skill from rewriting the lines about the others.

A field the loader accepts is not always a field the generated types declare. branding and the five path overrides are read and preserved by the CLI, but the ProjectConfig interface in config-types.ts doesn’t declare them — so writing one into config.ts draws a TypeScript error from satisfies ProjectConfig even though the CLI honors it. See Models and effort for branding and Scopes and paths for the path overrides.

Editing by hand, the wizard, or the editor

Section titled “Editing by hand, the wizard, or the editor”

Go back to the editor when you’re reconsidering the selection rather than adjusting a line of it — the whole catalog is on screen there, and a hand-edit only shows you what you already have. It’s a round trip, because the browser can’t read your disk: npx agents-inc edit --ui publishes this installation and opens it at agentsinc.sh/editor, and npx agents-inc edit --from <id> applies what you changed back. Reach for edit --from and not init --from — the second refuses a directory that’s already installed, since installing a shared configuration is a fresh setup rather than a merge.

Run npx agents-inc edit when the change involves files landing on or leaving disk and you’d rather stay in the terminal: adding a skill, removing one, switching a skill between plugin and eject, or moving something between project and global scope. The wizard runs the install pipeline; hand-editing skills only edits the manifest, and a config naming a skill nothing installed compiles to an agent referencing something that isn’t there.

Edit by hand when you’re rearranging what’s already installed: moving a skill from one agent to another, marking one preloaded, pinning a model, dropping an agent’s entry in stack. None of that installs or removes anything, so compile is all it needs.

All three write the same file. See Commands for what each one does.

What compile does with it

Section titled “What compile does with it”

npx agents-inc compile is non-interactive, takes no marketplace flag, and is safe in CI. It reads config.ts from disk, resolves each agent’s skills through stack, and writes one Markdown file per agent into .claude/agents/. Agents carrying excluded: true are filtered out before anything is resolved.

It also regenerates config-types.ts at every scope it compiles, so a skill you added by hand becomes a valid SkillId and a removed one becomes a type error. It never rewrites config.ts — the hand-edit workflow is “edit, then compile”, so the file you edited has to survive.

Two things it reports rather than fixes, both of which a hand-edit can create. A stack entry naming a skill that isn’t installed is dropped, and each one is named: Skill '<id>' is configured but was not found — agents will be compiled without it. A project-scoped skill handed to a global-scoped sub-agent is dropped the same way, with global-scoped sub-agents only carry global-scoped skills — see Scopes and paths. Neither rewrites the row, so the warning repeats on every run until you fix the config.

A compile run owns one pass, not two. Run it inside a project and it compiles that project’s agents — not the global install’s, and not another registered project’s. Where both installations exist the pass is narrowed to project scope, because a project’s config inlines the global entries and an unfiltered pass would write global-scoped agents into the project’s own agents directory. The global pass is reached only where no project installation is in play: from your home directory, or from a directory with no config of its own. So global-scoped sub-agents are not rebuilt from inside a project — run npx agents-inc compile from your home directory to rebuild those. That run also refreshes every project registered in the global config’s projects array.

The rest of this section

Section titled “The rest of this section”