Agent Skills in Facio: Packaging Domain Expertise Into Reusable Agent Modules

In October 2025, Anthropic introduced Agent Skills — an open standard for packaging domain-specific instructions, scripts, and resources into composable modules that AI agents can discover and load dynamically. By December, it was published as a cross-platform standard, adopted by Claude Code, and increasingly by the broader agent ecosystem.

The insight behind Skills is simple and powerful: a general-purpose agent needs different knowledge to review a PDF contract, deploy a Kubernetes cluster, or research DACH-region tax regulations. You cannot fit all of that into a single system prompt. Instead, you give the agent a filesystem, let it read the right skill at the right time, and load only what it needs — a design pattern Anthropic calls progressive disclosure.

Facio implements the Agent Skills standard natively. Every Facio workspace ships with a skills/ directory, a built-in skill-creator tool, and runtime support for the SKILL.md format. Here is how it works, and how to build your first skill.

---

What a Skill Looks Like

At its simplest, a skill is a directory containing a SKILL.md file. The file starts with YAML frontmatter:

---
name: my-skill
description: A short description of what this skill does
---

At agent startup, Facio pre-loads the name and description of every installed skill into the system prompt. This is the first level of progressive disclosure: the agent knows that the skill exists and when it might be relevant — but it has not yet loaded the full instructions.

When the agent determines that a skill matches the current task, it reads the full SKILL.md into context. This is the second level: detailed instructions, workflows, constraints, and references.

For complex skills, additional files — scripts, reference documents, templates, assets — live alongside SKILL.md inside the skill directory. The agent discovers them only when needed, reading through a third, fourth, or nth level of detail. The total amount of context a skill can bundle is effectively unbounded — limited only by the filesystem, not the context window.

---

Facio's Skill System: Beyond the Standard

Facio extends the open standard with three capabilities designed for production agent workflows:

1. Workspace-Managed Skills

Every Facio workspace has a dedicated skills/ directory. Installed skills are first-class workspace citizens — version-controlled, portable across deployments, and inspectable. Facio's runtime discovers them automatically at startup. No configuration files. No manual registration.

The workspace structure follows a clean convention:

workspace/
├── skills/
│   ├── blog-automation/
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── sources.md
│   │       └── categories.md
│   ├── html-slides/
│   │   ├── SKILL.md
│   │   ├── templates/
│   │   │   ├── base.html
│   │   │   ├── content-slide.html
│   │   │   └── ...
│   │   └── scripts/
│   │       ├── build-deck.py
│   │       └── render_slides.py
│   └── cron/
│       └── SKILL.md

Each skill is self-contained. Move it to another Facio workspace, and it works. Share it with a team, and it works. The skill is the unit of reuse.

2. One-Command Skill Creation

Facio ships with a built-in skill-creator tool. To create a new skill, the agent runs a single command — init_skill.py — which scaffolds the full directory structure, the YAML frontmatter, and the required metadata. An optional package_skill.py script bundles the skill for distribution.

This means you do not need to know the directory layout or the frontmatter format. You describe what the agent should be able to do, and Facio's skill-creator generates the scaffold. You fill in the instructions. The skill is ready.

3. Skills + MCP: Two Layers of Extensibility

Facio supports two complementary extension mechanisms:

• Skills are pure filesystem modules. Instructions, scripts, templates. No runtime dependencies beyond what the agent already has. Skills are for knowledge: domain expertise, procedural workflows, formatting rules, reference data.

• MCP (Model Context Protocol) servers are live runtime connections. They provide tools — API calls, database queries, browser automation — that the agent invokes as function calls. MCP is for actions.

The two layers compose. A skill can instruct the agent to use a specific MCP tool for a specific workflow. For example, the blog-automation skill bundles SEO research workflows and quality rules; at runtime, the agent follows the skill's instructions to call the Payload CMS MCP tools for publishing. The skill provides the what and why; MCP provides the how.

This separation — knowledge in skills, actions in MCP — keeps each layer focused and testable.

---

Progressive Disclosure in Practice

Here is the sequence of operations when an agent uses a skill:

1. Startup: Facio scans the skills/ directory. For each skill, it reads the name and description from the YAML frontmatter and adds them to the system prompt. Context cost: a few dozen tokens per skill.

2. Task matching: The user says "Create a blog post." The agent sees blog-automation in its available skills list. The description matches. The agent reads SKILL.md into context. Context cost: a few hundred to a few thousand tokens.

3. Deep dive: The skill's SKILL.md references references/categories.md and references/sources.md. The agent is in the research phase — it reads sources.md. Context cost: the file's contents, loaded only when needed.

4. Execution: The agent follows the skill's workflow, calling MCP tools, writing files, and producing output — all guided by the skill's instructions without the skill itself consuming additional context.

At no point does the agent load the entire skill tree into memory. It loads exactly what it needs, when it needs it. This is what makes skills scalable: you can have 50 skills installed, each with thousands of lines of reference material, and the agent's context window only holds the active one.

---

Why This Matters for B2B Workflows

The modular skill architecture solves a concrete business problem: every client has different rules.

A tax advisor in Munich processes Gewerbesteuer declarations differently than a tax advisor in Hamburg handles Umsatzsteuer-Voranmeldungen. An external data protection officer following BayernLDA guidelines operates differently than one following LfDI Baden-Württemberg. A Notar in Düsseldorf has different document formatting requirements than a Notar in Leipzig.

Without skills, you build one agent per variation — or you build one agent with an impossibly long system prompt that collapses under its own complexity. With skills, you build one agent and give it a library of domain modules. The agent loads the right one for the current client.

For Facio's target market — Steuerberater, Wirtschaftsprüfer, and regulated professionals in the DACH region — this is not a nice-to-have. It is the architecture that makes a general-purpose agent deployable across a fragmented regulatory landscape.

---

Getting Started

Facio ships with several skills pre-installed: cron for scheduling, memory for long-term recall, weather, and more. You can inspect them in the workspace skills/ directory to see how they are structured.

To create your first custom skill:

1. The agent invokes the skill-creator tool with a name and description
2. Facio scaffolds the directory and SKILL.md
3. You (or the agent) fill in the instructions, add scripts or references as needed
4. Restart — the skill is active

No API keys. No external services. No deployment pipeline. A skill is a folder. The filesystem is the interface.

For teams operating in regulated environments, this matters: skills are auditable. Every instruction the agent follows comes from a file that can be reviewed, versioned, and signed off. There is no hidden prompt layer. There is no vendor lock-in. The agent's expertise lives in your workspace, under your control.

---

Facio implements the Agent Skills open standard with one-command creation and workspace management. Deploy in 5 minutes →