Streamlit 内置 Agent Skills 的编写与维护读懂lib/streamlit/.agents/skills/AGENTS.md文档工程规范【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlitStreamlit 将一份面向 AI 编码助手的 Agent Skills代理技能随库发布供 Claude、Cursor、Codex 等 Agent 在开发 Streamlit 应用时按需加载与路由。lib/streamlit/.agents/skills/AGENTS.md正是这份技能库的维护者编写规范它规定了新增指引放哪里、弃用 API 如何清理、公开stAPI 概览如何保持精炼、路由与链接如何保持同步等一整套文档工程纪律。读完本文你将掌握这套技能库的目录架构、九条核心维护约定、以及它们如何在SKILL.md路由文件、references/主题文档、streamlit skillsCLI 安装链路与测试中被落地执行。一、背景什么是 Streamlit 内置的 Agent Skills位于lib/streamlit/.agents/skills/下的技能随 Streamlit 库一起发布用户安装 Streamlit 后即可从本地加载使用因此文档要求在功能演进时保持技能内容与代码同步更新。当前仓库中唯一的内容技能为developing-with-streamlit其整体结构如下lib/streamlit/.agents/ ├── meta-skill/ │ └── developing-with-streamlit/ │ ├── SKILL.md # 全局安装的路由外壳技能 │ └── scripts/ │ └── discover.py # 运行时定位版本匹配的内容技能 └── skills/ └── developing-with-streamlit/ ├── SKILL.md # 路由技能按任务类型分发到 references/ ├── references/ # 28 个主题文档dashboards、theme、session-state…… └── assets/ ├── templates/apps/ # 6 个可复制的仪表盘应用模板 └── templates/themes/configs/ # 12 个主题配置dracula、nord……该技能的设计遵循路由 主题文件的两层模型见 lib/streamlit/.agents/skills/developing-with-streamlit/SKILL.mdSKILL.md是路由技能routing skill本身不承载具体知识只负责根据用户需求创建应用性能优化自定义组件……判断应该加载哪份references/文档references/下的主题文档api-reference.md、theme.md、markdown.md 等才是真正的知识载体。AGENTS.md正是这份技能库的维护约定。以下九条规则是它的核心骨架每一条都可以在仓库源码与配套测试中找到落地证据。二、九条核心维护约定逐条解析2.1 争取显眼位置Earn prominent placement约定要求只有常见、易用错、或很可能不在 Agent 训练数据里的特性才值得在既有 reference 中新增专门小节。对于小众或进阶特性例如不太相关的新参数默认应让 Agent 通过 API-reference 查询自行发现只有在能自然融入既有小节时才顺带提一句除非开发者明确指示否则不要新建 reference 页面和对应的SKILL.md路由条目。这一条的实际效果可以从参考文档的分工看出例如st.echarts_chart没有独立参考页而是被并入>streamlit skills # Interactive project install交互式项目安装 streamlit skills --global # Interactive global install交互式全局安装 streamlit skills --yes # Non-interactive project install非交互项目安装 streamlit skills -g -y # Non-interactive global install非交互全局安装项目模式默认通过符号链接把技能装到project/.agents/skills/若检测到 Claude Code 则同时装到.claude/skills/保证技能始终与激活的 Streamlit 环境保持同步全局模式则把版本无关的 meta-skill 复制到~/.agents/skills/及~/.claude/skills/。从_find_project_root()的实现可以看到项目根目录的解析顺序优先向上查找含.agents/.claude的目录其次找最近的.git最后才回退到当前工作目录且绝不回退到 home。4.3 meta-skill discover.py单份全局安装跨版本正确全局安装的是版本无关的路由外壳meta-skilllib/streamlit/.agents/meta-skill/developing-with-streamlit/SKILL.md scripts/discover.py。skills.py的注释说明了设计动机它随 wheel 从本地磁盘复制无网络依赖规避受控网络下的安装失败与运行时外部下载的安全审查随后由discover.py在运行时定位项目实际安装的 Streamlit 包python SKILL_DIR/scripts/discover.py --project-dir USER_PROJECT_DIR脚本按优先级探测解释器VIRTUAL_ENV→ 项目.venv→ 父目录.venv→ git 根.venv→ conda → pipenv/poetry/pdm/uv → 系统 Python导入streamlit并输出streamlit.__path__[0]/.agents/skills/developing-with-streamlit/SKILL.md的绝对路径退出码 0若 Streamlit 未安装1、版本早于 1.572、找不到解释器3或技能目录结构异常4则在 stderr 输出ERROR:块并给出针对检测到的那套包管理器pip/conda/pipenv/poetry/pdm/uv的精确安装建议然后让 Agent 按提示重跑。这样一份全局安装即可在多个 Streamlit 版本间保持正确。4.4 应用内引导nudge与检测skills.py还实现了完整的检测与安装技能应用内提示nudge体系detect_installed_skills()在 home / app / repo / project 四个层级、八种 Agent harnessagents、claude、codex、copilot、cortex、cursor、gemini、opencode的既定 skills 目录下查找SKILL.md标记nudge_suppression_reason()则按优先级决定是否展示引导headless 部署、用户已关闭欢迎消息、已点过不再询问、无 Agent harness、技能已安装、安装必然冲突等均会抑制。安装结果的失败原因被收拢为一个封闭的_InstallFailureReason字面量集合conflict、write_denied、write_locked、write_no_space、symlinks_no_privilege 等保证错误标签可作为遥测维度安全上报。五、维护约定的自动化保障测试如何守护文档工程lib/tests/streamlit/web/skills_test.py 为上述机制提供了系统级验证其中与技能维护直接相关的测试包括nudge 显示门控按优先级逐条验证headless、欢迎消息隐藏、dismiss 标记、无 Agent、已安装、部分安装、另一 harness 的标记、安装必冲突等情形每个抑制/失败原因词汇都至少被一个测试命名test_every_reason_in_the_vocabulary_is_named_by_a_test用参数化测试强制封闭集合不被静默扩充dismissed 标记文件的写入与路径归属测试。这些测试从工程上保证了AGENTS.md约定的可执行性维护者新增抑制原因时必须同步新增测试命名否则测试失败同理路由表新增 reference 时必须同步更新SKILL.md路由条目否则 Agent 将永远无法路由到新文档。六、给维护者的实践清单综合AGENTS.md的九条约定与仓库落地新增或编辑技能指引时应遵循先判断位置常见/易用错/可能不在训练数据中的特性才进既有 reference 的小节新建 reference 页必须经开发者明确指示并同步补路由条目。写前查 API用streamlit docs st.command核对本地 docstring 与签名用 api-reference.md 发现公开命令。遵守弃用红线绝不推广弃用 APIStreamlit 移除某 API 时从SKILL.md、references、示例、模板全量删除。保持简洁公开 API 概览只做高层摘要每条指引用最少的词传达行为并预防常见错误不添加版本戳兼容性只记例外。同步与验证增删 reference 时同步更新路由表并验证所有references/*.md链接可解析避免跨分支引用。跟随变化主题选项变化更新 theme.mdMarkdown 特性新增更新 markdown.md 的 Quick reference新公开注解类型更新 api-reference.md。可安装可测试确认新内容在MANIFEST.in白名单内、可被streamlit skills安装并被detect_installed_skills识别必要时补充skills_test.py覆盖。遵循以上纪律就能让随库发布的技能始终与代码演进保持同步让任何 Agent 在任意安装版本上都能拿到准确、精炼、可执行的 Streamlit 开发指引。【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考