Customize

Customize

Build and maintain agent profiles and skills programmatically via the repl tool using host.agents.* and host.skills.*.

A profile is a named bundle that shapes how an agent behaves:

• system_prompt — the profile's identity. This is the opening of the agent's system prompt; it REPLACES the generic "You are Claude Science" base identity. Write it in second person, lead with You are {display_name}, ..., state what the agent specializes in and what it does NOT do. Everything else (tool-usage rules, working-style bullets, scope guardrail) is inherited automatically — don't restate it.
• display_name / description / icon_key / color_key — picker metadata.
• skill_names (optional restriction) — by default a profile sees the full live skill catalog via search_skills / skill(...), same as the main agent. Pass an explicit list ONLY to deliberately restrict it; [] creates a zero-skill specialist. Restricting skills also restricts connectors — a single unrestricted flag governs both; passing skill_names flips the profile to curated mode and starts it with zero connectors (see next).
• Connector access — an unrestricted profile (the default) reaches every connector (bundled + custom + authorized directory), same as the main agent; use detach_connector to subtract specific ones. A curated profile (one created with an explicit skill_names list, or flipped via {"unrestricted": False}) starts with no connectors — reach is exactly what you attach_connector.
• excludedTools — per-tool blocklist applied after connectors resolve. Use to strip specific high-risk or irrelevant tools from an otherwise-useful connector. Per-connector, not a profile field — set via attach_connector(..., include_tools_pattern=/exclude_tools_pattern=); the profile's excludedTools in list() is the read-only aggregation across all its attached connectors. Patterns match the connector's bare tool names (e.g. '^list_marts$', as returned by list_connectors(name)['tools']); the aggregated excludedTools entries are stored fully-qualified as mcp_<connector>_<tool> since the list spans every attached connector.

Python SDK

All calls run via the repl tool (see "Runs via the repl tool" below). Return values are plain dicts/lists; errors raise RuntimeError with a host.agents.*: / host.skills.*: prefix.

host.agents

host.agents.list()
# → [{"name", "displayName", "description", "source", "enabled",
#     "systemPrompt", "iconKey", "colorKey",
#     "skillNames": ["skill", ...], "connectors": ["name", ...],
#     "excludedTools": [...]}, ...]
#   (Return-dict keys are camelCase — wire shape, not kwarg names.)
#   `connectors` is a list of connector names (strings, same as skillNames) —
#   pass one to attach_connector/detach_connector or list_connectors(name).

host.agents.create(name, display_name, description,
                     system_prompt="", skill_names=None)
# name: 2–32 chars, UPPERCASE letters / digits / underscores only —
#       e.g. "RNASEQ_REVIEWER". Lowercase / dashes are rejected.
#       display_name is the human-friendly picker label.
# skill_names controls catalog visibility:
#   - leave it unset → the profile sees the FULL live skill catalog, same as
#     the main agent — skills published later appear automatically. It also
#     gets every connector the main agent has, resolved dynamically — new
#     connectors added later appear automatically too. This is the default;
#     don't pass a list unless you mean to restrict.
#   - pass a list (including []) → restricts `search_skills`/`skill(...)` to
#     EXACTLY those names. [] creates a zero-skill specialist.
# → the stored profile record (same shape as one list() entry)

host.agents.update(name, patch)
# patch: dict of fields to change — any of display_name, description,
#        system_prompt, skill_names, unrestricted, icon_key, color_key
#        (camelCase also OK).
# patch["skill_names"] is an EXACT REPLACE of the whole skill list and flips
# the profile to restricted mode — anything you omit is DETACHED. To add or
# remove a few skills, use attach_skill / detach_skill — they work on both
# restricted AND unrestricted profiles without changing the mode.
#
# If you do need a full-list replace, CHECK cur["unrestricted"] FIRST: on an
# unrestricted profile cur["skillNames"] is the lossy disk-cache view (not
# the full live catalog), so `cur["skillNames"] + ["x"]` would permanently
# freeze the profile to that partial list. The safe pattern:
#   cur = [a for a in host.agents.list() if a["name"] == name][0]
#   if cur["unrestricted"]:
#       host.agents.attach_skill(name, "new-skill")   # stays unrestricted
#   else:
#       host.agents.update(name,
#           {"skill_names": cur["skillNames"] + ["new-skill"]})
# (return-dict keys are camelCase — read "skillNames", write "skill_names")
# patch["unrestricted"] = True → back to the full live catalog + all
# connectors (undoes a skill_names restriction).
# → updated profile record
# (excludedTools is NOT a patch field — it's per-connector; use
#  attach_connector's include_tools_pattern/exclude_tools_pattern below.)

