agentskills-fs

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("incident-response", provider)

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

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

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