Agent Packs, Skills, and Profiles
Add deterministic capabilities through the Git catalog and publish immutable revisions safely.
Ownership Flow
Git catalog
→ validated deterministic revision
→ immutable object-store publication
→ organization profile reconciliation
→ pinned runtime hydrationGit owns built-in templates and skill content. PostgreSQL owns organization selections and pins. Object storage owns published immutable revisions. Keep the flow one-way.
Add a Skill
Define the owner and trigger
Create a skill only when it gives a profile a reusable workflow, policy, or deterministic tool recipe. Do not move general product policy into a skill merely because an agent will read it.
Create the skill directory
Add packages/agent-packs/catalog/skills/<skill-key>/SKILL.md. Use lowercase kebab-case. Keep the
top-level file complete enough to route the task and link only relevant progressive references.
Write bounded instructions
Name the trigger, inputs, invariants, execution flow, success/waiting/blocked/failure exits, and unsafe shortcuts. Skills must not contain secrets or executable provider configuration.
Register the skill
Add the skill key to commonSkillKeys or the owning profile’s skillKeys in
packages/agent-packs/catalog/catalog.json.
Validate and test
Catalog tests should cover missing files, unsafe paths or symlinks, duplicate keys, unknown skill keys, deterministic revisions, the shared runtime contract, and the profile/runtime ownership split.
Publish and provision
Run the agent-pack sync command, then reprovision affected profiles when their static composition changes.
Modify a Profile
Profiles define name, summary, kind, optional department, skill keys, static MCP keys, default run mode, concurrency, tool-policy keys, and optional runtime overrides.
When profile content changes:
- Change the Git catalog or owning
AGENTS.md. - Validate the complete catalog.
- Publish a new immutable revision.
- Reconcile or reprovision organizations.
- Verify root instructions, composed skills, memory coexistence, and missing-revision failure.
Chat profile changes invalidate reusable chat sessions. Existing database IDs survive reconciliation; deselection disables historical rows rather than deleting them.
Profile AGENTS.md files own role, scope, domain dispatch, and always-on public boundaries. They do
not duplicate task admission, mode branching, run accounting, retries, handoffs, scheduling, output
sync, or outcome submission. The shared task-runtime skill owns that complete lifecycle for
Operator and department tasks. Chat remains a separate persistent-turn workflow and does not load
task-runtime.
The task runtime mirrors application-enforced limits instead of pretending prose is enforcement: each task run may sync at most 100 changed output files; accepted human/action waits remain in run history but release their consumed run credit; and task agents may create future schedules only within the active objective and authority scope. The backend records those schedules as agent-originated with creator and source-execution provenance.
Add Capability to a Department
Prefer adding a skill, integration grant, or tool policy to Growth, Engineering, or Support. Adding a fourth department changes shared enums, onboarding, organization configuration, profile rules, routing, persistence, UI, context structure, tests, and documentation and requires an explicit architecture decision.
Static MCP Grants
commonMcpServerKeys and profile mcpServerKeys select only keys present in the trusted agent-image
registry. The catalog or database may select a registered server but never provide its command,
package, path, or secrets.
Verification
bun test packages/agent-packs apps/backend
bun run --cwd apps/backend agent-packs:sync
bun run --cwd apps/backend agent-profiles:provision
bun run typecheckAlso update operator/developer documentation when a skill changes a visible workflow.