git:20260703.9bb1ad2 to git:20260721.77e7d29

- description: Create, configure, and maintain custom agent profiles and author new skills via the `repl` tool. Use when the user wants to create an agent profile, build a custom agent, modify agent capabilities, attach or detach skills/connectors on a profile, author a skill, or inspect which connectors and tools are available. Also use whenever you need the `host.agents.*` or `host.skills.*` Python SDK.

- license: Apache-2.0

- ---

-

- # 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 wisp-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`

-

- ```python

- 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`

-

- ```python

- 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:

-

- ```python

- # repl tool

- import json, os

- os.makedirs("handoff", exist_ok=True)

- profiles = host.agents.list()

- json.dump(profiles, open("handoff/agents.json", "w"))

- ```

-

- ```python

- # 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:

-

- ```python

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

- ```

-

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

-

- ```python

- # 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:

- ```python

- # 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:

- ```python

- # 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.