Skip to content

Handle persona skills installation in SDK #824

@willwashburn

Description

@willwashburn

Today @agent-relay/sdk's persona loader (packages/sdk/src/personas.ts) explicitly skips skills installation:

Skills installation, mount policy, sidecar markdown, input rendering, and routing profiles are deliberately not handled here — callers needing those should use the agentworkforce CLI directly.

This means a persona authored against skills.sh or prpm.dev sources spawns fine via relay but is missing the skills the persona depends on, and there's no parity with agentworkforce for SDK consumers.

Repro

A persona declares:

"skills": [
  { "source": "https://github.com/wsimmonds/claude-nextjs-skills#nextjs-anti-patterns" },
  { "source": "vercel/some-prpm-skill" }
]

Spawning via AgentRelay.spawnPersona → harness boots without those skills. Same persona under agentworkforce <id> runs:

npx -y skills add https://github.com/wsimmonds/claude-nextjs-skills --skill nextjs-anti-patterns -y
npx -y prpm install vercel/some-prpm-skill --as <harness>

…before launch.

Proposal

Add an opt-in installSkills step (default off, or behind a { skills: 'install' } flag on spawnPersona) that:

  1. Parses skills[].source (mirrors materializeSkills in AgentWorkforce's packages/workload-router/src/index.ts — supports prpm URL, bare <scope>/<name>, skill.sh <repo>#<skill>, and skill.sh tree URLs).
  2. Builds the same install commands AgentWorkforce builds.
  3. Runs them in the spawn cwd (or a caller-supplied install root) before launch, with the same exit-code-aware abort behavior.
  4. Surfaces the install plan as a pure value (no execution) so callers can dry-run for validation — useful for persona authoring tools that want to verify a skill source resolves before committing the JSON.

Step 4 is the part I want most: a materializeSkills(persona, harness) export that returns the install plan without running it. That alone unlocks pre-launch validation in tools like persona-maker, and the execute step can land later.

Why in relay (vs. shelling out to agentworkforce CLI)

  • SDK consumers building persona-launching apps shouldn't need a second CLI dep just to honor skills[].
  • The persona schema is already mirrored in relay's PersonaFile — honoring it fully is less surprising than silently dropping a declared field.
  • Authoring-time validation (catching a hallucinated skill name like nextjs-anti-patterns before it ships in a persona JSON) needs a pure plan/parse function, not a full CLI run.

Out of scope

  • Mount policy, sidecar markdown, routing profiles — keep deferred to the AgentWorkforce CLI for now.
  • Skill cleanup paths post-spawn (separate concern; can land with the execute step).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions