Skills

Skills are modular instruction packages that an application makes available to an agent. The system prompt contains only each skill's name, description, and model-visible SKILL.md path. When a skill applies, the model reads the full instructions through its file tools.

Ownership

The application owns both provisioning and discovery:

createBashTool() does not upload, mount, discover, or expose skills. The skills() fragment does not inspect a sandbox or filesystem. This keeps the context layer independent from local directories, GCS, container volumes, and provider-specific upload APIs.

AvailableSkill

The caller describes each available skill with one model-facing type:

interface AvailableSkill {
  name: string;
  description: string;
  /** Path to SKILL.md as seen by the model's file tools. */
  path: string;
}

path is the runtime-visible file path, not a host-side source path. For example, if a GCS-backed volume is mounted at /skills, the catalog might be:

import type { AvailableSkill } from '@deepagents/context';

const availableSkills: AvailableSkill[] = [
  {
    name: 'deploy',
    description: 'Deploy services with safe rollout checks.',
    path: '/skills/deploy/SKILL.md',
  },
  {
    name: 'data-analysis',
    description: 'Analyze datasets and summarize findings.',
    path: '/skills/data-analysis/SKILL.md',
  },
];

GCS is storage, not an implicit skills registry. Your application can build this array from a GCS manifest, a database, configuration, or its own scan of the mounted filesystem. The context package does not choose one of those sources.

Provision the Files

Provisioning happens before the fragment is created. A container application can mount a volume when it creates the sandbox backend:

const backend = await createDockerSandbox({
  volumes: [
    {
      type: 'bind',
      hostPath: '/mnt/gcs/agent-skills',
      containerPath: '/skills',
      readOnly: true,
    },
  ],
});

const sandbox = await createBashTool({ sandbox: backend });

The same boundary applies to other runtimes: the application may use a native volume, image layer, remote sandbox API, or a generic file-copy step. Whatever mechanism it uses must make every supplied AvailableSkill.path readable by the model's tools.

Add the Catalog to Context

Pass the explicit array to skills():

import {
  ContextEngine,
  InMemoryContextStore,
  role,
  skills,
} from '@deepagents/context';

const context = new ContextEngine({
  store: new InMemoryContextStore(),
  chatId: 'chat-001',
  userId: 'user-001',
}).set(
  role('You are a helpful assistant.'),
  skills(availableSkills),
);

The fragment renders:

1. instructions explaining progressive disclosure and trigger rules; and
2. one skill entry per supplied item, containing name, description, and path.

It does not check that paths exist. File accessibility remains the application's responsibility.

Read the Catalog from Context

ContextEngine.getAvailableSkills() returns the catalog stored by the first available_skills fragment:

const catalog = context.getAvailableSkills();
// [{ name: 'deploy', description: '...', path: '/skills/deploy/SKILL.md' }]

The agent uses this same catalog for GuardrailContext.availableSkills, so a guardrail that corrects skill/tool confusion refers to the exact path shown to the model.

Parse Frontmatter Content

parseFrontmatter() remains available as a host-neutral utility. It parses a string that your application has already read; it does not read a path or discover directories.

import { parseFrontmatter } from '@deepagents/context';

const source = `---
name: deploy
description: Deploy services safely
---

## Workflow
1. Validate
2. Roll out`;

const { frontmatter, body } = parseFrontmatter(source);

Your discovery code can combine the parsed name and description with the runtime path it assigned to build an AvailableSkill.

Skill Reminders

The baseline skills() fragment lists the entire explicit catalog. skillsReminder() is separate: it ranks the same AvailableSkill[] against a user message and repeats the most relevant entries as a reminder. See Skill Reminders.

Provider-Native Skills

AI providers may offer APIs that upload file content into a provider-managed skill store. That is a separate deployment model. Files already exposed to an agent through a mounted volume do not need to be uploaded by this fragment or by createBashTool().

Next Steps

• Sandbox — choose and provision a runtime filesystem
• Skill Reminders — surface relevant skills per query
• Guardrails — inspect available skills during streaming