Skills

Skills are eve’s way to keep reusable procedures available without forcing every procedure into every model turn. A skill is a model-loadable markdown procedure that follows the SKILL.md convention, and it can be either a single markdown file or a packaged directory with supporting files. The important design point is progressive disclosure: eve advertises the short description of each skill, while the full instructions are loaded only when the task calls for them. That keeps the active context focused while still giving the model access to specialized playbooks, checklists, policies, or domain procedures when they become relevant.

Sources: docs/skills.mdx

Purpose and Scope

Use a skill when the agent needs procedural knowledge rather than a new callable function. For example, a release checklist, research workflow, incident response playbook, or forecasting rubric can live as a skill because it primarily teaches the model how to approach a task. Loading a skill adds instructions to the current turn, not a new execution surface. If the capability must validate structured inputs, call an external service, perform side effects, or return typed runtime data, the source documentation directs authors toward tools instead of skills.

Sources: docs/skills.mdx

Skills also give teams a clean place to manage optional knowledge. The always-on instruction file should stay small enough to define identity, policy, and standing behavior. Skills hold procedures that are valuable only for particular tasks, so the model can pull them in on demand. This separation matters as an agent grows: it lets maintainers add new reusable workflows without bloating the baseline prompt, and it makes each procedure easier to review as a standalone artifact with its own description, body, and optional package files.

Sources: docs/skills.mdx

Relevant Source Files

• docs/skills.mdx — Defines the public authoring model for skills, including the SKILL.md convention, load_skill behavior, markdown and TypeScript forms, agent scoping, runtime file access, and dynamic skill guidance.

Core Primitives

The central primitive is the skill document. In the smallest form, a skill is a markdown file under agent/skills/, with the skill name coming from the file path and the body acting as the procedure. In packaged form, the skill is a directory containing SKILL.md plus siblings such as references, assets, or scripts. In TypeScript form, defineSkill from eve/skills creates the same package shape from structured fields. All three forms express the same idea: a named, described procedure that can be loaded into context when useful.

Sources: docs/skills.mdx

The second primitive is the framework-owned load_skill tool. eve scans agent/skills/ and exposes each skill description beside that tool, so the model can decide whether a user request matches a procedure. The description is therefore a routing hint rather than a display label. It should describe the kind of work that should activate the skill, such as a release workflow or unfamiliar-topic research task. A vague title-like description is less useful because the model needs to infer when the full procedure should be brought into the turn.

Sources: docs/skills.mdx

The third primitive is runtime skill file access. Loading a skill appends its SKILL.md content to the active context, but packaged skills can also include sibling files. When a tool or hook needs one of those files, it can use ctx.getSkill(id) to obtain a handle and read a package-relative file lazily from the active sandbox. This keeps large references out of prompt context until executable code actually needs them, while still allowing a skill package to carry the materials that support its procedure.

Sources: docs/skills.mdx

Authoring Forms

Start with plain markdown when the procedure is static text. A flat markdown skill is the quickest form and can omit description frontmatter. When that frontmatter is absent, eve advertises the first non-empty, non-code-fence line of the body after stripping leading markdown markers such as headings, quotes, bullets, or emphasis markers. If no usable line exists, eve falls back to a generic sentence for the skill name. That fallback is intentionally weak as a routing signal, so authors should add an explicit description whenever routing accuracy matters.

Sources: docs/skills.mdx

Use the weather tool before answering forecast or temperature questions.

Use a packaged skill when the procedure needs nearby supporting materials. A directory skill uses SKILL.md as the loadable instruction file and may include references, assets, or scripts beside it. Unlike a flat markdown file, the packaged SKILL.md must include description frontmatter because the directory itself does not provide the same filename-body fallback. This form is useful for workflows that need checklists, templates, supporting examples, or other files that should be versioned with the skill but not necessarily pasted into every model turn.

Sources: docs/skills.mdx

---
description: Research unfamiliar topics before answering with confidence.
---
 
When the task is novel or ambiguous, gather evidence first, then answer with the
key facts and the remaining uncertainty.

