@vsuite/catalog

The static catalog of agents, skills, capabilities, targets, MCP servers, and stack technologies that vsuite can generate, plus resolution over that catalog and the template context schema. Non-goals: rendering artifact bodies (@vsuite/templates), target file formats (@vsuite/targets), and reading vsuite.json (@vsuite/config).

This is a private, source-only workspace package (exports → ./src/index.ts). It is bundled into the @krizic/vsuite CLI and is not published to npm. Workspace consumers depend on it with "@vsuite/catalog": "workspace:*".

Public API

Export	Kind	Signature	Description
`targetIds`	const	`readonly ["opencode", "claude-code", "github-copilot"]`	Supported targets.
`TargetId`	type	`(typeof targetIds)[number]`	Target identifier.
`agentIds`	const	`readonly AgentId[]` (19 ids)	All catalog agent ids.
`AgentId`	type	`(typeof agentIds)[number]`	Agent identifier.
`skillIds`	const	`readonly SkillId[]` (36 ids)	All built-in skill ids: `coreSkillIds` (10) plus `conventionSkillIds` (26).
`SkillId`	type	`(typeof skillIds)[number]`	Built-in skill identifier.
`capabilityIds`	const	`readonly ["agent-metrics", "agent-memory", "brainstorming", "context7", "playwright", "prisma"]`	Optional capabilities.
`CapabilityId`	type	`(typeof capabilityIds)[number]`	Capability identifier.
`neutralTools`	const	`readonly ["read", "edit", "search", "execute", "web", "browser", "todo", "agent"]`	The tool vocabulary of `vsuite.json` `agents.<id>.tools`.
`agentTools`	const	`readonly AgentTool[]`	Tool names catalog agent definitions use (the neutral vocabulary plus Copilot-style MCP tool names).
`AgentTool`	type	`(typeof agentTools)[number]`	Tool name.
`preferenceKeys`	const	`readonly ["frontend.framework", "frontend.designLibrary", "tracking.provider", "documentation.location"]`	Preference keys an artifact can require.
`PreferenceKey`	type	`(typeof preferenceKeys)[number]`	Preference key.
`ArtifactDefinition`	type	`interface ArtifactDefinition<Id extends string>`	Common fields: `id`, `description`, optional `label` and `whenToUse`, `defaultSelected`, `optional`, `targets`.
`AgentDefinition`	type	`interface extends ArtifactDefinition<AgentId>`	Agent metadata: required skills/capabilities, preferences, tools, handoffs.
`SkillDefinition`	type	`interface extends ArtifactDefinition<SkillId>`	Skill metadata: required skills/capabilities, recommended agents, optional tool restriction.
`CapabilityDefinition`	type	`interface extends ArtifactDefinition<CapabilityId>`	Capability metadata.
`HandoffDefinition`	type	`{ label: string; agent: AgentId; prompt: string }`	Suggested next step to another agent.
`RenderableSkill`	type	`{ id; description; content; kind: "built-in" \| "project"; tools? }`	A skill ready to be written to a target.
`ResolvedSelection`	type	`{ agents: AgentId[]; skills: SkillId[]; projectSkills: string[]; capabilities: CapabilityId[] }`	Output of `resolveSelection`, each list sorted.
`agents`	const	`Record<AgentId, AgentDefinition>`	Agent catalog.
`skills`	const	`Record<SkillId, SkillDefinition>`	Skill catalog.
`capabilities`	const	`Record<CapabilityId, CapabilityDefinition>`	Capability catalog.
`defaultAgentIds`	const	`AgentId[]`	Agents with `defaultSelected`.
`defaultSkillIds`	const	`SkillId[]`	Skills with `defaultSelected`.
`defaultCapabilityIds`	const	`CapabilityId[]`	Capabilities with `defaultSelected`.
`targetDirectories`	const	`Record<TargetId, string>`	`.opencode`, `.claude`, `.github`.
`isKnownAgent`	function	`(id: string) => id is AgentId`	Catalog membership check.
`isKnownSkill`	function	`(id: string) => id is SkillId`	Catalog membership check; unknown ids are treated as project skills.
`isKnownCapability`	function	`(id: string) => id is CapabilityId`	Catalog membership check.
`resolveSelection`	function	`(agentIds: readonly AgentId[], skillIds: readonly string[], capabilityIds?: readonly CapabilityId[]) => ResolvedSelection`	Expands required skills and capabilities transitively.
`supportsTargets`	function	`(selection: ResolvedSelection, selectedTargets: readonly TargetId[]) => boolean`	True if every selected agent, skill, and capability supports every target.
`mcpServerIds`, `mcpServers`, `vsuiteMcpServer`, `vsuitePaths`, `agentMemoryPaths`	consts		MCP server catalog, the built-in `vsuite` server, and the project-local `.vsuite/` paths.
`stackTechnologies`, `stackCategories`, `resolveStack`, `stackOwnership`, `findStackTechnology`	consts, functions		Stack registry and the ownership rules that map technologies to agents, skills, and MCP servers.
`templateContextSchema`, `SUPPORTED_CONTEXT_VERSIONS`	consts		Template context contract (`pnpm --filter @vsuite/catalog run schema:context` writes `schema/template-context.v2.json`; `docs/packs/context-reference.md` is generated from it by `scripts/gen-context-reference.mjs`).

src/index.ts exports further helpers (isNeutralTool, isKnownMcpServer, declarableCapabilityIds, preference choices, and others); it is the authoritative list.

Dependencies

Workspace: none.
Third-party: zod.
Used by: every other workspace package.

Diagrams

flowchart TD
  IN["agentIds, skillIds, capabilityIds"] --> SPLIT{"skill id known to catalog?"}
  SPLIT -- yes --> SEL["selectedSkills + pending queue"]
  SPLIT -- no --> PROJ["projectSkills"]
  IN --> AG["for each agent: add requiredSkills to selectedSkills and queue; add requiredCapabilities"]
  AG --> Q{"pending queue empty?"}
  SEL --> Q
  Q -- no --> POP["pop skill: add its requiredSkills (queue new ones) and requiredCapabilities"]
  POP --> Q
  Q -- yes --> OUT["ResolvedSelection: agents, skills, projectSkills, capabilities, each sorted"]
  PROJ --> OUT

Usage

import { resolveSelection, supportsTargets } from "@vsuite/catalog";
 
const selection = resolveSelection(["orchestrator"], ["my-project-skill"], ["context7"]);
supportsTargets(selection, ["opencode", "claude-code"]);

Testing

pnpm vitest run --project @vsuite/catalog