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.
Select Profile Models
Set an exact provider model ID and reasoning effort in the profile template’s existing
config.runtime object. The built-in catalog currently uses:
| Profile | Model | Reasoning |
|---|---|---|
| Operator | gpt-5.6-sol | high |
| Chat | gpt-5.6-terra | high |
| Growth | gpt-5.6-terra | high |
| Engineering | gpt-5.6-sol | high |
| Support | gpt-5.6-luna | high |
Keep the shared runtime model field provider-neutral. Do not add an Oblive model alias registry or silently retry with another model. An unavailable selected model should fail through the normal redacted execution error path.
Changing a model or reasoning effort creates a new catalog revision. Publish that revision and explicitly reprovision affected organizations with their currently enabled departments. The existing reconciliation keeps profile IDs stable, persists the runtime settings in PostgreSQL, and clears reusable Chat sessions when the Chat profile changes.
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.
It also owns completion semantics for every durable profile. Planning instructions prefer formal
output_file, command_exit, and integration_call criteria, permit an empty list for
self-verifying work, and treat legacy semantic criteria as display-only expectations. The
backend—not the profile prompt—chooses whether deterministic completion closes immediately, repairs
once, asks a human, or fails. Judgment that must gate work belongs in an explicit review task.
Profile instructions should state only when a domain skill applies; they must not duplicate this
lifecycle.
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.