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

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions