Skills

Skills are reusable instruction packages that teach agents how to perform specific tasks. They follow the YAML frontmatter + Markdown body pattern.

Using with AgentSession

import { createAgentSession } from '@philschmid/agent';

const session = createAgentSession({
  model: 'gemini-3-flash-preview',
  tools: ['read', 'write', 'skills'],  // Enable skills tool
});

session.send('Use the code-review skill to analyze src/index.ts');

Discovery Sources

Skills are loaded from multiple sources with a defined precedence. When two skills share the same name, the first match wins:

1. Project (.agent/skills/) — highest priority
2. Global (~/.agent/skills/) — shared across projects
3. Built-in (shipped with @philschmid/agent) — lowest priority

# Project skills (highest priority)
.agent/skills/my-skill/SKILL.md

# Global skills (shared across projects)
~/.agent/skills/my-skill/SKILL.md

# Built-in skills (shipped with the package)
# e.g. skill-creator

Configuration

Override the paths with environment variables:

# Override project artifacts path (default: .agent)
export AGENT_ARTIFACTS_PATH=".agent"

# Override global artifacts path (default: ~/.agent)
export AGENT_GLOBAL_ARTIFACTS_PATH="/custom/global/path"

SKILL.md Format

---
name: code-reviewer
description: Reviews code for quality, security, and best practices
---

You are an expert code reviewer. When reviewing code:

## Review Checklist
1. Check for security vulnerabilities
2. Verify error handling
3. Review naming conventions

Required Fields

Field	Type	Description
name	string	Unique identifier (used for loading)
description	string	Brief summary (used for skill selection)

Loading Skills

import { loadSkills, type ArtifactLayer } from '@philschmid/agent';

// Load from all default sources (project + global + built-in)
const skills = loadSkills();

// Load from specific layers
const skills = loadSkills([
  { path: '.agent', source: 'project' },
  { path: '/custom/path', source: 'global' },
]);

Skill Type

type Skill = {
  name: string;        // From frontmatter
  description: string; // From frontmatter
  content: string;     // Markdown body
  path: string;        // Directory path
  source: 'project' | 'global' | 'builtin';
};

Disabling Skills

Disable specific skills by name:

# Via environment variable (comma-separated)
export AGENT_DISABLED_SKILLS="skill-creator,other-skill"

Or in settings.json:

{
  "disabledSkills": ["skill-creator"]
}

Best Practices

1. Keep frontmatter minimal: Only name and description
2. Use clear, specific descriptions: Helps with skill selection
3. Structure the body: Use headings, lists, and code blocks
4. Bundle resources: Include scripts or templates in the skill directory
5. Override built-ins: Create a project skill with the same name to customize

---

Next Steps

• Subagents: Delegate to specialized agents
• Session: Multi-turn conversations with skills
• Built-in Tools: All available tools