agentskills-fs

---

title: agentskills-fs description: Local filesystem provider for Agent Skills.

Local filesystem skill provider for the Agent Skills SDK.

Serves Agent Skills from a local directory tree. Each subdirectory containing a SKILL.md file is a skill.

Installation

pip install agentskills-fs

Requires Python 3.12 or newer. Installs agentskills-core and pyyaml as dependencies.

Expected Directory Layout

skills/
├── incident-response/
│   ├── SKILL.md              # YAML frontmatter + markdown body
│   ├── references/           # supplementary docs (optional)
│   ├── scripts/              # executable scripts (optional)
│   └── assets/               # diagrams, data files (optional)
└── another-skill/
    └── SKILL.md

Usage

from pathlib import Path
from agentskills_core import SkillRegistry
from agentskills_fs import LocalFileSystemSkillProvider

provider = LocalFileSystemSkillProvider(Path("./skills"))
registry = SkillRegistry()
await registry.register_all(provider)  # every subdirectory holding a SKILL.md

skill = registry.get_skill("incident-response")
meta = await skill.get_metadata()
body = await skill.get_body()
script = await skill.get_script("page-oncall.sh")

Use registry.register("incident-response", provider) instead to take one named skill and ignore the rest of the folder.

Blocking file I/O runs in a worker thread, so a slow or networked filesystem does not stall other coroutines.

SKILL.md content is cached per provider instance after the first read — a single skill is otherwise re-read up to five times in one agent session. Call invalidate() when skills change on disk.

provider.invalidate("incident-response")  # forget one skill
provider.invalidate()                      # forget everything

Lossless File Access

The file-access capability preserves original bytes and lists the complete skill tree, including hidden files and arbitrary nested directories:

paths = await provider.list_files("incident-response")
original = await provider.read_file("incident-response", "SKILL.md")
data = await provider.read_file("incident-response", "data/nested.bin")

Listing does not read file contents. Reads bypass the parsed SKILL.md cache and enforce max_file_bytes. Negative limits are rejected. Zero permits empty files only. Links, junctions, special files, absolute paths, and traversal are rejected instead of silently producing an incomplete listing.

Publish only directories intended for sharing. Hidden files are not automatically excluded, so remove credentials and private files before exposing a skill. The provider does not freeze the tree or prevent concurrent filesystem changes. Use a trusted, immutable publication directory when constructing verified manifests.

Security

• Path-traversal protection - Skill IDs and resource names are validated to stay within the root directory. Attempts to escape (e.g. ../../etc/passwd) raise SkillNotFoundError or ResourceNotFoundError.
• File size limits - Files exceeding 10 MB (default) are rejected before reading into memory. Configure via the max_file_bytes parameter.
• Error-message sanitization - Error messages reference the skill_id rather than full filesystem paths, preventing internal path leakage.

For the full security policy, see SECURITY.md.

API

LocalFileSystemSkillProvider(root, *, max_file_bytes=10_485_760)

Resource Discovery

This provider sets supports_resource_listing = True and can enumerate a skill's bundled files:

listing = await provider.list_resources("incident-response")
# {"references": ["severity-levels.md"], "scripts": ["page-oncall.sh"], "assets": []}

All three keys are always present; unused categories are empty lists. Only regular files directly inside references/, scripts/ and assets/ are reported. Dotfiles, subdirectories, and symlinks resolving outside the skill root are skipped rather than raising, so one stray entry cannot make a whole skill unlistable — and listing can never offer a name that a subsequent read would reject.

License

MIT