Skills Overview

Skills are bundles of related tools and prompt context that you assign to agents. When an agent has a skill, it gains access to the skill's tools and a relevant context fragment is injected into its system prompt. Skills are the primary way to give agents domain-specific capabilities.

What a skill is

A skill is a TypeScript module that exports a SkillDefinition object. It has:

• A manifest — metadata including a unique ID, category, and the list of tool names the skill activates
• An optional init function — runs once at startup for any initialization (e.g. loading API credentials, warm caches)
• An optional getPromptContext function — returns a string that is injected into the agent's system prompt when the skill is active, providing domain-specific instructions

Auto-discovery

Skills are discovered automatically at startup. The gateway scans src/skills/definitions/*/index.ts and imports each file. There is no manual registration step — create the file and the skill is live on next startup.

// src/skills/definitions/my_skill/index.ts
import type { SkillDefinition } from '../../types';

const skill: SkillDefinition = {
  manifest: {
    id: 'my_skill',
    displayName: 'My Skill',
    category: 'productivity',
    description: 'Does something useful',
    tools: ['my_tool_1', 'my_tool_2'],
  },
  async init() {
    // Optional: one-time initialization
  },
  getPromptContext() {
    return \`You have access to my_skill capabilities.
Use my_tool_1 for X and my_tool_2 for Y.\`;
  },
};

export default skill;

Assigning skills to agents

Add skill IDs to the agent's skills array in astra.yml:

agents:
  - id: my-agent
    skills:
      - git_ops
      - web_search
      - my_skill

When the agent starts a turn, each skill's tools are merged into the agent's effective allow list and each skill's getPromptContext() result is appended to the system prompt.

SkillDefinition interface

Skills vs. tools

A tool is a single callable function with Zod-typed parameters. A skill is a higher-level grouping: it activates one or more tools and provides domain-specific prompt guidance. Think of tools as verbs and skills as roles.