add-agent-profile
Add or change a Greenhouse Agent profile. First decide whether a system preset is needed at all: most requests are a custom Agent (run_profiles row), a profile pack, a plugin's agent context or a spro
SKILL.md.claude/skills/add-agent-profile/SKILL.md
GitHubAdd or change an Agent profile
Source of truth: apps/api/src/profiles/AGENTS.md (inventory and rules) and apps/api/src/profiles/agent-profiles.md (architecture, tool matrix, i18n, rich output). On conflict those win.
Step 0: you probably do not need a preset
- The directory holds two YAMLs on purpose:
sprouty.yaml(the only preset, DEFAULT_PROFILE_ID, /api/chat) anddesktop.yaml(hidden runtime profile for /api/agent and /api/mcp; never listed, renaming it needs a data migration). - Different model: the model is chosen per turn beside the composer (
POST /api/chatmodel, checked by isChatModelAllowed()); never a new profile. - Different prompt or narrower tools for some people: a custom Agent (below), the normal path.
- A deployment's own set: a profile pack,
packs.profilesin greenhouse.config.ts (a later directory wins for the same id). - Plugin behavior the model should know: the plugin's agentContext or promptContext, never a profile.
- Better wording for everyone: edit sprouty.yaml; there is no second copy.
- External agents (MCP clients, CLIs) use /api/agent or /api/mcp, never a dedicated profile.
Custom Agents
- One current-configuration row in run_profiles;
versioncounts edits; references arecustom:<id>@<version>and any pin ≤ version resolves to the current configuration. - Sessions and automations pin on creation (pinProfileIdForUser(), profiles/access.ts); execution rechecks owner, super or team sharing.
base_profile_idmust be a preset (isValidCustomBaseProfileId()); the base supplies onlyaccess.rich_outputand the model fallback.- Private by default; only a super shares it with the team (
PUT /api/profiles/custom/:id/sharing); tools only narrow the member's own. - API: /api/profiles/custom (apps/api/src/routes/profiles.ts); UI: the custom agents section of the client's Automations place (apps/client/src/automations/agents.ts, agent-editor.web.tsx).
- resolveProfileAsync() throws for a missing custom Agent or version; it never falls back to Sprouty.
Step 1: the YAML (only for a real preset)
id: xxx
name: Xxx
version: 'YYYY-MM-DD'
description: # plain string or { zh, en } (source locale zh)
en: …
zh: …
access:
level: internal # internal | hidden
rich_output: true
model:
id: flash # default for headless paths only; options live in config/models.yaml
tools: [] # built-ins derive tools from the member and active plugins
system_prompt: |
…
accessholds onlylevelandrich_output; session requirements belong to each runtime or route.- No
options: temperature, thinking, max_tokens belong to config/models.yaml (resolveModelConfig()). - No
extends; reuse prompt text by editing sprouty.yaml. - The rich-output block guide exists once, RICH_OUTPUT_GUIDE (packages/utils/src/prompts.ts), appended by enrichSystemPrompt(); never restate it.
- Prompts never restate rules of dynamically assembled tools; name only
is_global: truetools or tools the profile declares. nameanddescriptionwith an unknown locale key or an empty string fail loading;system_promptis never localized.- The system prompt holds only session-stable content (prompt caching); per-turn content goes elsewhere.
Step 2: move these together
apps/api/src/profiles/<id>.yaml(loadAllProfiles() scans the directory).apps/api/src/profiles/profile.ts: PRESET_PROFILE_IDS (array order is picker order), DEFAULT_PROFILE_ID, CUSTOM_BASE_PROFILE_IDS.- A YAML without its constant is an Agent nobody can pick; a constant without its YAML fails at boot with
Profile not found. apps/api/src/profiles/agent-profiles.md: architecture and tool matrix.tests/api/agent-profiles.test.ts: YAML count and names, legacy mapping, valid custom bases, single rich-output copy, no extends, keyless models out of the picker.- The universal client hard-codes
sprouty: new-Agent base (apps/client/src/automations/agents.ts), automation default (apps/client/src/automations/editor.web.tsx), Sprouty ids (apps/client/src/data/home.ts).
Step 3: tools and models
- Built-in profiles derive tools at runtime (resolveEffectiveTools narrows; resolveUserTools is the member's allow-set); never pin optional plugin tool ids in YAML.
- A custom Agent's
toolsonly narrows;meta.builtintools join its filter without widening permissions. GET /api/profilesreturnsmodels: listChatModels(), which omits models without a reachable provider; an unreachable custommodel_idfalls back to the base preset's model.
Step 4: legacy ids map, never migrate
- normalizeProfileId() maps retired preset, team and eval ids to
sproutyandlocal-dev/local-pitodesktop; stored values stay as they are; never recreate YAML for them.
Gate
pnpm typecheck
pnpm lint
TEST_DATABASE_URL=<loopback test db> pnpm test
(cd apps/client && pnpm typecheck) # when client hard-coded ids changed
- Check by hand: resolveProfileAsync() resolves the profile; a non-hidden preset appears in the client's Agent pickers.
Checklist
- Custom Agent, pack, plugin context or a sprouty.yaml edit ruled out; reason for a new preset recorded in profiles/AGENTS.md
- access only level + rich_output; no options, no extends, no second rich-output guide
- No restated dynamic tool rules or false capability claims in the prompt
- YAML, profile.ts, agent-profiles.md, agent-profiles.test.ts and client ids moved together
- Gate green