Host support: Swival — skill collection installation, MCP configuration, and bounded lifecycle mapping

[ScriptedAlchemy]

Scope and evidence

P2 feature expansion. Researched 2026-09-06 from Swival's own documentation; Agent Bundle baseline 5fc8de37c9695b816d55bdcf18a6bcb1dfee69f5. No Swival process was run. Support means the verified skill/MCP/lifecycle surfaces below, not an invented all-purpose swival.plugin.json API.

Primary specifications and configuration guides

• Skills: frontmatter, discovery, activation and external access
• Library: staged versus active collections, installation and removal
• MCP: TOML/JSON schema, transports, precedence and output handling
• Lifecycle command invocation and failure semantics
• Safety and sandboxing
• Official documentation index / upstream link

Record the supported host/source revision. The research establishes current documented behavior, not native conformance of Agent Bundle output.

Skills and collections

A skill is an immediate directory containing SKILL.md, required name/description frontmatter and optional supporting scripts/resources. Names are constrained and must match directories. Swival truncates sufficiently long skill bodies, so the emitter should diagnose a document exceeding the supported limit rather than silently changing intended instructions.

Discovery prioritizes project .swival/skills, then .agents/skills, explicit extra paths and global roots. Duplicate names can hide a lower-priority skill. External/symlinked skill locations have read-only access semantics distinct from ordinary project files.

A downloaded global library collection is a staging shelf, not necessarily an active skill source. Do not report a collection as active merely because download succeeded.

Generated artifact and operator workflow

composite-root/
  skills/review/SKILL.md
  skills/review/references/guide.md
  .swival/mcp.json            # only if MCP is selected for this profile
  hooks/swival-lifecycle.mjs  # only for supported lifecycle declarations

The host installation flow consumes the root skills/ collection and puts it in the selected active/staged location; do not also copy it into every discovery root and cause duplicate identities.

swival skills add --ref v1.0.0 https://github.com/example/plugin
swival skills list
swival skills add --global https://github.com/example/plugin
swival skills add plugin
swival skills delete review

The example separates direct project installation from staging then activation; resolve actual collection/skill names from the host inventory. Use --global for an explicitly requested global target, not as the default for all Agent Bundle users. --skills-dir /absolute/composite-root/skills is an alternative development reference. A $review mention invokes the skill; slash-command syntax is not interchangeable.

MCP projection

Swival accepts [mcp_servers.<name>] in swival.toml or mcpServers in .swival/mcp.json. The TOML source wins same-name conflicts; --mcp-config chooses the JSON source but does not make it higher priority than TOML. --no-mcp remains authoritative.

Illustrative JSON configuration:

{"mcpServers":{"example":{"command":"node","args":["/absolute/composite-root/mcp/example.mjs"]}}}

Use the canonical executable record to resolve the illustrated path. Explicit transport fields distinguish Streamable HTTP from SSE; do not rely on fallback to prove the intended transport. The host namespaces tool names and can omit expensive or colliding tool catalogs, so a configured server is not proof that every tool was made available. Preserve sanitized environment behavior and operator secrets.

Lifecycle mapping, not a second event system

The documented lifecycle command runs at startup and exit, not per prompt or before every tool. It receives event and project-base arguments and native environment context. Command text is tokenized for direct subprocess execution, not a license to insert shell pipelines. Failure is configurable; default fail-open must remain explicit.

Example host config:

lifecycle_command = "node /absolute/composite-root/hooks/swival-lifecycle.mjs"
lifecycle_timeout = 30
lifecycle_fail_closed = false

Map only genuinely equivalent canonical lifecycle declarations. Reject per-tool permission hooks or per-turn injection requirements not supported by this interface. Preserve REPL versus per-context server lifetime and nested-reviewer behavior. Do not overwrite an operator's existing lifecycle command with an implicit chain; competing single-command ownership needs a diagnostic or explicit composition policy.

Acceptance and implementation

