Skills

skills() makes a Workspace or external Source Skill available to an Agent Invocation.

For an Agent-owned Skill, use a folder Agent Definition whose entry file is named agent.ts, agent.js, index.ts, or index.js, including their c and m variants, then place skills/ beside that entry file. ViteHub discovers and materializes those files automatically, so local Skills do not need a Capability declaration. Flat files such as server/agents/support.ts do not discover sibling Skills.

The Capability records the configured Skill path in metadata and requires the Workspace path to exist. When shellExecution is set, model-backed Agents receive the normal Workspace Shell tools in the requested mode. When source is set, ViteHub adds that source to the Agent Workspace at definition time and mounts it at the skill path.

Model-facing guidance for a Skill belongs in Agent Driver Instructions or deterministic imported instruction Markdown. Agent inspection metadata warns when skills() makes a Skill available but no explicit instruction coverage names it.

Configure a Skill

The default path is skills/SKILL.md. Pass a custom path when the Workspace stores the skill somewhere else.

import { defineAgent } from 'vite-hub/agent'
import { skills } from 'vite-hub/agent/capabilities'

export default defineAgent({
  driver: { model },
  workspace,
  capabilities: [
    skills(),
  ],
})

Mount a remote skill source when the skill file lives outside the local project:

import { defineAgent } from 'vite-hub/agent'
import { skills } from 'vite-hub/agent/capabilities'
import { github } from 'vite-hub/workspace'

export default defineAgent({
  driver: { model },
  workspace: { name: 'review', mode: 'write' },
  capabilities: [
    skills({
      path: 'skills/agent-browser',
      source: github({
        repo: 'vercel/vercel-plugin',
        root: 'skills/agent-browser',
        include: ['SKILL.md', 'references/**', 'templates/**'],
        materialize: 'build',
      }),
      shellExecution: 'write',
    }),
  ],
})

How Skills are loaded

ViteHub validates the Workspace read requirement before the Agent Driver runs. The Capability metadata includes the directory path and the resolved SKILL.md path. Model-facing Skill guidance belongs in Agent Driver Instructions or deterministic imported instruction Markdown with an explicit ::skill{path="..."} coverage block. For provider-backed drivers, skills() contributes the skill directory to the Provider Workspace session instead of adding model-facing instructions or tools. With shellExecution: 'write', model-backed Workspace Shell writes commit Workspace Session changes back into the Workspace. With source, ViteHub still uses normal Workspace Source materialization, visibility, and Agent inspection metadata. skills() does not fetch source files at invocation time.

Requirements

Workspace-scoped skills() requires an explicit Workspace with read access to the configured skill file. The path can point to a directory or directly to a SKILL.md file. When source is configured, path is the canonical mount. ViteHub mounts the source at the configured skill directory even when the source helper has its own default mount. File Sources are single-file and root-confined. Use a directory-capable github() or custom() Source, or a root-confined glob() Source, when a Skill source is a directory.

Driver support

Verify the Skill

Run the Agent with the configured Workspace. Confirm that a missing skill file fails before model execution with a Workspace path requirement error.

Inspect Capability metadata for the normalized path and skillPath values. Agent inspection metadata warns when a configured Skill lacks explicit instruction coverage. The warning clears when Agent Driver Instructions or a deterministic imported instruction file covers the Skill.

Options

Cover Skill usage guidance in Agent Driver Instructions with explicit Skill coverage blocks. Keep tool descriptions with Workspace Shell tools because they are structured tool contracts.

Related pages

• Workspace primitive
• Agent instructions