Skills

Skills are reusable prompt modules. Each skill is a SKILL.md file containing domain-specific instructions, workflows, and references. When the LLM recognizes a task matches a skill, it loads the skill's content into the conversation — giving the agent specialized knowledge for that task without modifying the system prompt.

Skills are not executable tools. They don't run code, have no security checks, and produce no visualization. They're pure instruction content.

Creating a Skill

Create a folder in .agents/skills/ inside your workspace, then add a SKILL.md file:

your-workspace/
└── .agents/
    └── skills/
        └── code-review/
            └── SKILL.md

The folder name doesn't matter — the skill's identity comes from the name field in the frontmatter.

SKILL.md Format

YAML frontmatter + markdown body:

---
name: code-review
description: Review code for bugs, style issues, and best practices
user-invocable: true
---

# Code Review

When reviewing code, focus on:
- Bug detection
- Performance issues
- Security vulnerabilities
- Code style consistency

## Process

1. Read the files to review
2. Analyze each file systematically
3. Provide specific, actionable feedback

Frontmatter fields:

Field	Required	Description
name	Yes	Unique skill identifier
description	Yes	Shown in the tool description so the LLM knows when to use the skill
user-invocable	No	Whether users can trigger this skill directly (default: true)

The markdown body is the instruction content that gets injected into the conversation when the skill is loaded.

How Skills Work

When a session starts in a workspace:

1. Jean2 scans .agents/skills/ for subdirectories containing SKILL.md files
2. Available skills are listed in the skill tool's description — the LLM sees them as options
3. When the LLM recognizes a task matches a skill, it calls skill({ name: "code-review" })
4. The server returns the skill content wrapped in a <skill_content name="..."> block
5. The content is injected into the conversation, giving the agent specialized instructions

Bundled Resources

Skills can include additional files in their folder (scripts, templates, references). When a skill is loaded, the server includes its base directory as a file URL — so relative paths in the skill content can reference these resources:

.agents/skills/
└── code-review/
    ├── SKILL.md
    ├── checklist.md
    └── templates/
        └── feedback.md

The skill content can reference these files, and the LLM can use read-file to access them via the base directory path.

Preconfig Filtering

Preconfigs can control which skills are available through the skills field in the preconfig definition:

Value	Behavior
Omitted or null	All skills available (default)
[]	No skills available
["code-review", "testing"]	Only these named skills available

This lets you create specialized agents that only have access to relevant skills — for example, a deployment agent that can only load infrastructure-related skills.

Workspace Scope

Skills are per-workspace. Each workspace has its own .agents/skills/ directory. An agent working in one workspace cannot see or use skills from another workspace.