• Pin skills/MCP/lifecycle contracts and expose unsupported capabilities accurately.
• Static collection builds and installs without React, Flight, MCP or a persistent plugin process.
• Test project/global/explicit-root precedence, same-name conflicts, staged versus active collections, and disabled skill loading.
• Validate name/description/body limits and supporting-file containment, including external symlinks.
• Execute a generated MCP operation from a relocated source-free artifact; test schema/result, transport, namespace, missing server and cancellation outcomes.
• Verify TOML versus JSON precedence and native no-MCP behavior without modifying unrelated config.
• Lifecycle startup/exit run exactly at the documented times, with correct cwd, arguments, outcome and cleanup; unsupported per-tool use is rejected.
• Inspect and uninstall remove only owned active/staged entries and registrations; never delete the entire shared library or .swival state.
• Composite conformance proves required/forbidden discovery alongside other .agents readers.
• Record real-host completion separately from emitting a valid file; update English/Chinese setup instructions with source URLs.

Use existing skill lowering, adapter capability tables, manifest/evidence, install receipts and #651/#652 tests. Metaskills/Starlark, Python Session embedding, A2A/ACP orchestration, model-provider selection and remote-state synchronization are not prerequisites.

[ScriptedAlchemy]

Landed in #727, squash-merged as b5cf7575e0 on main.

Swival reads the artifact Agent Bundle already emits, so this needed no adapter, projection, or compiler change — the support is one pinned record in packages/agent-bundle/src/adapters/capabilities/portable-1.0.0.json, which feeds the generated en/zh hosts reference, the generated INSTALL.md, and the discovery tests. Everything below was read against swival.dev on 2026-09-06 (no product version is published on the documentation pages).

Tier: skills. Registration hands Swival the emitted tree where it lies:

swival --skills-dir <plugin directory>/skills "<task>"

skills_dir in swival.toml makes the same directory persistent; swival skills add is the copy-in path and is not what this record claims. swival skills list is the inspection command.

Surface	State	Evidence
skills	partial	The emitted skills/ layout is exactly what pages/skills.html requires — "Every immediate subdirectory that contains SKILL.md is treated as a skill", name lowercase-alphanumeric and matching the directory — and --skills-dir reads "a parent directory where nested subdirectories contain skill files" in place. Partial, not full: the emitted root is not a default location, and "If the same skill name exists in multiple locations, the first one in the precedence order wins" puts .swival/skills/ and .agents/skills/ ahead of --skills-dir paths. A registered tree outside the project resolves as external, which Swival adds "as read-only roots".
manifest	unsupported	Swival discovers skill directories and MCP configuration and publishes no plugin manifest of any kind (skills, mcp), so the emitted root plugin.json is read by nothing there.
mcp	unsupported	MCP servers come from swival.toml [mcp_servers.*] or .swival/mcp.json (pages/mcp.html). The emitted document is a shape Swival reads — it accepts mcpServers with command/args/env and url/type/headers, and its accepted type values include stdio "so configs copied from other MCP clients load unchanged" — but only an invocation that passes --mcp-config at this file reads it, and that flag "replaces the default .swival/mcp.json lookup" rather than adding to it, while "TOML servers (swival.toml [mcp_servers.*]) always win by server name over JSON servers". The recorded registration does not pass it, so no Swival MCP source is claimed for this artifact.
placeholders	unsupported	No ${PLUGIN_ROOT} or ${PLUGIN_DATA} expansion is documented for Swival MCP configuration; the documented substitution surface is the skill body and its own directory path, so Agent Plugins 1.0.0 §9.1 reserved behavior is not provided.
hooks	unsupported	Agent Plugins 1.0.0 defines no hooks, so this projection emits no hooks document for Swival to read.

Deferred: nothing. A user who wants the emitted mcp.json in Swival can pass --mcp-config <plugin directory>/mcp.json, but that replaces their .swival/mcp.json and loses by name to swival.toml, so it is a documented trade-off rather than a surface this artifact delivers — the row says so with the quotes rather than claiming it.

Rendered claims are held to the emitted plan, not to the record: packages/agent-bundle/tests/install-surface.test.ts :: claims only the paths a portable bundle with <inventory> emits asserts Swival's line across all four component inventories (no component, skills only, MCP only, skills and MCP), including that the Register: command and the partial-skills note appear only when the build actually wrote skills/.