Skip to main content

createSkill()

Creates an inline skill that can be passed directly to an agent's skills config without a filesystem or workspace.

The returned object implements the Skill interface and works anywhere a filesystem-discovered skill works.

Usage example
Direct link to Usage example

src/mastra/skills.ts
import { createSkill } from '@mastra/core/skills'

const reviewSkill = createSkill({
  name: 'code-review',
  description: 'Use when reviewing code changes.',
  instructions: `
    When reviewing code:
    1. Check for correctness
    2. Check for style consistency
    3. Look for potential bugs
  `,
  references: {
    'checklist.md': '# Review Checklist\n- No unused imports\n- Error handling present',
  },
})

Parameters
Direct link to Parameters

name:

string
Unique skill name. Used as the identifier when agents activate the skill. Must be a valid slug (lowercase, hyphens allowed).

description:

string
Short description shown to the agent in the system message. Helps the agent decide when to use the skill.

instructions:

string
The full skill instructions in markdown. Loaded into the conversation when the agent activates the skill.

references?:

Record<string, string>
Supporting documents the agent can read with the `skill_read` tool. Keys are filenames, values are file contents.

license?:

string
SPDX license identifier for the skill.

compatibility?:

unknown
Compatibility requirements. The Agent Skills spec leaves this flexible — can be a string array, object, or any structure your tooling expects.

user-invocable?:

boolean
Whether end users can invoke this skill directly. Defaults to `undefined` (agent decides).

metadata?:

Record<string, unknown>
Arbitrary metadata attached to the skill.

Return value
Direct link to Return value

Returns an InlineSkill object that implements the Skill interface:

interface InlineSkill extends Skill {
  __inline: true
  __referenceContents: Record<string, string>
}

The skill is assigned a synthetic path of inline/<name> (e.g., inline/code-review).

Validation
Direct link to Validation

createSkill() validates inputs using the same rules as filesystem skills:

  • name is required and must be a valid slug
  • description is required
  • instructions is required and non-empty

If validation fails, an Error is thrown with details about the invalid fields.

// Throws: Invalid skill "": name is required
createSkill({ name: '', description: 'test', instructions: 'test' })
On this page