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}).

7. Set up the environment

After the profile exists, propose a conda environment for it: name it after the profile (lowercase slug, e.g. rnaseq-reviewer), pick python or r based on the skills you attached, and list the packages those skills need. ask_user to confirm the package list, then call manage_environments(mode="create", name="<slug>", packages=[...]) and, if anything further is needed, manage_packages(mode="install", environment="<slug>", packages=[...]). The profile uses this env by default; the system-owned python and r skeletons remain available as fallbacks.

What makes a good profile

• A sharp identity. One job, stated clearly in system_prompt. Full catalog access by default — restrict the loadout only when the user asks.
• Composable. Reuse existing skills; don't inline workflow steps into system_prompt that belong in a skill.
• Safe by default. If a connector is powerful, exclude the tools the agent doesn't need.

Authoring skills

For the full skill-authoring guide (anatomy, progressive disclosure, eval loop, description optimization), first load it:

skill({"skill": "skill-creator"})

Then use the host.skills SDK via the repl tool to write and publish:

# draft
host.skills.edit("my-skill", "SKILL.md", """---
name: my-skill
description: ...
---

# My Skill
...
""")

# bundle a helper
host.skills.edit("my-skill", "kernel.py", "def helper(x): ...\n")

# inspect / iterate
print(host.skills.read("my-skill")["content"])

# publish to the live skill set
host.skills.publish("my-skill")

Once published, the skill is in the live catalog — every unrestricted profile (including the main agent and any profile created with the default) sees it immediately. For a restricted profile, attach it explicitly with host.agents.attach_skill(profile_name, "my-skill").

Kernel sidecars (kernel.py / kernel.R)

If a skill's workflow depends on reusable helper functions, ship them as kernel.py (and/or kernel.R) at the skill root. When any agent calls skill({skill: <name>}), that file is executed in its persistent python/R kernel and the tool result reports which top-level names were defined — so SKILL.md can say "call annotate_df(df)" and the function already exists.

Sidecars are validated before execution so that loading a skill only defines names — nothing author-written runs at load time. Allowed at the top level:

• def / async def (no decorators). Default argument values must be literals — def f(url=MY_CONSTANT) gets the whole file rejected. Wrap constants with an explicit is None check: def f(url=None): then if url is None: url = MY_CONSTANT (not url = url or MY_CONSTANT, which also replaces 0, "", []).
• import / from … import name (no *). Defer third-party imports to inside function bodies — the skeleton python env ships stdlib + a small starter set (numpy, pandas, scipy, matplotlib, seaborn, pillow), so e.g. import requests at module scope surfaces a load error on every fresh kernel. Import errors don't fail the skill load; the agent sees the traceback and can manage_packages then re-load.
• Assignment of a literal constant to a plain name (e.g. VERSION = "1", LIMITS = (1, 2, 3)). Computed values like os.path.join(...) are rejected — move them into a function body.

Anything else at the top level (classes, calls, if/for, non-literal assigns) is rejected with [kernel.py rejected] …. Names starting with _ are reserved by the loader and cannot be bound at the top level (use import os and reference os.path inside functions, not import os as _os). Function bodies are not restricted — they run only when the agent calls them in a python cell.

Keep kernel.py small and self-contained (same guidance applies to kernel.R). If a helper wants more than ~100 lines, trim it to the core operations the agent actually calls; scripts/ is for standalone CLI tools run via bash, not for backing the sidecar. For kernel.py, the skill directory is not on sys.path, so from scripts.X import … fails — but the directory is on disk and readable. A Python sidecar function can locate it via its own co_filename to shell out to a scripts/ tool:

# kernel.py
import os, sys, subprocess

def run_pipeline(cfg_path):
    here = os.path.dirname(sys._getframe().f_code.co_filename)
    if not here:
        raise RuntimeError("skill dir unavailable in this runtime")
    tool = os.path.join(here, "scripts", "pipeline.py")
    return subprocess.run([sys.executable, tool, cfg_path],
                          capture_output=True, text=True, check=True).stdout

__file__ is not set (sidecars share one kernel namespace, so a global __file__ would point at whichever skill loaded last). co_filename is per-function and normally points at this skill's on-disk kernel.py; in rare cases (e.g. when the loader can't resolve the skill dir on disk) it falls back to the bare name "kernel.py" — hence the if not here guard above.

The runtime exports PYTHONSAFEPATH=1, which the subprocess.run child inherits — so python scripts/pipeline.py does NOT put scripts/ on the child's sys.path. A multi-file tool that does sibling imports must add sys.path.insert(0, os.path.dirname(__file__)) at the top of its entry script (or pass env={**os.environ, "PYTHONSAFEPATH": ""} to subprocess.run). If the child exits non-zero, capture_output=True hides the traceback — inspect CalledProcessError.stderr.

kernel.R has no runtime analogue of co_filename (the R loader parses with keep.source=FALSE), so an R sidecar that needs to reach scripts/ should take the path as an argument from the caller.

Minimal example:

# kernel.py
import pandas as pd  # starter-set package — OK at module scope

def annotate_df(df: pd.DataFrame, gene_col: str = "gene") -> pd.DataFrame:
    """Attach HGNC symbols; see SKILL.md ## Workflow step 3."""
    import requests  # not in starter set — defer to function body
    ...
    return df

Write sidecars via host.skills.edit(name, "kernel.py", src). When the gate probe can judge, the edit result carries sidecar_gate: {ok, error?} — the same structural gate the load path runs — so a reject (non-literal default, _-prefixed name, top-level call) surfaces immediately. When the probe can't judge (interpreter unavailable, or the source doesn't parse under the host's interpreter — possible version drift), the key is absent and note says why. Iterate against that; don't load the skill just to test the sidecar. host.skills.publish refuses only on a structural reject.