host.agents.switch(name)
# Ask to continue THIS conversation as `name`. Shows the user an approval
# card; on Allow, the switch takes effect on their NEXT message (the current
# turn finishes as the current profile). On decline, tell the user they can
# select the profile from the session config popover on any new conversation.
# → {"switched": True, "name", "displayName"}

host.agents.delete(name)
# → {"deleted": name}

host.agents.attach_skill(name, skill)
host.agents.detach_skill(name, skill)
# → updated profile record

host.agents.attach_connector(name, connector,
                               include_tools_pattern=None,
                               exclude_tools_pattern=None)
host.agents.detach_connector(name, connector)
# → updated profile record. Omit both patterns on a fresh attach to expose
#   every tool the connector offers; re-attaching an already-attached
#   connector without patterns preserves its existing exclusion list (pass
#   include_tools_pattern='.*' to clear it). Patterns match the connector's
#   BARE tool names (as returned by list_connectors(name)['tools'], e.g.
#   '^list_marts$'); the resulting excludedTools entries are stored
#   fully-qualified as mcp_<connector>_<tool>.

host.agents.list_connectors(connector_name=None)
# no arg → [{"name", "displayName", "source", "description",
#            "authState", "attachedAgents": [...]}, ...]
# with connector_name → single dict with an extra
#   "tools": [{"name", "description"}, ...]

host.skills

host.skills.list()
# → [{"name", "origin", "description"}, ...]
#   origin: "anthropic" (bundled, read-only — fork under a new name),
#           "organization"/"personal" (editable), "draft" (local, unpublished)

host.skills.read(name, path="SKILL.md")
# → {"name", "path", "content": "..."}

host.skills.edit(name, path, content, old_string=None)
# old_string=None → create `path` with `content` (fails if the file already
#                   exists — read it, then edit with a non-empty old_string)
# old_string=str  → str_replace the single exact match (rejected unless it
#                   matches exactly once — add surrounding context if needed)
# → {"action", "path", "draft_path", "note"}

host.skills.publish(name, overwrite=False)
# publish takes NO content args — write SKILL.md via .edit() first.
# → {"status": "published", "skill_id", "name", "note"}

host.skills.delete(name)
# draft → removes local dir; org/personal → unpublishes + removes local
# cache; anthropic bundled → protected.
# → {"deleted": name}  (plus "unpublished": True for published skills)

Runs via the repl tool

host.agents.* / host.skills.* execute in the control-plane kernel — a separate Python process from your python cells, reached via the repl tool (not the python tool). It shares your workspace directory (cwd) but not memory, so variables from python cells aren't visible there and vice-versa. To hand results across, write to a file — same pattern as Python↔R:

# repl tool
import json, os
os.makedirs("handoff", exist_ok=True)
profiles = host.agents.list()
json.dump(profiles, open("handoff/agents.json", "w"))

# python tool
import json, pandas as pd
profiles = json.load(open("handoff/agents.json"))
pd.DataFrame(profiles)[["name", "source", "enabled"]]

Workflow: scope → draft → review → create

Do not call generate_plan for profile CRUD. This is a single scope→draft→confirm loop; ask_user (step 4) is the review gate. A plan adds a second approval that duplicates the ask_user confirmation and drags in step-status bookkeeping that fights this workflow.

User approval. Most host.agents.* / host.skills.* calls apply immediately — create/update (including unrestricted), attach_*/detach_*, and skills.publish/skills.edit are pre-approved at session start and the cell does NOT pause. An approval card (cell pauses, resumes automatically on Allow — you don't retry) appears only for the calls that hand off identity or free a granted name:

• host.agents.switch(name) — per-target; Allow covers this name only
• host.agents.update(name, {"name": ...}) (rename) — per-target
• host.agents.delete(name) / host.skills.delete(name) — one card per project: the first delete shows a card; "Allow for this project" covers every subsequent delete in this project, including bulk teardown. Do NOT tell the user they'll see N cards for N deletes.

The name is read from the runtime call for switch and rename, so both literal and variable names work (host.agents.switch("FOO") or host.agents.switch(name_var)); keep the ask_user review step so the click is a quick confirm, not a surprise. After the call returns, read back (host.agents.list()) to confirm the actual state — don't narrate an expected card.

Reading existing profiles

Call host.agents.list() to see the user's current profiles so you don't duplicate an existing agent. The main agent's bundled profile is protected — it cannot be renamed or deleted.

1. Scope first

What is this agent for? A profile should have one job. Pick an UPPER_SNAKE name (RNASEQ_REVIEWER, not RNA-seq review helper). Use ask_user if the name or scope is unclear — profiles are user-visible in the picker.

2. Write the identity

system_prompt is the agent's opening paragraph — it replaces the base identity, it's not an addendum. Lead with You are {display_name}. State the specialization and the boundaries ("You handle X, Y, Z. You do not handle ..."). Keep it under ~200 words; the heavy how-to lives in skills, not the prompt.

3. Ask: full access or a subset?

Before creating, ask_user whether this profile should have full access (the live skill catalog and every connector — same reach as the main agent; new skills and connectors appear automatically) or a restricted subset (a fixed list you'll curate together). Don't infer this from the role description — a narrowly-described specialist may still want full reach, and a broadly-described one may want a tight loadout. Pair this with the name/prompt review in step 4 so it's one round-trip.

4. Review with the user

Show the proposed name, display name, description, system_prompt, and the user's full-vs-subset choice from step 3. ask_user to confirm before writing. If they chose a subset, list the proposed skills/connectors here.

5. Create

Call host.agents.create(name, display_name, description, system_prompt=...). If the user chose full access, leave skill_names unset. If they chose a subset, pass skill_names=[...] with the agreed list — this flips the profile to curated mode and starts it with zero connectors, so attach the agreed connectors after create as in step 6. For edits to an existing profile, use host.agents.update(name, {...}) with targeted fields; prefer host.agents.attach_skill(...) / host.agents.detach_skill(...) and host.agents.attach_connector(...) / host.agents.detach_connector(...) over wholesale skill_names replacement so you don't clobber the user's own edits.

After the profile exists, offer to switch to it: host.agents.switch(name). The user sees an approval card; on Allow, this conversation continues as the new specialist from their next message. If they decline, tell them they can select it from the session config popover on any new conversation.

6. Restricting the loadout (when the user chose a subset)

If the user chose a subset in step 3, curate after create:

• Skills: host.agents.update(name, {"skill_names": [...]}) with the exact list, or detach_skill one at a time. Check host.skills.list() for available names. On update, skill_names is an exact replace — never send a partial list to "add"; fetch the current skillNames (camelCase in the return dict), modify, send back.
• Connectors: a curated profile (created with an explicit skill_names list, or flipped via {"unrestricted": False}) starts with NO connectors — reach is exactly what you attach. Call host.agents.list_connectors() to see every available connector (bundled + directory + user-added MCP) with its auth state, then host.agents.attach_connector(name, connector_name) for each connector the user agreed to keep. Use include_tools_pattern=/exclude_tools_pattern= on the attach call to scope which tools the profile gets (omit both to expose every tool; re-attaching without patterns preserves the existing exclusion list — pass include_tools_pattern='.*' to clear). A connector with authState other than "authorized" or "not-required" must be connected via the Connectors panel before it can be attached. detach_connector only removes an explicit attachment; on a curated profile there is nothing to detach — don't use it to "restrict".
• After attaching, read back host.agents.get(name)["connectors"] to confirm the reach matches what you told the user.
• To undo a restriction: host.agents.update(name, {"unrestricted": True}).