nb_langchain_agentskills
LangChain 的 Agent Skills(SKILL.md)工具包:扫描 skill 目录,把 skill 清单注入系统提示,并提供 4 个工具让 agent 按需加载正文、读取文件、执行脚本。
特点:
- 递归发现与热刷新:单个目录下任意深度嵌套的 SKILL.md 都能被扫描到,坏文件只收集为警告、不中断扫描;技能清单按 TTL 自动重扫(默认 60 秒),长驻进程新增或删除技能无需重启,正文与文件始终实时读盘。
- 多目录合并:可同时挂载多个 skills 目录,同名技能后者覆盖(last wins),天然支持"全局技能 + 项目技能"叠加。
- 运行时黑白名单:黑名单与白名单都对"列出、加载、读文件、解析目录"四条链路生效,不存在"列表看不见但仍能加载";名单集合按引用持有,原地增删立即生效,无需重建 agent。
- 渐进式披露:系统提示只注入技能名与一句话描述,正文、文件、脚本在 agent 调用工具时才按需加载,不占用额外上下文。
- 跨平台脚本执行:内置命令执行器(shell 由
resolve_shell()统一解析:Windows 上有可用的 PowerShell 7 就用 7,否则 5.1;POSIX 用$SHELL/bash;可用NB_AGENTSKILLS_SHELL钉死),自动把技能根目录与scripts/注入PYTHONPATH,超时终止进程树(默认 180 秒),并拦截../路径穿越。
组成
一条数据流串起全部组件,每层都可单独替换:
DirectorySkillLoader(技能来源,可多个)
│ CompositeSkillLoader 合并(last wins)
▼
Allowed / BlacklistSkillLoader(可见性过滤,可叠加或省略)
│
▼
SkillsMiddleware ── 注入系统提示(仅 name + description)
│ 注册 4 个工具
▼
skill__list_skills / skill__load_skill / skill__read_content / skill__execute_script
(执行走 CommandExecutor)
| 组件 | 职责 |
|---|---|
DirectorySkillLoader |
从本地目录递归发现并读取技能 |
CompositeSkillLoader |
合并多个来源,同名后者覆盖 |
AllowedSkillLoader / BlacklistSkillLoader |
白名单 / 黑名单过滤,四链路全拦截 |
SkillsMiddleware |
注入技能清单提示、注册工具,可自定义 prompt |
CommandExecutor |
跨平台 shell 执行,超时管控与 PYTHONPATH 注入 |
所有 Loader 实现同一接口(list_skills / load_skill / read_content / resolve_root),可自行实现后接入。工具的入参与中间件参数见下文 工具 与 配置。
安装
要求 Python 3.10 及以上版本。
pip install nb-langchain-agentskills
快速开始
from langchain.agents import create_agent
from nb_langchain_agentskills import DirectorySkillLoader, SkillsMiddleware
loader = DirectorySkillLoader("./my-skills")
agent = create_agent(
model="openai:gpt-4o",
middleware=[SkillsMiddleware(loader=loader)],
)
result = agent.invoke({"messages": [("user", "帮我处理一个 PDF 文件")]})
for message in result["messages"]:
message.pretty_print()
SKILL.md 格式
每个 skill 是一个包含 SKILL.md 的目录:
my-skills/
└── pdf/
├── SKILL.md # 必须:YAML frontmatter + markdown 正文
├── references/ # 可选:参考文档
│ └── forms.md
└── scripts/ # 可选:脚本
└── fill.py
SKILL.md:
---
name: pdf
description: Handle PDF files. Use when the user asks to read, fill, or merge PDF documents.
license: MIT
---
# PDF Skill
Read `references/forms.md` for form field conventions.
Run `scripts/fill.py` to fill forms.
name 必填:小写字母数字与单个内部连字符,不超过 64 字符(agentskills.io 规范)。description 必填且不超过 1024 字符,写清楚何时适用——agent 靠它判断要不要用这个 skill。其余字段(license / compatibility / metadata / allowed-tools 及任意自定义字段)解析后透传;其中 compatibility 按规范为字符串,allowed-tools 按规范接受空格分隔的工具名字符串并解析为列表;source 是保留字,会被忽略。
工具
SkillsMiddleware 注册以下 4 个工具,可用 exclude_tools 去掉任何一个:
| 工具 | 入参 | 说明 |
|---|---|---|
skill__list_skills |
无 | 列出所有可用 skill |
skill__load_skill |
skill_name |
返回 <skill_directory>(根目录)/<skill_files>(文件清单,含 SKILL.md)/<skill_instructions>(正文)三段式 XML |
skill__read_content |
skill_name, file_path |
读 skill 下任意文件;file_path 支持相对(相对 skill 根)或绝对路径 |
skill__execute_script |
skill_name, command, max_run_ms=180000, working_directory=None |
在 skill 目录内执行 shell 命令,返回 exit_code / duration_ms / stdout / stderr |
skill__execute_script:
command是完整 shell 命令字符串,原样交给解析到的 shell 执行(具体是哪个 shell 见返回值里的shell字段:Windows 优先 PowerShell 7,其次 5.1;POSIX 用$SHELL/bash)working_directory为空时为 skill 根;相对路径相对 skill 根解析;不允许逃出 skill 根- 执行前把 skill 根目录和
scripts/前插到PYTHONPATH(只影响 python 命令;enable_pythonpath=False可关闭) - 超时终止运行;超长输出截断并注明
安全提示:
skill__execute_script会原样执行任意 shell 命令,本包不做命令过滤与沙箱。请仅在具备审批、沙箱或权限控制的可信环境中使用。
配置
SkillsMiddleware
| 参数 | 默认 | 说明 |
|---|---|---|
loader |
必填 | 任意 SkillLoader 实例 |
exclude_tools |
None |
不注册的工具名集合,如 {"skill__list_skills"} |
prompt_builder |
None |
(skills: list[SkillMetadata]) -> str,接管系统提示注入的格式;默认模板对 name / description 做 HTML 转义 |
executor |
None |
自定义 CommandExecutor |
enable_pythonpath |
True |
执行命令时是否注入 PYTHONPATH |
SkillLoader
from nb_langchain_agentskills import (
AllowedSkillLoader, CompositeSkillLoader, DirectorySkillLoader,
)
global_loader = DirectorySkillLoader("~/.agents/skills")
project_loader = DirectorySkillLoader("./.agents/skills", exclude_dirs=["archive-*"])
composite = CompositeSkillLoader([global_loader, project_loader])
visible = AllowedSkillLoader(composite, allowed={"pdf", "xlsx"})
middleware = SkillsMiddleware(
loader=visible,
exclude_tools={"skill__list_skills"},
prompt_builder=lambda skills: my_custom_prompt(skills),
)
DirectorySkillLoader(root, exclude_dirs=None, ttl_seconds=60):递归扫描本地目录;点开头目录默认跳过,exclude_dirs支持 fnmatch 通配CompositeSkillLoader(loaders, ttl_seconds=60):合并多个来源;同名 skill 后一个来源覆盖前一个,来源顺序从通用到具体排列(如[全局, 项目]);覆盖时记录 debug 日志AllowedSkillLoader(inner, allowed=None):只暴露白名单内的 skill;allowed集合按引用持有,原地增删即刻生效;allowed=None表示全部BlacklistSkillLoader(inner, blocked=None):只隐藏黑名单内的 skill,其余照常可见;blocked集合按引用持有,原地增删即刻生效;blocked=None等价空集
热重载
- skill 清单(name / description / 根路径)缓存,默认每 60 秒最多重扫一次:超期后的下一次调用自动重扫;
ttl_seconds=0关闭自动刷新,只用手动loader.reload() - 正文与文件内容不缓存,
load_skill与read_content每次实时读盘,修改立即生效 loader.last_warnings保存最近一次扫描的警告
License
MIT
Metadata
Release files for nb-langchain-agentskills 0.9.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nb_langchain_agentskills-0.9.2.tar.gz | 36.2 kB | Without provenance | Details for nb_langchain_agentskills-0.9.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nb_langchain_agentskills-0.9.2-py3-none-any.whl | Python 3 | none | any | Details for nb_langchain_agentskills-0.9.2-py3-none-any.whl |
Total release size: 68.6 kB
Release files / nb_langchain_agentskills-0.9.2.tar.gz
| Download URL | nb_langchain_agentskills-0.9.2.tar.gz |
|---|---|
| Size | 36.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0b7574cae04957b0d11bdf87d0d95aa76a0f0262830d601f26783a8ab4dde6e5
|
|
BLAKE2b-256 checksum How to use checksums |
0baa3b663be7d7750c16fcd39442da8f4a5311d81dbc41dac7345a41d51ef5bf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Release files / nb_langchain_agentskills-0.9.2-py3-none-any.whl
| Download URL | nb_langchain_agentskills-0.9.2-py3-none-any.whl |
|---|---|
| Size | 32.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8767f443eb2db59c0e3e9d6e6497c78276f4f56f3f045b1c6bf5fa3123d19f2b
|
|
BLAKE2b-256 checksum How to use checksums |
160525ff192a55c75023621063cdbf683cb3172a5510a6365725ef2317cb112c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Security for nb-langchain-agentskills 0.9.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.