Using Workspaces to Reuse Repos, Skills, and Agent Selection — Agentuity Documentation

Using Workspaces to Reuse Repos, Skills, and Agent Selection

Store reusable Coder selections in a workspace and attach them to sessions with workspaceId

Workspaces save a session setup once and reuse it everywhere by workspaceId. They hold the selections your app repeats most often: saved skills, agent selection, and (once your app has them) repository refs. That means you aren't re-listing those on every createSession() call.

The Pattern

Create a workspace, then create a session that points at it:

import { CoderClient } from '@agentuity/coder';
 
const DEFAULT_TASK =
  'Use the workspace selections to review the repo, identify the biggest implementation risk, and recommend a focused next step.';
 
function getTask(): string {
  const task = process.argv.slice(2).join(' ').trim();
  return task || DEFAULT_TASK;
}
 
async function main(): Promise<void> {
  const client = new CoderClient();
  const task = getTask();
 
  // Save the skill into the library first so the workspace can own it by id
  const savedSkill = await client.saveSkill({
    repo: 'anthropics/skills',
    skillId: 'frontend-design',
    name: 'frontend-design',
    description: 'Design-focused frontend implementation guidance.',
    url: 'https://skills.sh/anthropics/skills/frontend-design',
  });
 
  // Workspaces bundle reusable selections (skills, agents, repos) behind a single id
  const workspace = await client.createWorkspace({
    name: `workspace-${Date.now()}`,
    description: 'Reusable selections for review-oriented sessions.',
    savedSkillIds: [savedSkill.id],
    agentSlugs: ['builder', 'reviewer'], 
  });
 
  // Passing workspaceId is enough; the session inherits the workspace selections
  const created = await client.createSession({
    task,
    workflowMode: 'standard',
    workspaceId: workspace.id, 
    // defaultAgent can still be set per session even when a workspace supplies the agent list
    defaultAgent: 'builder',
  });
 
  // Read the session back to confirm the workspace selections took effect
  const session = await client.getSession(created.sessionId);
 
  console.log(
    JSON.stringify(
      {
        workspaceId: workspace.id,
        sessionId: session.sessionId,
        defaultAgent: session.defaultAgent,
        skills: session.skills.map((skill) => ({
          repo: skill.repo,
          skillId: skill.skillId,
          name: skill.name,
        })),
      },
      null,
      2
    )
  );
}
 
void main();

Example Output

{
  "workspaceId": "ws_956cc248e682",
  "sessionId": "codesess_2f3af05751fb",
  "defaultAgent": "builder",
  "skills": [
    {
      "repo": "anthropics/skills",
      "skillId": "frontend-design",
      "name": "frontend-design"
    }
  ]
}

What this means:

  • the workspace stored the reusable selections
  • workspaceId carried those selections into the session
  • you can still set a default agent like builder when you create the session

Where Repositories Fit

Once your app has a valid CoderSessionRepositoryRef, add it to the same workspace:

// Store repo, skill, and agent selections together so later createSession calls need only workspaceId
const workspace = await client.createWorkspace({
  name: 'review-workspace',
  repos: [repoRef], // Repository ref your app already resolved
  savedSkillIds: [savedSkill.id],
  agentSlugs: ['builder', 'reviewer'],
});

That keeps repo, skill, and agent selections in one reusable object. If your app doesn't have repository refs yet, start with skills and agents and layer repositories in later.

When to Use This Pattern

Use this pattern when you want:

  • one saved setup reused across multiple sessions
  • less duplication in your session creation code
  • a stable place to store reusable skill and agent selections
  • session creation that starts from a named workspace instead of a long config object

Key Points

  • Workspaces pay off when the same selections repeat across sessions.
  • A workspace can't be empty. Include at least one repo, saved skill, skill bucket, or agent selection.
  • workspaceId doesn't replace the normal session lifecycle APIs; create, inspect, archive, and delete sessions the same way.
  • Read the session back after creation to confirm the workspace selections flowed through.

See Also