Use TypeScript with defineSkill when markdown alone is not expressive enough. The documentation calls out typed values, generated content, and inline sibling files as reasons to move beyond static markdown. In that form, the exported value includes a description, markdown body, and files map. eve generates SKILL.md from the markdown field, and each files entry becomes a package-relative sibling. This makes TypeScript a packaging convenience, not a different capability model: the result is still a skill that is advertised by description and loaded as instructions.

Sources: docs/skills.mdx

import { defineSkill } from "eve/skills";
 
export default defineSkill({
  description: "Research unfamiliar topics before answering with confidence.",
  markdown:
    "When the task is novel or ambiguous, gather evidence first, then answer with the key facts and the remaining uncertainty.",
  files: {
    "references/checklist.md": "# Checklist\n\n- Find primary sources.\n",
  },
});

Discovery, Resolution, and Scope

Skill discovery is filesystem-oriented. eve scans the agent/skills/ area for authored skills and exposes descriptions to the model. The model then calls load_skill when the user request matches a description or when the skill is named directly. The full markdown enters only the active turn’s context, so skills behave like load-on-demand instructions rather than globally resident prompt text. This also means authors should write skill bodies as procedural guidance: explain when to gather evidence, which tool to use, what order to follow, and how to report uncertainty or results.

Sources: docs/skills.mdx

Skills are scoped to the agent that declares them. The documentation explicitly states that a subagent’s skills are invisible to the root agent, and the root agent’s skills are invisible to the subagent. There is no shared-skill mechanism. If several agents need the same executable helper, put that helper in a shared lib area and call it from tools or hooks as appropriate. If several agents need the same written procedure, copy or package it deliberately for each agent so ownership and routing remain explicit.

Sources: docs/skills.mdx

Dynamic skills are the extension point when the available procedures depend on runtime state. The skills guide points dynamic capability needs to defineDynamic, which is intended for cases where different callers, tenants, projects, or feature flags should see different capabilities. The same conceptual rule still applies: a dynamic skill should resolve to a described procedure that the model can load when useful. Treat the description as part of authorization and routing design, because it controls what the model knows is available before the full skill body is loaded.

Sources: docs/skills.mdx

Runtime File Access

Packaged skills often contain more than the markdown body that should enter context. A research skill might include a checklist, a glossary, or supporting reference files. When runtime code needs those files, it should use the skill handle rather than hard-coding independent filesystem assumptions. The documented access pattern calls ctx.getSkill with the skill id, then reads a relative file through the handle. The file content is loaded lazily from the active sandbox, which keeps normal model context smaller and aligns supporting assets with the skill package that owns them.

Sources: docs/skills.mdx

const research = ctx.getSkill("research");
const checklist = await research.file("references/checklist.md").text();

The handle exposes the skill name and a file(relativePath) accessor. This distinction is useful when designing a tool that cooperates with a skill. The skill can teach the model when and why to use a procedure, while the tool can read packaged references or perform typed work. The loaded skill instructions do not create new tools, and the tool list does not depend on whether a skill was loaded. This keeps execution capabilities stable while allowing procedural context to vary by turn.

Sources: docs/skills.mdx

Compact Reference

Practical Guidance and Next Steps

A good skill description should sound like a trigger condition. Prefer wording such as “Use when the user needs a release checklist or changelog workflow” over a bare noun phrase. A good skill body should be concrete enough to guide behavior after loading: define the sequence, decision points, required evidence, expected output shape, and any cautions. If the procedure depends on executable work, pair the skill with a tool rather than embedding implementation details in prose. If the procedure depends on large references, package those references beside SKILL.md and read them lazily when needed.

Sources: docs/skills.mdx

After authoring a skill, test it with user requests that should and should not trigger loading. If the model ignores a useful skill, improve the description before expanding the body. If the model loads a skill too often, narrow the trigger language. For related authoring decisions, read the tools guide when you need typed execution, the subagents guide when capability ownership crosses agent boundaries, the dynamic capabilities guide when procedures depend on runtime context, and the project layout reference when organizing files under the agent directory.