用途
该技能面向 put.io 终端用户应用与共享前端包的开发与评审，涵盖 UI、状态管理、测试、文档、测试框架、交付流程以及前端开发机器环境准备。
使用原则：在目标仓库自身的指导说明与既有代码惯例之后，再套用 put.io 共享的前端工程默认规范。目标仓库的指导、项目本地技能以及代码先例优先于本技能。
主要能力
技能以参考映射（reference map）的方式组织，按任务选择所需参考：
- 特征代码、解析、状态、错误、表单、样式与测试：前端默认规范
- README、CONTRIBUTING、安全报告以及面向智能体的文档：顶层文档
- 包与应用的 CI、verify、发布、部署与发布形态：交付模型
- TypeScript 包与应用搭建：TypeScript 默认规范
- 机器工具、同级克隆、智能体工作树、就绪检查：环境搭建
- 本地开发密钥与 CI 凭据边界：密钥
- 涉及密钥的发布、签名、发布与部署：发布安全
- 浏览器、原生、TV、模拟器、仿真器与设备验证：测试框架
- 共享测试账号浏览器授权：测试框架模式
- 基于 CLI 的框架发现、认证、读取与写入：CLI 框架契约
Markdown 链接用于在技能包内导航。参考中出现的其他路径（如 .github/pull_request_template.md）用于指明在目标仓库中创建或检查的文件。
使用方式
- 用
git ls-files '*AGENTS.md' '*SKILL.md'清点嵌套指导文档，并阅读待变更区域的 README.md 与 docs。 - 识别仓库类型、技术栈、验证入口、交付目标以及运行时验证面。
- 只选择任务所需的参考。
仓库信息：repos.json 列出 put.io 仓库；owns 中标注 frontend 的条目属于前端。字段包括：name（本地文件夹）、repo（GitHub 远程）、path（规范检出路径）、owns（负责团队）、visibility（文档边界）、topics（GitHub 主题集，可选）、mode（团队工作区工具是否管理该检出）。owns 含多个团队的条目为共享条目。同级仓库位于同一文件夹下，默认 ~/projects/putdotio/。缺少路径时用 gh repo clone <repo> <path>，或环境搭建中的克隆循环。跨仓库引用前先检查可见性；私有内容不得进入公开仓库。跨所有前端仓库的任务：迭代 owns 含 frontend 的条目，跳过 sdks 组（除非任务覆盖 SDK），进入每个根目录，读取其 AGENTS.md，运行其自身的验证。
知识库位于 put.io 的 Notion 工作区 Frontend hub，通过 Notion MCP 读取，包含 Products、Specs、Design、Services、Delivery、Decisions、Analytics 与 Guides。在产品、规格、发布或密钥决策前先阅读。仅编辑 Frontend 页面；除非任务要求，不修改其他团队页面。
共享默认规范要点
- 在边界处解析外部输入，并从已验证的契约推导类型。
- 用显式状态与穷尽转换建模易出错流程。
- 预期错误保持类型化且可操作；约束意外失败而不清空无关 UI。
- 将副作用限制在适配器与叶子节点，保持渲染树纯净。
- 避免削弱契约的类型逃逸手段。
- 仅在 put.io 官方网站接受用户名、密码与当前一次性验证码；长期 TOTP 种子保留在生成当前验证码的授权密钥提供方内。CLI、移动端、TV、扩展、测试框架等客户端必须通过 OAuth 或设备链接流程将账号授权委托给网站，仅处理生成的验证码或令牌。
- 将构建、验证、部署与冒烟逻辑放在仓库自有命令中，由 CI 调用，工作流 YAML 保持薄。保留既有任务图；新建通道时使用单一验证入口。
- 仅从可信 main 或已验证的发布 ref 交付，且须先通过验证。合并或推送到 main 即为交付（包括 CI 由此启动的部署与发布）。手动部署或发布、密钥或提供方变更、在仓库 forge 之外写入、强制推送前需先询问。
- PR 正文尽量简短：结果、真实风险与未验证项。每个正文携带视觉辅助而非散文：UI 用评审过的截图或短视频，流程用 Mermaid 图，数字用表格，API 用简短代码示例。测试数量、命令日志与评审历史不写入。
- 将非显而易见的代码惯例记录到最近的 AGENTS.md；用户、贡献者、分发与安全文档保留在其规范位置。
验证要求
按所有者记录的检查选择受影响行为及其依赖项的验证。当所有者策略要求、共享输入变更或聚焦覆盖不确定时，运行完整规范门禁。在边界重要处，保持独立的已安装包、下游消费者、浏览器与设备验证。存在真实浏览器、应用、模拟器、仿真器或设备面时，在其中演练用户可见行为。
在称 UI 工作完成前，需演练首屏加载、加载中、错误与空状态，小屏幕，以及选择、聚焦、水合与竞态等交互状态。自行检查结果而非询问用户哪里看起来不对。
在源、输入与环境仍有效时可复用通过的验证；仅换轮次或交接不要求重跑。点名不可用的验证及其确切阻塞原因。命令发现不授权实时操作。验证命令启动运行时前，安装清理逻辑并记录是否启动了该确切目标。每次退出时，只停止它启动的目标并确认其已消失；保留既有目标。
边界
- SDK 仓库属于专门的 SDK 开发工作流，包括其文档、验证、发布与交付形态。
- 作为文件、下载、传输、认证或存储消费者操作 putio CLI 属于 CLI 的消费者指导。前端框架通过 CLI 框架契约使用已安装的 CLI。
- 仓库策略、通用 GitHub Actions 加固、构建工具迁移、可启动性修复与独立代码评审不在本技能范围内；本技能为执行这些工作的工作流提供 put.io 前端领域指导。
- 将机器特定事实、凭据、账号细节与私有支持上下文排除在本公开技能之外；仓库注册表只携带名称、远程、规范路径、所有者、可见性、主题与模式。