{
"canonical_name": "numman-ali/openskills",
"compilation_id": "pack_c60d04e3d46a438ca269eda89b9556a7",
"created_at": "2026-05-16T16:04:12.853559+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx openskills` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx openskills",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_c04e5813129c4490a6aefe28cd193588"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_79c50dca395adffa775243c99bb14208",
"canonical_name": "numman-ali/openskills",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/numman-ali/openskills",
"slug": "openskills",
"source_packet_id": "phit_c08be6bee544443bb59df5efa1f94753",
"source_validation_id": "dval_6945712b05d448cb8c09fcd8d85981c9"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 639,
"github_stars": 10153,
"one_liner_en": "Universal skills loader for AI coding agents - npm i -g openskills",
"one_liner_zh": "Universal skills loader for AI coding agents - npm i -g openskills",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:coding, git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "openskills",
"title_zh": "openskills 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_c08be6bee544443bb59df5efa1f94753",
"page_model": {
"artifacts": {
"artifact_slug": "openskills",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx openskills",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/numman-ali/openskills#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Universal skills loader for AI coding agents - npm i -g openskills"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] `--universal` installs to `.agent/` not `.agents/`",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_c384eba59a4f4177ace0a344b94400dc | https://github.com/numman-ali/openskills/issues/84 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[BUG] `--universal` installs to `.agent/` not `.agents/`",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] add cli option --skills=name1,name2 to only install selected skill from github repo non-interactivelly",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_3ec834575446429c96f39db392b81751 | https://github.com/numman-ali/openskills/issues/53 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[FEATURE] add cli option --skills=name1,name2 to only install selected skill from github repo non-interactivelly",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Read skill.json from source repos for install and sync",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_8752343cfb2d4231a5eb42f242806a31 | https://github.com/numman-ali/openskills/issues/81 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Feature]: Read skill.json from source repos for install and sync",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Update command doesn't update all paths",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_8f8a414bbe634c229bf200f45014fc57 | https://github.com/numman-ali/openskills/issues/75 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[BUG] Update command doesn't update all paths",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Clone failed",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_59fb2f76bd674cf2bba0efb5a57843bd | https://github.com/numman-ali/openskills/issues/85 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[BUG] Clone failed",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] EEXIST when overwriting an existing skill during installation",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_ac382f17e8a744b58f7d0860617a2f19 | https://github.com/numman-ali/openskills/issues/73 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[BUG] EEXIST when overwriting an existing skill during installation",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.0 - Universal Skills Support",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_31f11650e29a4e7c9fbd4ff026d577d0 | https://github.com/numman-ali/openskills/releases/tag/v1.2.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.2.0 - Universal Skills Support",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.1 - Documentation Fixes",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_bb36323b2acd470bb0382644fddfde5f | https://github.com/numman-ali/openskills/releases/tag/v1.2.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.2.1 - Documentation Fixes",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.5.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_7fab452932ab47e18a1d915b327b22d2 | https://github.com/numman-ali/openskills/releases/tag/v1.5.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.5.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1083829346 | https://github.com/numman-ali/openskills | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1083829346 | https://github.com/numman-ali/openskills | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1083829346 | https://github.com/numman-ali/openskills | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1083829346 | https://github.com/numman-ali/openskills | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Path Resolution & Sandbox Access Conflict for Global OpenSkills on macOS",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_92230b03d1ec434694ad8d2e5ee6441f | https://github.com/numman-ali/openskills/issues/87 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[BUG] Path Resolution & Sandbox Access Conflict for Global OpenSkills on macOS",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Explicit local-first precedence for synced skills",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_6a14016c475349378139fe37f465945b | https://github.com/numman-ali/openskills/issues/86 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[FEATURE] Explicit local-first precedence for synced skills",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Remote path that isn't a git repo",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_24fd46302500414a80566af028da3bb8 | https://github.com/numman-ali/openskills/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[FEATURE] Remote path that isn't a git repo",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：[BUG] `--universal` installs to `.agent/` not `.agents/`。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 3,
"forks": 639,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 10153
},
"source_url": "https://github.com/numman-ali/openskills",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Universal skills loader for AI coding agents - npm i -g openskills",
"title": "openskills 能力包",
"trial_prompt": "# openskills - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 openskills 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-cli-commands：CLI命令参考。围绕“CLI命令参考”模拟一次用户任务，不展示安装或运行结果。\n5. page-install-command：install命令详解。围绕“install命令详解”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-cli-commands\n输入：用户提供的“CLI命令参考”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-install-command\n输入：用户提供的“install命令详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-cli-commands：Step 4 必须围绕“CLI命令参考”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-install-command：Step 5 必须围绕“install命令详解”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/numman-ali/openskills\n- https://github.com/numman-ali/openskills#readme\n- examples/my-first-skill/SKILL.md\n- README.md\n- package.json\n- AGENTS.md\n- src/cli.ts\n- src/types.ts\n- src/utils/skills.ts\n- src/utils/agents-md.ts\n- src/commands/install.ts\n- src/commands/list.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 openskills 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: [BUG] `--universal` installs to `.agent/` not `.agents/`（https://github.com/numman-ali/openskills/issues/84）；github/github_issue: [FEATURE] Remote path that isn't a git repo（https://github.com/numman-ali/openskills/issues/89）；github/github_issue: [BUG] Path Resolution & Sandbox Access Conflict for Global OpenSkills on（https://github.com/numman-ali/openskills/issues/87）；github/github_issue: [FEATURE] Explicit local-first precedence for synced skills（https://github.com/numman-ali/openskills/issues/86）；github/github_issue: [BUG] Clone failed（https://github.com/numman-ali/openskills/issues/85）；github/github_issue: [Feature]: Read skill.json from source repos for install and sync（https://github.com/numman-ali/openskills/issues/81）；github/github_issue: [BUG] Update command doesn't update all paths（https://github.com/numman-ali/openskills/issues/75）；github/github_issue: [FEATURE] add cli option --skills=name1,name2 to only install selected s（https://github.com/numman-ali/openskills/issues/53）；github/github_issue: [BUG] EEXIST when overwriting an existing skill during installation（https://github.com/numman-ali/openskills/issues/73）；github/github_release: v1.5.0（https://github.com/numman-ali/openskills/releases/tag/v1.5.0）；github/github_release: v1.3.1（https://github.com/numman-ali/openskills/releases/tag/v1.3.1）；github/github_release: v1.3.0 - CI/CD, Local Development & Security（https://github.com/numman-ali/openskills/releases/tag/v1.3.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[BUG] `--universal` installs to `.agent/` not `.agents/`",
"url": "https://github.com/numman-ali/openskills/issues/84"
},
{
"kind": "github_issue",
"source": "github",
"title": "[FEATURE] Remote path that isn't a git repo",
"url": "https://github.com/numman-ali/openskills/issues/89"
},
{
"kind": "github_issue",
"source": "github",
"title": "[BUG] Path Resolution & Sandbox Access Conflict for Global OpenSkills on",
"url": "https://github.com/numman-ali/openskills/issues/87"
},
{
"kind": "github_issue",
"source": "github",
"title": "[FEATURE] Explicit local-first precedence for synced skills",
"url": "https://github.com/numman-ali/openskills/issues/86"
},
{
"kind": "github_issue",
"source": "github",
"title": "[BUG] Clone failed",
"url": "https://github.com/numman-ali/openskills/issues/85"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature]: Read skill.json from source repos for install and sync",
"url": "https://github.com/numman-ali/openskills/issues/81"
},
{
"kind": "github_issue",
"source": "github",
"title": "[BUG] Update command doesn't update all paths",
"url": "https://github.com/numman-ali/openskills/issues/75"
},
{
"kind": "github_issue",
"source": "github",
"title": "[FEATURE] add cli option --skills=name1,name2 to only install selected s",
"url": "https://github.com/numman-ali/openskills/issues/53"
},
{
"kind": "github_issue",
"source": "github",
"title": "[BUG] EEXIST when overwriting an existing skill during installation",
"url": "https://github.com/numman-ali/openskills/issues/73"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.5.0",
"url": "https://github.com/numman-ali/openskills/releases/tag/v1.5.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.3.1",
"url": "https://github.com/numman-ali/openskills/releases/tag/v1.3.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.3.0 - CI/CD, Local Development & Security",
"url": "https://github.com/numman-ali/openskills/releases/tag/v1.3.0"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Universal skills loader for AI coding agents - npm i -g openskills",
"effort": "安装已验证",
"forks": 639,
"icon": "code",
"name": "openskills 能力包",
"risk": "可发布",
"slug": "openskills",
"stars": 10153,
"tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/numman-ali/openskills 项目说明书\n\n生成时间：2026-05-16 16:02:37 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [快速开始](#page-quick-start)\n- [系统架构](#page-architecture)\n- [CLI命令参考](#page-cli-commands)\n- [install命令详解](#page-install-command)\n- [sync命令详解](#page-sync-command)\n- [update命令详解](#page-update-command)\n- [SKILL.md格式规范](#page-skill-md-format)\n- [数据存储与管理](#page-data-storage)\n- [贡献指南](#page-contributing)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[快速开始](#page-quick-start), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/numman-ali/openskills/blob/main/README.md)\n- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)\n- [examples/my-first-skill/SKILL.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/SKILL.md)\n- [examples/my-first-skill/references/skill-format.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/references/skill-format.md)\n- [CHANGELOG.md](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)\n- [CONTRIBUTING.md](https://github.com/numman-ali/openskills/blob/main/CONTRIBUTING.md)\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)\n \n\n# 项目概述\n\nOpenSkills 是一个开源的 Node.js CLI 工具，旨在为 AI 编码代理提供标准化的技能（Skills）管理和分发机制。该项目完全兼容 Anthropic 的 SKILL.md 格式规范，使技能可以在不同的 AI 代理平台之间无缝移植和使用。\n\n## 项目定位与核心价值\n\nOpenSkills 的核心定位是**通用技能加载器**。在 AI 代理的工作场景中，技能是静态的指令和资源的集合，与 MCP（Model Context Protocol）的动态工具调用形成互补。项目采用 SKILL.md 文件作为技能的唯一载体，无需运行服务器，使得技能具备天然的跨平台兼容性。\n\n**核心价值主张：**\n\n- **Exact Claude Code 兼容性** — 采用相同的提示格式、市场和文件夹结构 资料来源：[README.md]()\n- **通用性** — 支持 Claude Code、Cursor、Windsurf、Aider、Codex 等多种代理 资料来源：[README.md]()\n- **渐进式披露** — 按需加载技能，保持代理上下文的精简 资料来源：[README.md]()\n- **仓库友好** — 技能与项目代码一同版本化管理 资料来源：[README.md]()\n- **私有化友好** — 支持从本地路径或私有 Git 仓库安装技能 资料来源：[README.md]()\n\n## 技术架构\n\n### 技术栈\n\nOpenSkills 基于现代 Node.js 生态构建，对运行环境有明确要求：\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Node.js | >= 20.6.0 | 项目引擎要求 |\n| Git | 任意版本 | 用于克隆仓库 |\n| TypeScript | 5.9.3 | 开发语言 |\n| Vitest | 4.0.3 | 测试框架 |\n\n**核心依赖库：**\n\n| 库名 | 版本 | 用途 |\n|------|------|------|\n| commander | ^12.1.0 | CLI 命令框架 |\n| chalk | ^5.6.2 | 终端着色 |\n| ora | ^9.0.0 | 加载动画 |\n| @inquirer/prompts | ^7.9.0 | 交互式提示 |\n\n资料来源：[package.json]()\n\n### 项目结构\n\n```\nopenskills/\n├── src/\n│ ├── cli.ts # CLI 主入口，定义命令路由\n│ ├── commands/ # 各命令实现\n│ │ ├── update.ts # 技能更新逻辑\n│ │ ├── install.ts # 技能安装逻辑\n│ │ └── ...\n│ ├── utils/ # 共享工具\n│ │ ├── agents-md.ts # AGENTS.md 生成\n│ │ └── ...\n│ └── types.ts # TypeScript 接口定义\n├── tests/ # 测试套件（88+ 测试用例）\n├── examples/\n│ └── my-first-skill/ # 示例技能\n└── package.json\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[用户执行 CLI 命令] --> B{npx openskills}\n B --> C[install 安装技能]\n B --> D[sync 同步 AGENTS.md]\n B --> E[list 列出技能]\n B --> F[read 读取技能内容]\n B --> G[update 更新技能]\n B --> H[manage/remove 管理技能]\n \n C --> C1[解析安装源]\n C1 --> C2{GitHub 仓库?}\n C2 -->|是| C3[git clone 克隆仓库]\n C2 -->|否| C4{本地路径?}\n C4 -->|是| C5[使用本地目录]\n C4 -->|否| C6[私有 Git 仓库]\n C3 --> C7[复制到技能目录]\n C5 --> C7\n C6 --> C7\n C7 --> C8[写入元数据]\n \n F --> F1[定位 SKILL.md]\n F1 --> F2[输出技能内容]\n F2 --> F3[提供基础目录]\n```\n\n## CLI 命令体系\n\n### 命令总览\n\n| 命令 | 描述 | 主要选项 |\n|------|------|----------|\n| `install ` | 从 GitHub/Git URL 安装技能 | `--global`, `--universal`, `--yes` |\n| `sync` | 更新 AGENTS.md | `--yes`, `--output ` |\n| `list` | 列出已安装技能 | - |\n| `read ` | 读取技能内容到 stdout | - |\n| `update [skill-names]` | 更新已安装技能 | - |\n| `manage` | 交互式管理技能 | - |\n| `remove ` | 移除指定技能 | - |\n\n资料来源：[src/cli.ts]()\n\n### 安装来源类型\n\nOpenSkills 支持多种安装来源，覆盖了典型的使用场景：\n\n| 来源类型 | 示例 | 说明 |\n|----------|------|------|\n| Anthropic 市场 | `anthropics/skills` | 从 Anthropic 官方技能库安装 |\n| GitHub 仓库 | `your-org/your-skills` | 从任意 GitHub 仓库安装 |\n| 本地路径 | `./local-skills/my-skill` | 从本地目录安装 |\n| 私有仓库 | `git@github.com:org/private-skills.git` | 通过 SSH 安装私有仓库 |\n\n资料来源：[README.md]()\n\n### 安装位置优先级\n\n```mermaid\ngraph LR\n A[安装请求] --> B{--universal 标志?}\n B -->|是| C[.agent/skills/]\n B -->|否| D{--global 标志?}\n D -->|是| E[~/.claude/skills/]\n D -->|否| F[项目本地]\n F --> G{存在 .claude/skills?}\n G -->|是| H[./.claude/skills/]\n G -->|否| I[./.agent/skills/]\n \n C --> J[优先级 1: 最高]\n H --> K[优先级 2]\n E --> L[优先级 3]\n I --> M[优先级 4]\n```\n\n优先级顺序：**`.agent/skills/` > `~/.agent/skills/` > `./.claude/skills/` > `~/.claude/skills/`**\n\n资料来源：[README.md]()\n\n## SKILL.md 格式规范\n\nSKILL.md 是 OpenSkills 技能的核心文件，采用 YAML frontmatter + Markdown 的混合格式。\n\n### 文件结构\n\n```\nskill-name/\n├── SKILL.md # 必需：技能主文件\n├── references/ # 可选：参考文档（按需加载）\n├── scripts/ # 可选：可执行脚本\n└── assets/ # 可选：资源文件（不加载到上下文）\n```\n\n资料来源：[examples/my-first-skill/references/skill-format.md]()\n\n### YAML Frontmatter\n\n每个 SKILL.md 必须以 YAML frontmatter 开头：\n\n```yaml\n---\nname: skill-name # 必需：连字符格式标识符\ndescription: When to use # 必需：1-2 句话描述，第三人称\n---\n```\n\n### 内容写作规范\n\n**推荐风格：**\n\n- 使用祈使句/不定式：\"To accomplish X, execute Y\"\n- 被动表述：\"This skill is loaded when Z\"\n- 引用资源：\"See references/guide.md for details\"\n\n**应避免：**\n\n- 第二人称：\"You should do X\"\n- 条件式：\"If you need Y\"\n\n资料来源：[examples/my-first-skill/references/skill-format.md]()\n\n### 文件大小指南\n\n| 部分 | 限制 | 说明 |\n|------|------|------|\n| SKILL.md | < 5,000 词 | 核心指令，保持精简 |\n| references/ | 无限制 | 按需选择性加载 |\n| scripts/ | 可执行 | 不计入上下文大小 |\n| assets/ | 任意 | 不加载到上下文 |\n\n资料来源：[examples/my-first-skill/references/skill-format.md]()\n\n## 渐进式披露机制\n\nOpenSkills 实现了三级渐进式加载策略，优化 AI 代理的上下文使用效率：\n\n```mermaid\ngraph TD\n A[技能元数据] --> B[SKILL.md 核心指令]\n A --> C[references/ 详细文档]\n A --> D[scripts/ 可执行脚本]\n \n B --> E[始终加载]\n C --> F[按需加载]\n D --> G[执行时调用]\n \n style A fill:#e1f5fe\n style B fill:#fff3e0\n style C fill:#f3e5f5\n style D fill:#e8f5e9\n```\n\n| 级别 | 内容 | 加载时机 | 说明 |\n|------|------|----------|------|\n| 1 | 元数据 | 始终在上下文中 | name + description |\n| 2 | SKILL.md | 技能被调用时 | 核心指令流程 |\n| 3 | references/ | 需要时 | 详细 API 文档、指南 |\n\n资料来源：[examples/my-first-skill/references/skill-format.md]()\n资料来源：[README.md]()\n\n## AGENTS.md 集成\n\n### 生成机制\n\n`sync` 命令负责生成包含技能信息的 AGENTS.md 文件段：\n\n```mermaid\ngraph LR\n A[扫描技能目录] --> B[读取元数据]\n B --> C[解析 SKILL.md]\n C --> D[生成 XML 块]\n D --> E[替换 AGENTS.md 内容]\n```\n\n生成的 XML 块结构：\n\n```xml\n\n\n...\n\n\n\npdf\nPDF manipulation toolkit...\nproject\n\n\n\n```\n\n资料来源：[src/utils/agents-md.ts]()\n\n### 输出配置\n\n`sync` 命令支持自定义输出路径：\n\n| 选项 | 说明 |\n|------|------|\n| `-o, --output ` | 指定输出文件路径（默认：AGENTS.md） |\n| `-y, --yes` | 跳过交互式选择，同步所有技能 |\n\n资料来源：[README.md]()\n\n## 技能更新机制\n\nupdate 命令支持三种来源类型的技能更新：\n\n```mermaid\ngraph TD\n A[update 命令] --> B{技能来源类型}\n \n B --> C[本地类型 local]\n B --> D[Git 类型 git]\n B --> E[未知类型]\n \n C --> C1{本地路径存在?}\n C1 -->|否| C2[跳过 - 源缺失]\n C1 -->|是| C3{SKILL.md 存在?}\n C3 -->|否| C4[跳过 - 文件缺失]\n C3 -->|是| C5[从本地目录复制]\n \n D --> D1{元数据包含 repoUrl?}\n D1 -->|否| D2[跳过 - 缺少仓库 URL]\n D1 -->|是| D3[git clone 临时目录]\n D3 --> D4[复制到技能目录]\n \n E --> E1[输出警告]\n \n style C5 fill:#c8e6c9\n style D4 fill:#c8e6c9\n```\n\n**更新流程要点：**\n\n1. **本地技能**：直接使用 `localPath` 指向的目录作为更新源\n2. **Git 技能**：克隆到临时目录后复制内容\n3. **缺少元数据**：跳过更新并输出警告\n\n资料来源：[src/commands/update.ts]()\n\n## 版本演进\n\n### 版本历史\n\n| 版本 | 发布日期 | 关键特性 |\n|------|----------|----------|\n| 1.0.0 | 2025-10-26 | 初始版本，核心 CLI 功能 |\n| 1.1.0 | 2025-10-27 | README 完善，位置标签修复 |\n| 1.2.0 | 2025-10-27 | 增加 `--universal` 标志，项目本地安装成为默认 |\n| 1.2.1 | 2025-10-27 | 文档清理，移除重复部分 |\n| 1.3.0 | 2025-11-12 | 本地路径安装、私有仓库支持、88+ 测试用例 |\n| 1.3.1-1.3.2 | 2026-01 | 符号链接支持、可配置输出路径 |\n| 1.4.0 | 2026-01-17 | README 澄清、项目本地默认说明 |\n| 1.5.0 | 2026-01-17 | 完整功能集发布 |\n\n资料来源：[CHANGELOG.md]()\n\n### 里程碑特性\n\n**v1.3.0 新增特性：**\n\n- 本地技能开发工作流支持\n- 损坏的符号链接自动跳过\n- 可配置输出路径（`--output` 标志）\n- 从本地目录安装技能\n- 私有 Git 仓库支持（SSH/HTTPS）\n- 完整的测试套件\n\n**v1.2.0 重大变更：**\n\n- 项目安装成为默认行为（之前是全局安装）\n- 技能默认安装到 `./.claude/skills/`\n\n资料来源：[CHANGELOG.md]()\n\n## 测试体系\n\nOpenSkills 采用 Vitest 作为测试框架，构建了多层次的测试覆盖：\n\n| 测试类型 | 测试文件数 | 说明 |\n|----------|------------|------|\n| 单元测试 | 多个 | 符号链接检测、YAML 解析 |\n| 集成测试 | 多个 | install、sync 命令 |\n| E2E 测试 | 多个 | 完整 CLI 工作流 |\n\n资料来源：[CHANGELOG.md]()\n\n**测试命令：**\n\n```bash\nnpm run test # 运行所有测试\nnpm run test:watch # 监听模式\nnpm run test:coverage # 覆盖率报告\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 与 MCP 的对比\n\n| 方面 | Skills | MCP |\n|------|--------|-----|\n| 实现方式 | 静态文件 | 动态服务器 |\n| 通信协议 | 无需网络 | 需要 MCP 服务器 |\n| 上下文加载 | 按需渐进式 | 实时查询 |\n| 跨代理兼容性 | 高 | 依赖 MCP 支持 |\n| 适用场景 | 固定指令集 | 动态工具调用 |\n\n**设计理念差异：**\n\n- **MCP 面向动态工具** — 适合需要实时交互、数据获取的场景\n- **Skills 面向静态指令** — 适合流程指导、领域知识、模板生成\n\n资料来源：[README.md]()\n\n## 快速开始\n\n### 安装方式\n\n```bash\n# 通过 npx 运行（无需安装）\nnpx openskills install anthropics/skills\nnpx openskills sync\n\n# 全局安装\nnpm install -g openskills\n```\n\n### 本地开发\n\n```bash\n# 克隆项目\ngit clone git@github.com:your-org/openskills.git\ncd openskills\n\n# 链接本地 CLI\nnpm link\n\n# 测试安装\nnpx openskills install anthropics/skills/pdf-editor --project\nnpx openskills sync\nnpx openskills read pdf-editor\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 系统要求\n\n| 要求 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | 20.6.0+ | 项目引擎限制 |\n| Git | 任意版本 | 用于仓库克隆操作 |\n\n资料来源：[README.md]()\n\n## 开源许可\n\nOpenSkills 采用 **Apache 2.0** 开源许可证。项目实现了 Anthropic 的 Agent Skills 规范规范，并在 README 中标注了 Attribution。\n\n资料来源：[README.md]()\n资料来源：[CONTRIBUTING.md]()\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [CLI命令参考](#page-cli-commands)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/numman-ali/openskills/blob/main/README.md)\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [examples/my-first-skill/SKILL.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/SKILL.md)\n- [examples/my-first-skill/references/skill-format.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/references/skill-format.md)\n- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n- [src/commands/sync.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/sync.ts)\n- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)\n- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)\n \n\n# 快速开始\n\n本页面介绍如何快速上手 OpenSkills，包括环境准备、技能安装、AGENTS.md 同步以及基本使用流程。\n\n## 系统要求\n\n| 要求 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | 20.6.0+ | 核心运行环境 |\n| Git | 任意版本 | 用于克隆技能仓库 |\n\n> 资料来源：[package.json:23-24]()\n\n## 安装 OpenSkills\n\nOpenSkills 无需全局安装，可直接通过 `npx` 运行。\n\n### 方式一：直接使用 npx（推荐）\n\n```bash\nnpx openskills --version\n```\n\n### 方式二：全局安装（可选）\n\n```bash\nnpm install -g openskills\n```\n\n> 资料来源：[README.md:1-5]()\n\n## 安装技能包\n\n### 从 Anthropic 市场安装\n\n```bash\nnpx openskills install anthropics/skills\n```\n\n> 资料来源：[README.md:12-15]()\n\n### 从 GitHub 仓库安装\n\n```bash\nnpx openskills install your-org/your-skills\n```\n\n> 资料来源：[README.md:17-19]()\n\n### 从本地路径安装\n\n```bash\nnpx openskills install ./local-skills/my-skill\n```\n\n支持绝对路径、相对路径和波浪号展开路径。\n\n> 资料来源：[CHANGELOG.md:25-30]()\n\n### 从私有仓库安装\n\n```bash\nnpx openskills install git@github.com:your-org/private-skills.git\n```\n\nOpenSkills 自动使用系统 SSH 密钥进行身份验证。\n\n> 资料来源：[CHANGELOG.md:31-35]()\n\n## 安装选项说明\n\n| 选项 | 说明 | 默认值 |\n|------|------|--------|\n| `--global` | 全局安装到 `~/.claude/skills` | 禁用 |\n| `--universal` | 安装到 `.agent/skills/` | 禁用 |\n| `-y, --yes` | 跳过交互确认，用于 CI/CD | 禁用 |\n| `-o, --output ` | 指定输出路径（sync 命令） | AGENTS.md |\n\n> 资料来源：[README.md:48-55]()\n\n### 安装位置优先级\n\n当使用 `--universal` 选项时，安装目录优先级如下：\n\n1. `./.agent/skills/`\n2. `~/.agent/skills/`\n3. `./.claude/skills/`\n4. `~/.claude/skills/`\n\n> 资料来源：[README.md:27-34]()\n\n## 同步技能到 AGENTS.md\n\n安装技能后，需要运行同步命令将技能信息写入 `AGENTS.md` 文件。\n\n### 基本同步流程\n\n```bash\nnpx openskills sync\n```\n\n同步过程会：\n1. 扫描已安装的技能目录\n2. 读取每个技能的 `SKILL.md` 元数据\n3. 生成 `` XML 块\n4. 更新目标 `AGENTS.md` 文件\n\n> 资料来源：[src/commands/sync.ts:1-15]()\n\n### 生成的文件格式\n\n同步后的 `AGENTS.md` 包含以下结构：\n\n```xml\n\n\n\nskill-name\n技能描述\nproject\n\n\n\n```\n\n> 资料来源：[src/utils/agents-md.ts:45-60]()\n\n## 使用技能\n\n### 查看已安装的技能\n\n```bash\nnpx openskills list\n```\n\n> 资料来源：[README.md:57-60]()\n\n### 读取技能内容\n\n```bash\nnpx openskills read \n```\n\n例如读取 PDF 技能：\n\n```bash\nnpx openskills read pdf\n```\n\n> 资料来源：[README.md:1-7]()\n\n### 加载多个技能\n\n```bash\nnpx openskills read skill-one,skill-two\n```\n\n> 资料来源：[README.md:1-7]()\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[安装 OpenSkills] --> B[安装技能包]\n B --> C[运行 sync 同步]\n C --> D[AGENTS.md 已更新]\n D --> E[AI 代理读取 AGENTS.md]\n E --> F[根据任务调用 npx openskills read]\n F --> G[技能内容加载到上下文]\n G --> H[执行技能指令]\n```\n\n## 常用命令速查表\n\n| 命令 | 功能 |\n|------|------|\n| `npx openskills install ` | 从指定源安装技能 |\n| `npx openskills sync` | 同步技能到 AGENTS.md |\n| `npx openskills list` | 列出已安装的技能 |\n| `npx openskills read ` | 读取技能内容 |\n| `npx openskills update [name]` | 更新已安装的技能 |\n| `npx openskills remove ` | 移除指定技能 |\n| `npx openskills manage` | 交互式管理技能 |\n\n> 资料来源：[README.md:57-60]()\n\n## 本地技能开发\n\n### 创建最小技能结构\n\n```\nmy-skill/\n└── SKILL.md\n```\n\n### 带资源的技能结构\n\n```\nmy-skill/\n├── SKILL.md\n├── references/\n├── scripts/\n└── assets/\n```\n\n> 资料来源：[README.md:85-95]()\n\n### 使用符号链接进行开发\n\n```bash\ngit clone git@github.com:your-org/my-skills.git ~/dev/my-skills\nmkdir -p .claude/skills\nln -s ~/dev/my-skills/my-skill .claude/skills/my-skill\n```\n\n> 资料来源：[README.md:103-108]()\n\n## SKILL.md 格式简介\n\n每个技能必须包含 YAML 前置内容和 Markdown 正文：\n\n```yaml\n---\nname: skill-name\ndescription: 技能描述（1-2句话，第三人称）\n---\n\n# 技能标题\n\n技能使用说明...\n```\n\n> 资料来源：[examples/my-first-skill/SKILL.md:1-15]()\n\n## 下一步\n\n- 查看 [SKILL.md 格式参考](examples/my-first-skill/references/skill-format.md) 了解完整格式规范\n- 查看 [CHANGELOG.md](../../CHANGELOG.md) 了解版本更新历史\n- 查看 [CONTRIBUTING.md](../../CONTRIBUTING.md) 了解贡献指南\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[CLI命令参考](#page-cli-commands), [SKILL.md格式规范](#page-skill-md-format)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [src/types.ts](https://github.com/numman-ali/openskills/blob/main/src/types.ts)\n- [src/utils/skills.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skills.ts)\n- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)\n- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)\n \n\n# 系统架构\n\n## 概述\n\nOpenSkills 是一个通用的 AI 代理技能管理系统，旨在为各种 AI 编码代理提供标准化的技能加载机制。该项目采用 TypeScript 开发，基于 Node.js 20.6+ 运行时运行，通过命令行界面（CLI）提供技能安装、同步和管理功能。\n\n核心设计理念是实现与 Anthropic Claude Code 技能格式的完全兼容，同时支持跨平台、多代理环境使用。技能以 `SKILL.md` 文件为核心，配合可选的 `references/`、`scripts/` 和 `assets/` 目录形成完整的技能包结构。\n\n## 架构分层\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ CLI 交互层 (cli.ts) │\n│ commander 解析命令 + chalk/ora 美化输出 │\n├─────────────────────────────────────────────────────────────┤\n│ 命令实现层 (commands/) │\n│ install │ read │ sync │ list │ update │ manage │ remove │\n├─────────────────────────────────────────────────────────────┤\n│ 工具函数层 (utils/) │\n│ agents-md.ts │ skills.ts │ yaml.ts │ symlink.ts │\n├─────────────────────────────────────────────────────────────┤\n│ 类型定义层 (types.ts) │\n│ Skill │ SkillSourceMetadata │ ... │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 核心依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| commander | ^12.1.0 | CLI 命令解析 |\n| chalk | ^5.6.2 | 终端输出着色 |\n| ora | ^9.0.0 | 加载动画 |\n| @inquirer/prompts | ^7.9.0 | 交互式提示 |\n| typescript | ^5.9.3 | 类型检查 |\n| vitest | ^4.0.3 | 单元测试 |\n\n资料来源：[package.json:1-25]()\n\n## 命令模块设计\n\n### 命令注册机制\n\nCLI 采用 Commander.js 框架进行命令注册和参数解析。主入口文件 `src/cli.ts` 负责定义所有可用命令：\n\n```typescript\nprogram\n .command('list')\n .description('List all installed skills')\n .action(listSkills);\n\nprogram\n .command('install ')\n .description('Install skill from GitHub or Git URL')\n .option('-g, --global', 'Install globally (default: project install)')\n .option('-u, --universal', 'Install to .agent/skills/')\n .option('-y, --yes', 'Skip interactive selection')\n .action(installSkill);\n```\n\n资料来源：[src/cli.ts:1-50]()\n\n### 支持的命令列表\n\n| 命令 | 功能 | 选项 |\n|------|------|------|\n| `install ` | 从 GitHub/本地路径安装技能 | `--global`, `--universal`, `--yes` |\n| `sync` | 同步技能到 AGENTS.md | `--yes`, `--output ` |\n| `list` | 列出已安装的技能 | - |\n| `read ` | 读取技能内容输出到终端 | - |\n| `update [skill-names]` | 更新已安装的技能 | - |\n| `manage` | 交互式管理（删除）技能 | - |\n| `remove ` | 移除指定技能 | - |\n\n## 数据模型\n\n### 技能元数据结构\n\n```typescript\ninterface Skill {\n name: string; // 技能标识符（连字符格式）\n description: string; // 技能描述（1-2句）\n location: 'project' | 'global' | 'plugin';\n}\n```\n\n资料来源：[src/types.ts]()\n\n### 技能来源元数据\n\n```typescript\ninterface SkillSourceMetadata {\n source: string; // 原始安装来源\n sourceType: 'git' | 'local';\n repoUrl?: string; // Git 仓库 URL\n subpath?: string; // 子目录路径\n localPath?: string; // 本地路径\n installedAt: string; // ISO 时间戳\n}\n```\n\n资料来源：[src/commands/install.ts:80-100]()\n\n## 技能安装流程\n\n```mermaid\ngraph TD\n A[install 命令] --> B{解析来源类型}\n B -->|GitHub URL| C[克隆仓库]\n B -->|本地路径| D[验证本地目录]\n B -->|SSH URL| E[使用 SSH 克隆]\n C --> F[扫描 SKILL.md 文件]\n D --> F\n E --> F\n F --> G{检查冲突}\n G -->|项目安装| H[复制到 .claude/skills/]\n G -->|全局安装| I[复制到 ~/.claude/skills/]\n G -->|通用安装| J[复制到 .agent/skills/]\n H --> K[写入元数据]\n I --> K\n J --> K\n K --> L[安装完成]\n```\n\n### 安装元数据构建逻辑\n\n```typescript\nfunction buildMetadataFromSource(\n sourceInfo: InstallSourceInfo,\n skillDir: string,\n repoDir: string\n): SkillSourceMetadata {\n if (sourceInfo.sourceType === 'local') {\n return buildLocalMetadata(sourceInfo, skillDir);\n }\n const subpath = relative(repoDir, skillDir);\n return buildGitMetadata(sourceInfo, normalizedSubpath);\n}\n```\n\n资料来源：[src/commands/install.ts:70-85]()\n\n## AGENTS.md 同步机制\n\n### XML 结构生成\n\n`agents-md.ts` 负责生成兼容 Claude Code 的技能列表 XML：\n\n```typescript\nexport function generateSkillsXml(skills: Skill[]): string {\n const skillTags = skills\n .map((s) => `\n${s.name}\n${s.description}\n${s.location}\n`)\n .join('\\n\\n');\n // 返回完整的 skills_system XML 块\n}\n```\n\n资料来源：[src/utils/agents-md.ts:60-80]()\n\n### AGENTS.md 模板结构\n\n```xml\n\n\n## Available Skills\n\n\n\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.\n- Invoke: `npx openskills read ` (run in your shell)\n- Only use skills listed in \n\n\n\n\n${skillTags}\n\n\n\n\n\n```\n\n资料来源：[src/utils/agents-md.ts:1-30]()\n\n### 内容替换策略\n\n```mermaid\ngraph LR\n A[读取 AGENTS.md] --> B{检测标记类型}\n B -->|XML 标记| C[使用正则替换 skills_system 块]\n B -->|HTML 注释| D[使用正则替换 TABLE 块]\n C --> E[写入更新后的内容]\n D --> E\n```\n\n替换逻辑支持两种标记格式以保证向后兼容：\n- XML 格式：`...`\n- HTML 注释格式：`...`\n\n资料来源：[src/utils/agents-md.ts:40-55]()\n\n## 技能更新机制\n\n### 更新流程\n\n```mermaid\ngraph TD\n A[update 命令] --> B[读取技能元数据]\n B --> C{判断来源类型}\n C -->|local| D[验证本地路径存在]\n C -->|git| E[克隆最新仓库]\n D -->|路径缺失| F[跳过并警告]\n D -->|路径有效| G[复制文件到安装目录]\n E --> G\n G --> H[更新 installedAt 时间戳]\n H --> I[更新完成]\n```\n\n### 本地源处理\n\n```typescript\nif (metadata.sourceType === 'local') {\n const localPath = metadata.localPath;\n if (!localPath || !existsSync(localPath)) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (local source missing)`));\n continue;\n }\n if (!existsSync(join(localPath, 'SKILL.md'))) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (SKILL.md missing)`));\n continue;\n }\n updateSkillFromDir(skill.path, localPath);\n}\n```\n\n资料来源：[src/commands/update.ts:1-30]()\n\n## 技能目录结构\n\n### 安装优先级\n\n系统支持多层级的技能安装目录，按优先级从高到低排列：\n\n| 优先级 | 目录 | 说明 |\n|--------|------|------|\n| 1 | `./.agent/skills/` | 通用安装（多代理环境） |\n| 2 | `~/.agent/skills/` | 用户级通用安装 |\n| 3 | `./.claude/skills/` | 项目本地安装 |\n| 4 | `~/.claude/skills/` | 全局安装 |\n\n安装时使用 `--universal` 标志会将技能安装到 `.agent/skills/`，适用于同时使用 Claude Code 和其他代理（如 Cursor、Windsurf、Aider）的场景。\n\n资料来源：[README.md]() 和 [src/cli.ts]()\n\n### 技能包标准结构\n\n```\nskill-name/\n├── SKILL.md # 必需：技能定义文件\n├── references/ # 可选：参考文档（API 文档、详细指南）\n├── scripts/ # 可选：可执行脚本（Python/Bash）\n└── assets/ # 可选：静态资源（模板、图片）\n```\n\n## 错误处理机制\n\n```typescript\n// 错误处理流程\nif (err.code === 'commander.unknownOption' || err.code === 'commander.invalidArgument') {\n // 参数错误：Commander 已显示错误信息\n process.exit(1);\n}\n// 其他错误\nprocess.exit(err.exitCode || 1);\n```\n\n资料来源：[src/cli.ts:10-20]()\n\n### 冲突检测\n\n安装前会检查目标路径是否已存在技能：\n\n```typescript\nasync function warnIfConflict(\n skillName: string, \n targetPath: string, \n isProject: boolean, \n skipPrompt = false\n): Promise {\n if (existsSync(targetPath)) {\n if (skipPrompt) {\n // 自动覆盖模式\n }\n // 交互式确认模式\n }\n return true;\n}\n```\n\n资料来源：[src/commands/install.ts:95-110]()\n\n## SKILL.md 格式规范\n\n### YAML 前置元数据\n\n每个技能必须以 YAML frontmatter 开头：\n\n```yaml\n---\nname: skill-name # 必需：连字符格式标识符\ndescription: 技能用途描述 # 必需：1-2句话，第三人称\n---\n```\n\n### 渐进式加载策略\n\n| 层级 | 内容 | 加载时机 |\n|------|------|----------|\n| 元数据层 | name + description | 始终在上下文中 |\n| 技能说明层 | SKILL.md 内容 | 相关任务时加载 |\n| 资源层 | references/ | 按需选择性加载 |\n\n### 编写规范\n\n- 使用祈使语气：\"To do X, execute Y\"\n- 避免第二人称：\"You should...\" 改为 \"执行...\"\n- SKILL.md 控制在 5000 词以内\n- 详细内容移至 `references/` 目录\n\n资料来源：[examples/my-first-skill/references/skill-format.md]()\n\n## 测试覆盖\n\n项目使用 Vitest 框架进行测试，测试套件包含：\n\n| 测试类型 | 覆盖范围 |\n|----------|----------|\n| 单元测试 | 符号链接检测、YAML 解析 |\n| 集成测试 | install、sync 命令 |\n| 端到端测试 | 完整 CLI 工作流 |\n\n运行测试命令：\n```bash\nnpm run test # 运行所有测试\nnpm run test:watch # 监听模式\nnpm run test:coverage # 覆盖率报告\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 技术栈总结\n\n| 层级 | 技术选型 | 理由 |\n|------|----------|------|\n| 运行时 | Node.js 20.6+ | 现代化异步特性支持 |\n| 开发语言 | TypeScript 5.9 | 类型安全保证 |\n| CLI 框架 | Commander 12 | 成熟的命令行解析 |\n| 用户交互 | Inquirer 7 + Ora | 美观的交互体验 |\n| 构建工具 | tsup 8 | 快速的 TypeScript 打包 |\n| 测试框架 | Vitest 4 | 高性能的 Vite 集成测试 |\n\n此架构设计确保了 OpenSkills 能够作为一个轻量级、跨平台、与 Claude Code 完全兼容的技能管理系统运行。\n\n---\n\n\n\n## CLI命令参考\n\n### 相关页面\n\n相关主题：[install命令详解](#page-install-command), [sync命令详解](#page-sync-command), [update命令详解](#page-update-command)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n- [src/commands/list.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/list.ts)\n- [src/commands/read.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/read.ts)\n- [src/commands/manage.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/manage.ts)\n- [src/commands/remove.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/remove.ts)\n- [src/commands/sync.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/sync.ts)\n- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n \n\n# CLI命令参考\n\nOpenSkills 是一个为AI编码助手设计的通用技能加载工具，通过命令行接口（CLI）实现技能的安装、管理和同步功能。本页面详细介绍 OpenSkills CLI 的所有命令及其用法。\n\n## 概述\n\nOpenSkills CLI 提供了一套完整的命令，用于管理 AI 代理技能的生命周期。CLI 基于 Node.js 构建，使用 Commander.js 作为命令行参数解析框架，并集成了 Inquirer.js 用于交互式提示。 资料来源：[src/cli.ts:1-50]()\n\n### 核心功能模块\n\n| 模块 | 功能描述 |\n|------|----------|\n| `install` | 从各种来源安装技能（GitHub、本地路径、私有仓库） |\n| `list` | 列出所有已安装的技能 |\n| `read` | 读取技能内容并输出到标准输出 |\n| `update` | 从源更新已安装的技能 |\n| `sync` | 同步技能信息到 AGENTS.md 文件 |\n| `manage` | 交互式管理技能（删除） |\n| `remove` | 移除指定的技能 |\n\n## 命令详解\n\n### install - 安装技能\n\n`install` 命令用于从多种来源安装 AI 技能到本地环境。\n\n#### 基本语法\n\n```bash\nnpx openskills install [options]\n```\n\n#### 参数与选项\n\n| 参数/选项 | 类型 | 说明 |\n|-----------|------|------|\n| `` | 位置参数 | 安装来源（GitHub仓库、本地路径、Git URL） |\n| `-g, --global` | 选项 | 全局安装到 `~/.claude/skills/` |\n| `-u, --universal` | 选项 | 安装到 `.agent/skills/` 用于多代理环境 |\n| `-y, --yes` | 选项 | 跳过交互确认，自动安装所有找到的技能 |\n\n#### 安装来源类型\n\n1. **Anthropic Marketplace**\n ```bash\n npx openskills install anthropics/skills\n ```\n\n2. **任意 GitHub 仓库**\n ```bash\n npx openskills install your-org/your-skills\n ```\n\n3. **本地路径**\n ```bash\n npx openskills install ./local-skills/my-skill\n ```\n\n4. **私有 Git 仓库**\n ```bash\n npx openskills install git@github.com:your-org/private-skills.git\n ```\n\n#### 安装行为流程\n\n```mermaid\ngraph TD\n A[install 命令执行] --> B{源类型判断}\n B -->|GitHub| C[克隆远程仓库]\n B -->|本地路径| D[验证本地路径存在]\n B -->|私有仓库| E[使用SSH密钥克隆]\n C --> F[定位 SKILL.md]\n D --> F\n E --> F\n F --> G{安装位置判断}\n G -->|项目级| H[安装到 .claude/skills/]\n G -->|全局| I[安装到 ~/.claude/skills/]\n G -->|通用| J[安装到 .agent/skills/]\n H --> K[写入技能元数据]\n I --> K\n J --> K\n K --> L[安装完成]\n```\n\n#### 元数据构建\n\n安装过程中，系统会根据来源类型构建不同的元数据：\n\n| 来源类型 | 元数据字段 |\n|----------|------------|\n| Git 来源 | `sourceType: 'git'`、`repoUrl`、`subpath`、`installedAt` |\n| 本地来源 | `sourceType: 'local'`、`localPath`、`installedAt` |\n\n资料来源：[src/commands/install.ts:1-80]()\n\n---\n\n### list - 列出技能\n\n`list` 命令显示所有已安装的技能及其状态信息。\n\n#### 基本语法\n\n```bash\nnpx openskills list\n```\n\n#### 输出示例\n\n```\n📦 已安装技能\n\n├── pdf [project] /path/to/project/.claude/skills/pdf\n├── git-workflow [global] ~/.claude/skills/git-workflow\n└── check-branch-first [project] /path/to/project/.claude/skills/check-branch-first\n```\n\n---\n\n### read - 读取技能内容\n\n`read` 命令将技能内容输出到标准输出，供 AI 代理读取。\n\n#### 基本语法\n\n```bash\nnpx openskills read \n```\n\n#### 参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `` | 剩余参数 | 一个或多个技能名称，用空格分隔 |\n\n#### 使用示例\n\n```bash\n# 读取单个技能\nnpx openskills read pdf\n\n# 读取多个技能（逗号分隔）\nnpx openskills read foo,bar\n\n# 读取多个技能（空格分隔）\nnpx openskills read pdf git-workflow check-branch\n```\n\n#### 输出格式\n\n读取技能时，输出包含以下信息：\n\n- **基础目录路径**：用于解析相对资源路径\n- **完整 SKILL.md 内容**：包含技能指令和元数据\n- **引用资源路径**：references/、scripts/、assets/ 的相对路径\n\n---\n\n### update - 更新技能\n\n`update` 命令从原始源重新获取并更新已安装的技能。\n\n#### 基本语法\n\n```bash\nnpx openskills update [skill-names...]\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `[skill-names...]` | 可选参数 | 指定要更新的技能名称，默认为全部 |\n\n#### 更新流程\n\n```mermaid\ngraph TD\n A[update 命令执行] --> B{是否指定技能}\n B -->|是| C[筛选目标技能]\n B -->|否| D[加载所有技能]\n C --> E{技能元数据检查}\n D --> E\n E -->|本地来源| F[验证本地路径存在]\n E -->|Git 来源| G[克隆远程仓库]\n F -->|路径无效| H[跳过并警告]\n F -->|路径有效| I[复制 SKILL.md]\n G --> J[定位子路径]\n I --> K[更新 installedAt 时间戳]\n J --> K\n K --> L[更新完成]\n H --> M[报告跳过列表]\n```\n\n#### 特殊处理\n\n| 场景 | 处理方式 |\n|------|----------|\n| 本地源缺失 | 输出黄色警告并跳过 |\n| SKILL.md 不存在 | 输出警告并跳过 |\n| 缺少仓库 URL | 输出警告并跳过 |\n| Git 克隆失败 | 显示错误信息 |\n\n资料来源：[src/commands/update.ts:1-60]()\n\n---\n\n### sync - 同步到 AGENTS.md\n\n`sync` 命令将已安装的技能信息生成为 `` XML 块，并插入或更新 AGENTS.md 文件。\n\n#### 基本语法\n\n```bash\nnpx openskills sync [options]\n```\n\n#### 选项说明\n\n| 选项 | 说明 |\n|------|------|\n| `-y, --yes` | 跳过交互确认，同步所有技能 |\n| `-o, --output ` | 指定输出文件路径（默认：AGENTS.md） |\n\n#### 输出文件格式\n\n```markdown\n\n\n## Available Skills\n\n\n\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively...\n\nHow to use skills:\n- Invoke: `npx openskills read ` (run in your shell)\n- The skill content will load with detailed instructions...\n\n\n\n\npdf\nComprehensive PDF manipulation toolkit...\nproject\n\n\n\n\n\n```\n\n#### XML 标记说明\n\n| 标记 | 说明 |\n|------|------|\n| `` | 根元素，包含优先级属性 |\n| `` | 技能列表容器 |\n| `` | 单个技能定义块 |\n| `` | 技能名称（英文、中划线分隔） |\n| `` | 技能描述（1-2句话） |\n| `` | 安装位置（project/global） |\n\n---\n\n### manage - 交互式管理\n\n`manage` 命令提供交互式界面用于管理已安装的技能。\n\n#### 基本语法\n\n```bash\nnpx openskills manage\n```\n\n#### 交互流程\n\n1. 显示已安装技能列表\n2. 提供多选界面选择要移除的技能\n3. 确认后执行删除操作\n4. 更新 AGENTS.md（如需要）\n\n---\n\n### remove - 移除技能\n\n`remove` 命令直接移除指定的技能，无需交互确认。\n\n#### 基本语法\n\n```bash\nnpx openskills remove \n```\n\n#### 参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `` | 位置参数 | 要移除的技能名称 |\n\n#### 使用示例\n\n```bash\nnpx openskills remove pdf\nnpx openskills remove git-workflow\n```\n\n---\n\n## 安装优先级\n\n当使用 `--universal` 选项或存在多个安装位置时，技能加载遵循以下优先级顺序（优先级高者优先）：\n\n```mermaid\ngraph LR\n A1[.agent/skills/] --> A[优先级 1]\n A2[~/.agent/skills/] --> A\n B1[.claude/skills/] --> B[优先级 2]\n B2[~/.claude/skills/] --> B\n A --> C[技能加载顺序]\n B --> C\n```\n\n| 优先级 | 路径 | 用途 |\n|--------|------|------|\n| 1 | `./.agent/skills/` | 多代理通用设置 |\n| 1 | `~/.agent/skills/` | 全局多代理设置 |\n| 2 | `./.claude/skills/` | 项目级 Claude Code 设置 |\n| 2 | `~/.claude/skills/` | 全局 Claude Code 设置 |\n\n---\n\n## 环境要求\n\n| 要求 | 最低版本 |\n|------|----------|\n| Node.js | 20.6.0+ |\n| Git | 任意版本 |\n\n---\n\n## 命令速查表\n\n| 命令 | 用法 | 核心功能 |\n|------|------|----------|\n| `install` | `npx openskills install ` | 安装技能 |\n| `list` | `npx openskills list` | 列出已安装技能 |\n| `read` | `npx openskills read [,...]` | 读取技能内容 |\n| `update` | `npx openskills update [name...]` | 更新技能 |\n| `sync` | `npx openskills sync [-y] [-o ]` | 同步到 AGENTS.md |\n| `manage` | `npx openskills manage` | 交互式管理 |\n| `remove` | `npx openskills remove ` | 移除技能 |\n\n---\n\n\n\n## install命令详解\n\n### 相关页面\n\n相关主题：[CLI命令参考](#page-cli-commands), [数据存储与管理](#page-data-storage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)\n- [src/utils/marketplace-skills.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/marketplace-skills.ts)\n- [src/utils/yaml.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/yaml.ts)\n- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)\n \n\n# install命令详解\n\n## 概述\n\n`install` 是 OpenSkills 的核心命令之一，负责从各种来源安装技能（Skills）。该命令支持从 GitHub 仓库、本地路径、Git 远程仓库以及私有仓库安装技能，并自动处理技能元数据的存储和更新。\n\n**功能范围：**\n\n- 从 Anthropic Marketplace 安装预制技能\n- 从任意 GitHub 仓库安装技能\n- 从本地目录安装本地开发的技能\n- 支持私有 Git 仓库安装（SSH/HTTPS）\n- 自动检测并处理符号链接冲突\n- 支持全局安装和项目级安装\n\n**版本历史：**\n- v1.0.0：初始发布\n- v1.2.0：新增 `--universal` 标志\n- v1.5.0：新增本地路径安装和私有仓库支持\n\n资料来源：[package.json:3-24](https://github.com/numman-ali/openskills/blob/main/package.json)\n\n---\n\n## 命令语法\n\n```bash\nnpx openskills install [options]\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `` | string | 是 | 安装来源，可以是 GitHub 仓库、本地路径或 Git URL |\n\n### 可用选项\n\n| 选项 | 简写 | 类型 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `--global` | `-g` | boolean | false | 全局安装到 `~/.claude/skills/` |\n| `--universal` | `-u` | boolean | false | 安装到 `.agent/skills/` 用于多智能体环境 |\n| `--yes` | `-y` | boolean | false | 跳过所有交互提示，自动确认 |\n\n资料来源：[src/cli.ts:26-35](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n\n---\n\n## 安装来源类型\n\nOpenSkills 支持多种安装来源，命令会自动识别来源类型并采用相应的安装策略。\n\n```mermaid\ngraph TD\n A[install source] --> B{来源类型判断}\n B -->|GitHub shorthand| C[marketplace-skills.ts]\n B -->|本地路径| D[本地目录检测]\n B -->|git@ URL| E[SSH 私有仓库]\n B -->|https:// URL| F[HTTPS 私有仓库]\n B -->|github.com URL| G[GitHub 完整 URL]\n \n C --> H[从 Marketplace 获取]\n D --> I[直接复制/Symlink]\n E --> J[SSH 认证克隆]\n F --> K[HTTPS 认证克隆]\n G --> L[直接克隆]\n```\n\n### 1. Anthropic Marketplace\n\n使用简写格式从 Anthropic 官方技能市场安装：\n\n```bash\nnpx openskills install anthropics/skills\nnpx openskills install anthropics/skills/pdf-editor\n```\n\n资料来源：[README.md:30-32](https://github.com/numman-ali/openskills/blob/main/README.md)\n\n### 2. GitHub 仓库\n\n从任意 GitHub 仓库安装，支持完整 URL 或简写格式：\n\n```bash\n# 简写格式\nnpx openskills install owner/repo\nnpx openskills install owner/repo/path/to/skill\n\n# 完整 URL 格式\nnpx openskills install https://github.com/owner/repo\n```\n\n### 3. 本地路径\n\n支持绝对路径、相对路径和波浪号展开：\n\n```bash\n# 绝对路径\nnpx openskills install /path/to/my-skill\n\n# 相对路径\nnpx openskills install ./local-skills/my-skill\nnpx openskills install ../my-skill\n\n# 波浪号展开\nnpx openskills install ~/my-skills/skill\n```\n\n资料来源：[CHANGELOG.md:47-52](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)\n\n### 4. 私有 Git 仓库\n\n支持 SSH 和 HTTPS 两种认证方式：\n\n```bash\n# SSH 方式（使用系统 SSH 密钥）\nnpx openskills install git@github.com:your-org/private-skills.git\n\n# HTTPS 方式（需要配置 Git 认证）\nnpx openskills install https://github.com/your-org/private-skills.git\n```\n\n资料来源：[CHANGELOG.md:53-58](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)\n\n---\n\n## 安装位置与优先级\n\nOpenSkills 提供了多种安装位置选项，适用于不同的使用场景。\n\n```mermaid\ngraph TD\n A[install 命令] --> B{--universal?}\n B -->|是| C[.agent/skills/]\n B -->|否| D{--global?}\n D -->|是| E[~/.claude/skills/]\n D -->|否| F[项目安装]\n F --> G{存在.claude?}\n G -->|是| H[./.claude/skills/]\n G -->|否| I[./.agent/skills/]\n \n style C fill:#ff9999\n style E fill:#99ccff\n style H fill:#99ff99\n style I fill:#99ff99\n```\n\n### 位置优先级（最高优先）\n\n| 优先级 | 位置 | 说明 |\n|--------|------|------|\n| 1 | `./.agent/skills/` | 项目级通用目录（当 `.claude` 不存在时） |\n| 2 | `./.claude/skills/` | 项目级 Claude Code 目录 |\n| 3 | `~/.agent/skills/` | 用户级通用目录 |\n| 4 | `~/.claude/skills/` | 用户级全局目录 |\n\n资料来源：[README.md:44-51](https://github.com/numman-ali/openskills/blob/main/README.md)\n\n---\n\n## 工作流程\n\n### 安装流程图\n\n```mpx openskillsxy\ngraph LR\n A[解析 source 参数] --> B{识别来源类型}\n B -->|GitHub| C[获取仓库信息]\n B -->|本地| D[验证本地路径]\n B -->|Git URL| E[解析 Git URL]\n \n C --> F[克隆或更新仓库]\n D --> G[验证 SKILL.md 存在]\n E --> H[执行 git clone]\n \n F --> I[查找 SKILL.md]\n G --> I\n H --> I\n \n I --> J[创建技能目录]\n J --> K[复制/Symlink 文件]\n K --> L[生成元数据]\n L --> M[写入 metadata.json]\n M --> N[输出安装成功信息]\n```\n\n### 详细步骤说明\n\n1. **来源解析**\n - 解析 `` 参数确定安装类型\n - 提取仓库 URL、组织/仓库名、技能路径等信息\n\n2. **获取技能**\n - GitHub：通过 Git 克隆仓库\n - 本地：验证路径存在且包含 SKILL.md\n\n3. **元数据生成**\n - 创建 `metadata.json` 记录安装来源\n - 存储安装时间、来源类型、仓库 URL 等信息\n\n4. **文件复制**\n - 根据安装类型决定复制或创建符号链接\n - 本地开发模式优先使用符号链接\n\n资料来源：[src/commands/install.ts:50-150](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n\n---\n\n## 元数据结构\n\n每个已安装的技能都包含一个 `metadata.json` 文件，记录技能的来源和安装信息。\n\n### 元数据字段\n\n| 字段 | 类型 | 说明 | 来源类型 |\n|------|------|------|----------|\n| `source` | string | 原始安装命令参数 | 所有 |\n| `sourceType` | string | 来源类型：`git` 或 `local` | 所有 |\n| `repoUrl` | string | Git 仓库 URL | git |\n| `subpath` | string | 技能在仓库中的子路径 | git |\n| `localPath` | string | 本地路径 | local |\n| `installedAt` | string | ISO 8601 安装时间戳 | 所有 |\n\n### Git 来源元数据示例\n\n```json\n{\n \"source\": \"anthropics/skills/pdf-editor\",\n \"sourceType\": \"git\",\n \"repoUrl\": \"https://github.com/anthropics/skills\",\n \"subpath\": \"pdf-editor\",\n \"installedAt\": \"2026-01-20T10:30:00.000Z\"\n}\n```\n\n### 本地来源元数据示例\n\n```json\n{\n \"source\": \"./my-skill\",\n \"sourceType\": \"local\",\n \"localPath\": \"/Users/developer/projects/my-skill\",\n \"installedAt\": \"2026-01-20T10:30:00.000Z\"\n}\n```\n\n资料来源：[src/commands/install.ts:100-120](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n\n---\n\n## 冲突检测与处理\n\n### Claude Code 市场冲突警告\n\n当安装的技能名称与 Claude Code 原生插件市场冲突时，命令会发出警告：\n\n```mermaid\ngraph TD\n A[install skill-name] --> B{目标路径存在?}\n B -->|是| C[检查是否为符号链接]\n C -->|是| D{--yes 标志?}\n C -->|否| E[警告：覆盖风险]\n D -->|是| F[自动覆盖]\n D -->|否| G[询问用户确认]\n B -->|否| H[继续安装]\n E --> G\n```\n\n### 冲突处理规则\n\n| 情况 | 行为 |\n|------|------|\n| `--yes` 模式 | 自动覆盖，不提示 |\n| 交互模式 | 询问用户确认 |\n| 符号链接断开 | 优雅跳过，显示警告 |\n\n资料来源：[src/commands/install.ts:160-180](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n\n---\n\n## 与其他命令的协作\n\n`install` 命令不独立工作，它与其他 OpenSkills 命令紧密配合：\n\n```mermaid\ngraph LR\n A[install] -->|安装技能| B[本地文件系统]\n C[sync] -->|读取安装信息| B\n C -->|生成 AGENTS.md| D[AGENTS.md]\n \n E[update] -->|读取 metadata.json| B\n E -->|更新技能| B\n \n F[read] -->|加载技能内容| B\n F -->|输出到 stdout| G[AI Agent]\n \n H[list] -->|扫描安装目录| B\n H -->|显示技能列表| I[终端]\n```\n\n| 命令 | 与 install 的关系 |\n|------|-------------------|\n| `sync` | 读取已安装技能，生成 AGENTS.md |\n| `update` | 读取 metadata.json，从原来源更新 |\n| `read` | 加载已安装技能的内容 |\n| `list` | 显示所有已安装技能 |\n\n资料来源：[src/cli.ts:20-45](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n\n---\n\n## 使用示例\n\n### 基础安装\n\n```bash\n# 从 Anthropic Marketplace 安装所有技能\nnpx openskills install anthropics/skills\n\n# 安装单个技能\nnpx openskills install anthropics/skills/pdf-editor\n\n# 从其他 GitHub 仓库安装\nnpx openskills install owner/custom-skills\n```\n\n### 项目级 vs 全局安装\n\n```bash\n# 项目级安装（默认）\nnpx openskills install anthropics/skills\n# 安装到: ./.claude/skills/\n\n# 全局安装\nnpx openskills install anthropics/skills --global\n# 安装到: ~/.claude/skills/\n```\n\n### 多智能体环境安装\n\n```bash\n# 使用 --universal 标志\nnpx openskills install anthropics/skills --universal\n# 安装到: ./.agent/skills/\n\n# 可被 Claude Code、Cursor、Windsurf、Aider 等共用\n```\n\n### CI/CD 环境使用\n\n```bash\n# 使用 --yes 跳过所有交互\nnpx openskills install your-org/your-skills --yes\n\n# 指定输出文件\nnpx openskills install your-org/your-skills --yes --output .ruler/AGENTS.md\n```\n\n### 本地开发工作流\n\n```bash\n# 克隆技能仓库到开发目录\ngit clone git@github.com:your-org/my-skills.git ~/dev/my-skills\n\n# 创建符号链接进行开发\nmkdir -p .claude/skills\nln -s ~/dev/my-skills/pdf-editor .claude/skills/pdf-editor\n\n# 安装后更新\nnpx openskills update pdf-editor\n```\n\n资料来源：[README.md:54-66](https://github.com/numman-ali/openskills/blob/main/README.md)\n\n---\n\n## 依赖项\n\n`install` 命令依赖以下核心依赖包：\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| `commander` | ^12.1.0 | CLI 参数解析和命令定义 |\n| `@inquirer/prompts` | ^7.9.0 | 交互式提示（冲突确认等） |\n| `chalk` | ^5.6.2 | 终端彩色输出 |\n| `ora` | ^9.0.0 | 加载动画 |\n\n**系统要求：**\n\n- Node.js >= 20.6.0\n- Git（用于克隆仓库）\n\n资料来源：[package.json:15-20](https://github.com/numman-ali/openskills/blob/main/package.json)\n\n---\n\n## 常见问题\n\n### Q: 安装后技能没有出现在 list 中？\n\n检查技能目录是否正确：\n```bash\nls -la .claude/skills/ # 项目级\nls -la ~/.claude/skills/ # 全局\n```\n\n### Q: 如何安装私有仓库？\n\n确保：\n1. SSH 方式已配置 SSH 密钥\n2. HTTPS 方式已配置 Git 凭证\n\n```bash\n# SSH 方式\ngit clone git@github.com:org/private-skills.git\n\n# 验证 SSH 密钥\nssh -T git@github.com\n```\n\n### Q: 如何处理符号链接冲突？\n\n使用 `--yes` 标志自动覆盖，或手动删除后重新安装：\n```bash\nrm -rf .claude/skills/conflicting-skill\nnpx openskills install owner/skill\n\n---\n\n\n\n## sync命令详解\n\n### 相关页面\n\n相关主题：[CLI命令参考](#page-cli-commands), [SKILL.md格式规范](#page-skill-md-format)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/commands/sync.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/sync.ts)\n- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [src/types.ts](https://github.com/numman-ali/openskills/blob/main/src/types.ts)\n- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n \n\n# sync命令详解\n\n`sync` 是 OpenSkills 的核心命令之一，用于将已安装的技能（Skills）同步到 `AGENTS.md` 文件中，生成可供 AI Agent 识别的 `` XML 区块。本文详细解析该命令的实现原理、工作流程和配置选项。\n\n## 功能概述\n\n`sync` 命令的主要职责是根据已安装技能的元数据，动态生成符合 Anthropic Agent Skills 规范的 XML 内容，并将其注入到 `AGENTS.md` 文件中。生成的 XML 遵循特定的优先级机制，支持渐进式加载（Progressive Disclosure）模式。\n\n**核心功能：**\n\n| 功能 | 描述 |\n|------|------|\n| 技能扫描 | 读取 `.claude/skills/` 或 `.agent/skills/` 目录下的已安装技能 |\n| XML生成 | 生成包含 name、description、location 的 skill 标签 |\n| 文件更新 | 将生成的 XML 区块替换或插入到目标 Markdown 文件 |\n| 输出控制 | 支持自定义输出路径 |\n\n资料来源：[src/cli.ts:35-38]()\n\n## 命令行接口\n\n### 基本语法\n\n```bash\nnpx openskills sync [选项]\n```\n\n### 参数与选项\n\n| 选项 | 简写 | 类型 | 默认值 | 描述 |\n|------|------|------|--------|------|\n| `--yes` | `-y` | 布尔 | `false` | 跳过交互式确认，同步所有技能 |\n| `--output` | `-o` | 路径 | `AGENTS.md` | 指定输出文件路径 |\n\n**使用示例：**\n\n```bash\n# 默认同步到 AGENTS.md\nnpx openskills sync\n\n# 跳过交互确认\nnpx openskills sync -y\n\n# 输出到自定义路径\nnpx openskills sync -o .ruler/AGENTS.md\n```\n\n资料来源：[src/cli.ts:42-45]()\n\n## 工作流程\n\n`sync` 命令的执行流程可分为三个主要阶段：\n\n```mermaid\ngraph TD\n A[启动 sync 命令] --> B[解析命令行参数]\n B --> C{是否指定 -y?}\n C -->|是| D[跳过交互式选择]\n C -->|否| E[显示技能选择列表]\n E --> F[用户选择要同步的技能]\n D --> G[读取已安装技能元数据]\n F --> G\n G --> H[扫描 skills 目录]\n H --> I[解析每个技能的 SKILL.md]\n I --> J[生成 XML 内容]\n J --> K[更新目标文件]\n K --> L[输出完成信息]\n```\n\n### 阶段一：参数解析\n\nCLI 框架（Commander.js）负责解析用户输入的选项。如果未指定 `-y` 标志，命令将启动交互式界面让用户选择要同步的技能。\n\n资料来源：[src/cli.ts:42-45]()\n\n### 阶段二：技能扫描与 XML 生成\n\n系统会遍历指定的 skills 目录（默认为 `.claude/skills/`），读取每个技能目录下的 `SKILL.md` 文件，解析 YAML frontmatter 中的 `name` 和 `description` 字段。\n\n生成的 XML 结构如下：\n\n```xml\n\n\n## Available Skills\n\n\n\n当用户请求任务时，检查以下可用技能...\n\n\n\n\nskill-name\n技能描述\nproject\n\n\n\n\n\n```\n\n资料来源：[src/utils/agents-md.ts:55-85]()\n\n### 阶段三：文件更新\n\n`sync` 命令使用 `replaceSkillsSection` 函数处理目标文件。该函数支持两种标记格式：\n\n1. **XML 标记格式**（首选）：\n ```html\n ...\n ```\n\n2. **HTML 注释格式**（向后兼容）：\n ```html\n ...\n ```\n\n函数会自动检测文件中存在的标记格式，并执行相应的替换操作。\n\n资料来源：[src/utils/agents-md.ts:88-110]()\n\n## 核心实现\n\n### agents-md.ts 工具模块\n\n该模块提供了三个核心函数：\n\n#### `parseCurrentSkills(content: string): string[]`\n\n解析 `AGENTS.md` 文件中当前已列出的技能名称：\n\n```typescript\nconst skillRegex = /[\\s\\S]*?([^<]+)<\\/name>[\\s\\S]*?<\\/skill>/g;\n```\n\n正则表达式匹配 `` 标签块，提取其中的 `` 元素值。\n\n资料来源：[src/utils/agents-md.ts:113-122]()\n\n#### `generateSkillsXml(skills: Skill[]): string`\n\n根据技能数组生成完整的 XML 区块：\n\n```typescript\nexport function generateSkillsXml(skills: Skill[]): string {\n const skillTags = skills\n .map(\n (s) => `\n${s.name}\n${s.description}\n${s.location}\n`\n )\n .join('\\n\\n');\n // ... 生成完整 XML 结构\n}\n```\n\n每个技能生成独立的 `` 标签块，包含三个子元素：\n- ``：技能标识符\n- ``：技能描述\n- ``：安装位置（`project` 或 `global`）\n\n资料来源：[src/utils/agents-md.ts:125-148]()\n\n#### `replaceSkillsSection(content: string, newSection: string): string`\n\n执行实际的文件替换操作：\n\n```typescript\nexport function replaceSkillsSection(content: string, newSection: string): string {\n const startMarker = ']*>[\\s\\S]*?<\\/skills_system>/;\n return content.replace(regex, newSection);\n }\n // ... 处理 HTML 注释格式\n}\n```\n\n函数首先尝试使用 XML 标记进行匹配和替换，如果失败则回退到 HTML 注释格式。\n\n资料来源：[src/utils/agents-md.ts:88-110]()\n\n### Skill 数据模型\n\n```typescript\ninterface Skill {\n name: string; // 技能标识符\n description: string; // 技能描述\n location: string; // 安装位置：'project' | 'global'\n}\n```\n\n资料来源：[src/types.ts]()\n\n## 与 update 命令的协同\n\n`sync` 命令与 `update` 命令存在密切配合关系。当用户执行 `npx openskills update` 时，更新后的技能元数据会被重新写入，此时可以使用 `sync` 命令将更新后的技能信息同步到 `AGENTS.md`：\n\n```bash\n# 更新所有技能后同步\nnpx openskills update\nnpx openskills sync\n```\n\n`update` 命令支持更新本地路径安装的技能：\n\n```typescript\nif (metadata.sourceType === 'local') {\n const localPath = metadata.localPath;\n if (!existsSync(localPath)) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (local source missing)`));\n continue;\n }\n updateSkillFromDir(skill.path, localPath);\n writeSkillMetadata(skill.path, { ...metadata, installedAt: new Date().toISOString() });\n}\n```\n\n资料来源：[src/commands/update.ts:89-102]()\n\n## 输出文件格式\n\n`sync` 命令生成的文件采用固定的模板结构，包含以下部分：\n\n| 部分 | 描述 |\n|------|------|\n| `` | 根元素，包含 `priority=\"1\"` 属性 |\n| `` | 使用说明文本，指导 AI Agent 如何调用技能 |\n| `` | 技能列表容器 |\n| `` | 单个技能定义块 |\n\n**生成的完整结构示例：**\n\n```xml\n\n\n## Available Skills\n\n\n\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.\n\nHow to use skills:\n- Invoke: `npx openskills read ` (run in your shell)\n - For multiple: `npx openskills read skill-one,skill-two`\n- The skill content will load with detailed instructions\n- Base directory provided in output for resolving bundled resources\n\nUsage notes:\n- Only use skills listed in below\n- Do not invoke a skill that is already loaded in your context\n\n\n\n\npdf\nComprehensive PDF manipulation toolkit...\nproject\n\n\n\n\n\n```\n\n资料来源：[src/utils/agents-md.ts:55-85]()\n\n## 配置选项详解\n\n### 输出路径配置\n\n`sync` 命令支持通过 `-o` 或 `--output` 选项指定输出文件路径：\n\n| 输入 | 输出位置 |\n|------|----------|\n| `npx openskills sync` | `./AGENTS.md` |\n| `npx openskills sync -o .ruler/AGENTS.md` | `./.ruler/AGENTS.md` |\n| `npx openskills sync -o /absolute/path/file.md` | `/absolute/path/file.md` |\n\n**特殊功能：**\n\n- **自动创建目录**：如果指定的输出路径包含不存在的目录，系统会自动创建\n- **自动创建文件**：如果目标文件不存在，系统会创建文件并添加标题\n- **自动创建区块**：如果文件中不存在 `` 区块，系统会自动插入\n\n资料来源：[src/cli.ts:42-45]()\n\n### 非交互模式\n\n使用 `-y` 或 `--yes` 标志可以跳过所有交互式确认，直接同步所有已安装的技能：\n\n```bash\n# CI/CD 环境推荐用法\nnpx openskills sync -y\n```\n\n此模式适用于自动化脚本和持续集成环境。\n\n## 最佳实践\n\n### 1. 定期同步\n\n建议在以下时机执行 `sync` 命令：\n\n| 时机 | 原因 |\n|------|------|\n| 安装新技能后 | 确保新技能被 AI Agent 识别 |\n| 移除技能后 | 清理 AGENTS.md 中的过时信息 |\n| 更新技能描述后 | 同步最新的技能元数据 |\n\n### 2. 多代理环境配置\n\n在同时使用 Claude Code 和其他 Agent（如 Cursor、Windsurf）的环境中，推荐使用 `--universal` 标志安装技能到 `.agent/skills/` 目录：\n\n```bash\nnpx openskills install your-org/your-skills --universal\nnpx openskills sync -o .agent/AGENTS.md\n```\n\n这样可以避免与 Claude Code 原生插件市场的冲突。\n\n### 3. 版本控制建议\n\n将 `AGENTS.md` 纳入版本控制，确保团队成员获得一致的技能配置。\n\n## 错误处理\n\n`sync` 命令可能遇到的错误场景及处理方式：\n\n| 错误场景 | 处理方式 |\n|----------|----------|\n| 目标目录不存在 | 自动创建目录结构 |\n| 目标文件只读 | 报错并提示修改权限 |\n| skills 目录为空 | 生成空的 `` 区块 |\n| YAML 解析失败 | 跳过该技能，显示警告信息 |\n\n## 相关命令\n\n| 命令 | 功能 | 关系 |\n|------|------|------|\n| `install` | 安装技能到本地 | sync 依赖已安装的技能 |\n| `update` | 更新技能版本 | 与 sync 配合使用 |\n| `list` | 列出已安装技能 | 提供参考信息 |\n| `read` | 读取技能内容 | AI Agent 实际调用技能 |\n\n## 总结\n\n`sync` 命令是 OpenSkills 生态系统的关键连接点，它将本地安装的技能与 AI Agent 的上下文系统桥接起来。通过解析已安装技能的元数据并生成符合规范的 XML 内容，该命令使得 AI Agent 能够在需要时动态加载相应的技能指导。\n\n核心要点：\n- 使用 `-o` 选项支持灵活的输出路径配置\n- `-y` 标志实现完全非交互式同步\n- 支持 XML 和 HTML 注释两种标记格式\n- 自动处理文件创建和目录结构\n\n---\n\n\n\n## update命令详解\n\n### 相关页面\n\n相关主题：[install命令详解](#page-install-command), [数据存储与管理](#page-data-storage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n- [src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)\n- [src/utils/skills.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skills.ts)\n- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n \n\n# update命令详解\n\n## 概述\n\n`update` 命令是 OpenSkills 提供的核心功能之一，用于从已记录的源代码刷新已安装的技能（Skills）。该命令在 v1.5.0 版本中引入，解决了用户安装技能后如何获取更新的问题。\n\n### 核心功能\n\n- 从 Git 仓库更新技能\n- 从本地目录更新技能\n- 批量更新所有已安装的技能\n- 跳过无法确定源代码的技能并给出提示\n\n资料来源：[CHANGELOG.md](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)\n\n---\n\n## 架构设计\n\n### 模块依赖关系\n\n```mermaid\ngraph TD\n A[CLI入口 update命令] --> B[commands/update.ts]\n B --> C[skill-metadata.ts]\n B --> D[skills.ts]\n B --> E[文件系统操作]\n \n C --> F[SkillSourceMetadata接口]\n C --> G[元数据读写]\n \n D --> H[技能目录扫描]\n D --> I[SKILL.md解析]\n \n E --> J[git clone]\n E --> K[文件复制]\n```\n\n### 元数据结构\n\n```typescript\ninterface SkillSourceMetadata {\n source: string; // 安装源描述\n sourceType: 'git' | 'local'; // 源类型\n repoUrl?: string; // Git仓库URL (git类型)\n subpath?: string; // 子路径 (git类型)\n localPath?: string; // 本地路径 (local类型)\n installedAt: string; // 安装时间ISO字符串\n}\n```\n\n资料来源：[src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)\n\n---\n\n## 工作流程\n\n### 更新流程图\n\n```mermaid\ngraph TD\n Start[开始更新] --> LoadSkills[加载所有已安装技能]\n LoadSkills --> ForEach{遍历每个技能}\n \n ForEach --> |本地源| CheckLocalPath{检查localPath是否存在}\n CheckLocalPath --> |不存在| SkipMissing[跳过并提示缺失]\n SkipMissing --> Next1[下一个技能]\n \n CheckLocalPath --> |存在| CheckSkillMd{检查SKILL.md}\n CheckSkillMd --> |不存在| SkipNoSkillMd[跳过并提示SKILL.md缺失]\n SkipNoSkillMd --> Next2[下一个技能]\n \n CheckSkillMd --> |存在| CopyFromLocal[从本地复制文件]\n CopyFromLocal --> UpdateMeta[更新元数据installedAt]\n UpdateMeta --> Next3[下一个技能]\n \n ForEach --> |Git源| CheckRepoUrl{检查repoUrl}\n CheckRepoUrl --> |不存在| SkipNoUrl[跳过并提示缺失repoUrl]\n SkipNoUrl --> Next4[下一个技能]\n \n CheckRepoUrl --> |存在| CloneTemp[克隆到临时目录]\n CloneTemp --> ExtractSource[提取子目录源文件]\n ExtractSource --> CopyToTarget[复制到技能目录]\n CopyToTarget --> UpdateMeta2[更新元数据installedAt]\n UpdateMeta2 --> Next5[下一个技能]\n \n Next1 --> |完成| Cleanup[清理临时目录]\n Next2 --> Cleanup\n Next3 --> Cleanup\n Next4 --> Cleanup\n Next5 --> Cleanup\n \n Cleanup --> Report[输出更新结果统计]\n```\n\n---\n\n## 源码解析\n\n### 命令注册\n\n`update` 命令通过 Commander.js 在 CLI 入口点注册：\n\n```typescript\nprogram\n .command('update [skill-names...]')\n .description('Update installed skills from their source (default: all)')\n .action(updateSkills);\n```\n\n资料来源：[src/cli.ts:51-53](https://github.com/numman-ali/openskills/blob/main/src/cli.ts#L51-L53)\n\n### 本地源更新逻辑\n\n当技能源类型为 `local` 时，执行以下流程：\n\n```typescript\nif (metadata.sourceType === 'local') {\n const localPath = metadata.localPath;\n \n // 检查本地路径是否存在\n if (!localPath || !existsSync(localPath)) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (local source missing)`));\n missingLocalSource.push(skill.name);\n skipped++;\n continue;\n }\n \n // 检查SKILL.md是否存在\n if (!existsSync(join(localPath, 'SKILL.md'))) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (SKILL.md missing at local source)`));\n missingLocalSkillFile.push(skill.name);\n skipped++;\n continue;\n }\n \n // 执行更新\n updateSkillFromDir(skill.path, localPath);\n writeSkillMetadata(skill.path, { ...metadata, installedAt: new Date().toISOString() });\n console.log(chalk.green(`✅ Updated: ${skill.name}`));\n updated++;\n}\n```\n\n资料来源：[src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n\n### Git源更新逻辑\n\n当技能源类型为 `git` 时，执行以下流程：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Update as update命令\n participant FS as 文件系统\n participant Git as Git\n \n User->>Update: 执行 update 命令\n Update->>FS: 创建临时目录 ~/.openskills-temp-{timestamp}\n Update->>Git: git clone --depth 1 {repoUrl}\n Git-->>FS: 克隆到 tempDir/repo\n Update->>FS: 提取子目录文件\n Update->>FS: 复制到技能安装目录\n Update->>FS: 更新元数据 (installedAt)\n Update->>FS: 清理临时目录\n Update->>User: 输出更新结果\n```\n\n关键实现代码：\n\n```typescript\nif (!metadata.repoUrl) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (missing repo URL metadata)`));\n missingRepoUrl.push(skill.name);\n skipped++;\n continue;\n}\n\nconst tempDir = join(homedir(), `.openskills-temp-${Date.now()}`);\nmkdirSync(tempDir, { recursive: true });\n\nconst spinner = ora(`Updating ${skill.name}...`).start();\ntry {\n execSync(`git clone --depth 1 --quiet \"${metadata.repoUrl}\" \"${tempDir}/repo\"`, { \n stdio: 'pipe' \n });\n \n const repoDir = join(tempDir, 'repo');\n const subpath = metadata.subpath && metadata.subpath !== '.' ? metadata.subpath : '';\n const sourceDir = subpath ? join(repoDir, subpath) : repoDir;\n \n // 继续处理...\n} finally {\n // 清理临时目录\n}\n```\n\n资料来源：[src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n\n---\n\n## 使用方法\n\n### 基本语法\n\n```bash\nnpx openskills update [skill-names...]\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| skill-names | string[] | 否 | 要更新的技能名称，不提供则更新所有技能 |\n\n### 使用场景\n\n#### 更新所有技能\n\n```bash\n# 更新所有已安装的技能\nnpx openskills update\n```\n\n#### 更新指定技能\n\n```bash\n# 更新单个技能\nnpx openskills update pdf\n\n# 更新多个技能\nnpx openskills update pdf,git-workflow,check-branch-first\n```\n\n---\n\n## 输出示例\n\n### 成功更新\n\n```\n✅ Updated: pdf\n✅ Updated: git-workflow\n✅ Updated: check-branch-first\n\n更新完成: 3 个技能已更新\n```\n\n### 跳过技能\n\n```\nSkipped: some-skill (missing repo URL metadata)\n\n⚠️ 1 个技能跳过（无源代码信息）\n```\n\n### 输出统计\n\n```typescript\n// 更新完成后显示统计\nconsole.log(`\\n✅ 更新完成: ${updated} 个技能已更新`);\n\nif (skipped > 0) {\n console.log(`⚠️ ${skipped} 个技能跳过`);\n console.log('提示: 重新安装技能以获取源代码信息');\n}\n```\n\n资料来源：[src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n\n---\n\n## 错误处理\n\n### 错误类型与处理策略\n\n| 错误类型 | 处理策略 | 用户提示 |\n|----------|----------|----------|\n| 本地源路径不存在 | 跳过 | `Skipped: {name} (local source missing)` |\n| 本地源缺少SKILL.md | 跳过 | `Skipped: {name} (SKILL.md missing at local source)` |\n| Git仓库URL缺失 | 跳过 | `Skipped: {name} (missing repo URL metadata)` |\n| Git克隆失败 | 标记失败 | 显示错误信息 |\n| 文件复制失败 | 标记失败 | 显示错误信息 |\n\n### 临时目录清理\n\n更新完成后，无论成功与否，都会清理临时目录：\n\n```typescript\nfinally {\n if (existsSync(tempDir)) {\n rmSync(tempDir, { recursive: true, force: true });\n }\n}\n```\n\n---\n\n## 相关配置\n\n### 元数据存储位置\n\n每个技能的元数据存储在 `~/.claude/skills/{skill-name}/.skill-metadata.json` 或 `./.claude/skills/{skill-name}/.skill-metadata.json` 文件中。\n\n### 完整元数据接口\n\n```typescript\ninterface SkillSourceMetadata {\n source: string; // 原始安装源\n sourceType: 'git' | 'local'; // 源类型\n repoUrl?: string; // Git仓库地址 (git类型必须)\n subpath?: string; // 仓库中的子路径\n localPath?: string; // 本地绝对路径 (local类型必须)\n installedAt: string; // 安装时间 (ISO 8601格式)\n}\n```\n\n资料来源：[src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)\n\n---\n\n## 版本历史\n\n| 版本 | 发布日期 | 变更内容 |\n|------|----------|----------|\n| 1.5.0 | 2026-01-17 | 新增 `openskills update` 命令，支持从源代码刷新已安装技能 |\n| 1.5.0 | 2026-01-17 | 新增源元数据跟踪功能，为更新提供可靠依据 |\n\n资料来源：[CHANGELOG.md](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)\n\n---\n\n## 最佳实践\n\n1. **定期更新**：建议在开始新项目前运行 `npx openskills update` 获取最新技能\n2. **版本控制**：将技能目录加入版本控制可以追踪技能版本变化\n3. **本地开发**：使用符号链接（symlink）可以在开发时实时测试技能更新\n4. **批量处理**：不传参数时自动更新所有技能，适合定期维护\n\n---\n\n\n\n## SKILL.md格式规范\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/my-first-skill/SKILL.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/SKILL.md)\n- [examples/my-first-skill/references/skill-format.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/references/skill-format.md)\n- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)\n- [README.md](https://github.com/numman-ali/openskills/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)\n \n\n# SKILL.md格式规范\n\n## 概述\n\nSKILL.md是OpenSkills项目的核心技能描述格式，它采用Anthropic提出的智能体技能（Agent Skills）规范。该格式基于Markdown语法，结合YAML元数据前端块，用于定义AI编码智能体在执行特定任务时应加载的技能指令和资源文件。\n\nSKILL.md的设计理念是实现**渐进式披露（Progressive Disclosure）**，即根据任务需要动态加载不同详细程度的技能信息，而非一次性将所有内容加载到智能体上下文中。这种方式有效控制了上下文窗口的占用，同时保证了技能使用的灵活性。\n\n资料来源：[examples/my-first-skill/references/skill-format.md:1-25]()\n\n## 文件结构\n\n### 最小化结构\n\n一个基础的SKILL.md技能只需要一个目录和主文件：\n\n```\nmy-skill/\n└── SKILL.md\n```\n\n### 完整结构\n\n包含完整资源的技能应包含以下目录结构：\n\n```\nskill-name/\n├── SKILL.md # 核心指令文档（约2,000字）\n├── references/ # 参考文档目录\n│ ├── api-docs.md # API详细文档\n│ └── guide.md # 使用指南\n├── scripts/ # 可执行脚本目录\n│ ├── helper.sh # Shell脚本\n│ └── process.py # Python脚本\n└── assets/ # 静态资源目录\n └── template.pdf # 模板文件\n```\n\n资料来源：[examples/my-first-skill/references/skill-format.md:60-75]()\n\n### 目录职责\n\n| 目录 | 用途 | 加载到上下文 | 计数限制 |\n|------|------|-------------|---------|\n| `references/` | 详细API文档、数据库schema、指南 | 按需加载 | 无限制 |\n| `scripts/` | Python/Bash等可执行代码 | 不加载 | 不计入字数 |\n| `assets/` | 模板、图片等输出文件 | 不加载 | 不计入字数 |\n\n资料来源：[examples/my-first-skill/references/skill-format.md:45-60]()\n\n## YAML前端块规范\n\n每个SKILL.md文件必须以YAML前端块开始，该块用于定义技能的基本元数据。\n\n### 必需字段\n\n```yaml\n---\nname: skill-name # 必需：连字符分隔的标识符\ndescription: When to use # 必需：1-2句话的第三人称描述\n---\n```\n\n### 字段说明\n\n| 字段 | 类型 | 必填 | 格式要求 | 示例 |\n|------|------|------|----------|------|\n| `name` | string | 是 | 小写字母、连字符 | `pdf-editor`、`git-workflow` |\n| `description` | string | 是 | 第三人称、1-2句 | `Comprehensive PDF manipulation toolkit...` |\n\n### 命名规范\n\n- 仅使用小写字母\n- 使用连字符（`-`）分隔单词\n- 避免使用下划线或驼峰命名\n- 名称应简洁且具有描述性\n\n资料来源：[examples/my-first-skill/references/skill-format.md:3-12]()\n\n## Markdown正文规范\n\n### 语气要求\n\n正文内容应使用**祈使句/不定式形式**编写，避免使用第二人称。\n\n**推荐写法：**\n```markdown\nTo accomplish X, execute Y\nLoad this skill when Z\nSee references/guide.md for details\n```\n\n**应避免的写法：**\n```markdown\nYou should do X\nIf you need Y, you should...\nWhen you want Z, you can...\n```\n\n### 段落结构\n\n建议按以下顺序组织内容：\n\n1. **标题** - 使用技能名称作为主标题\n2. **目的说明** - 简要说明技能用途\n3. **使用场景** - 何时应加载此技能\n4. **执行步骤** - 完成任务的具体指令\n5. **资源引用** - 指向bundled resources的链接\n\n资料来源：[examples/my-first-skill/SKILL.md:1-40]()\n\n## 渐进式披露机制\n\nSKILL.md采用三级渐进式信息披露机制，智能体根据任务需求动态加载不同层级的信息。\n\n```mermaid\ngraph TD\n A[任务请求] --> B{技能匹配}\n B -->|匹配成功| C[Level 1: 元数据]\n B -->|需要核心指令| D[Level 2: SKILL.md]\n B -->|需要详细文档| E[Level 3: Resources]\n \n C --> F[name + description]\n D --> G[核心指令步骤]\n E --> H[references/]\n E --> I[scripts/]\n \n style C fill:#90EE90\n style D fill:#87CEEB\n style E fill:#DDA0DD\n```\n\n### 三级加载机制\n\n| 级别 | 内容 | 何时加载 | 上下文占用 |\n|------|------|----------|-----------|\n| **Level 1** | 元数据（name + description） | 始终在上下文中 | 极小 |\n| **Level 2** | SKILL.md核心指令 | 技能被请求时 | 中等 |\n| **Level 3** | resources资源文件 | 按需加载 | 可变 |\n\n资料来源：[examples/my-first-skill/references/skill-format.md:20-30]()\n\n## 文件大小限制\n\n为保证技能加载效率和上下文管理，OpenSkills对不同类型的文件设定了大小限制：\n\n| 文件类型 | 建议大小 | 限制 | 说明 |\n|----------|----------|------|------|\n| SKILL.md | ~2,000字 | < 5,000字 | 核心指令应保持简洁 |\n| references/ | 无限制 | 无限制 | 按需选择性加载 |\n| scripts/ | 可执行 | 不计数 | 不加载到上下文 |\n| assets/ | 无限制 | 无限制 | 仅作为输出使用 |\n\n资料来源：[examples/my-first-skill/references/skill-format.md:35-50]()\n\n## 资源解析机制\n\n当技能被加载时，OpenSkills会提供基础目录路径，技能内的相对路径应从该基础目录解析。\n\n### 资源解析示例\n\n```\nBase directory: /path/to/my-first-skill\n```\n\n相对路径解析规则：\n\n| 相对路径 | 解析结果 |\n|----------|----------|\n| `references/skill-format.md` | `/path/to/my-first-skill/references/skill-format.md` |\n| `scripts/helper.sh` | `/path/to/my-first-skill/scripts/helper.sh` |\n| `assets/template.pdf` | `/path/to/my-first-skill/assets/template.pdf` |\n\n资料来源：[examples/my-first-skill/SKILL.md:55-65]()\n\n## AGENTS.md集成\n\nOpenSkills通过生成特定的XML格式实现与AGENTS.md的集成。技能信息以``块的形式嵌入到AGENTS.md中。\n\n### 生成格式\n\n```xml\n\n\npdf\nComprehensive PDF manipulation toolkit...\nplugin\n\n\n```\n\n### 使用方式\n\n当AI智能体需要使用技能时，应通过以下命令加载：\n\n```bash\nnpx openskills read \n```\n\n对于多个技能，使用逗号分隔：\n\n```bash\nnpx openskills read skill-one,skill-two\n```\n\n资料来源：[src/utils/agents-md.ts:1-50]()\n\n## 最佳实践\n\n### 编写规范\n\n1. **使用祈使语气** - 直接描述操作而非建议\n2. **保持简洁** - SKILL.md应聚焦核心指令，细节移至references\n3. **明确触发条件** - 说明何时应加载此技能\n4. **引用资源** - 使用相对路径引用bundled resources\n\n### 结构建议\n\n```\nskill/\n├── SKILL.md # 简洁的核心指令\n├── references/ # 详细文档\n│ ├── api.md # API参考\n│ └── schemas.md # 数据结构\n└── scripts/ # 辅助脚本\n```\n\n### 常见错误\n\n| 错误类型 | 问题 | 修正方式 |\n|----------|------|----------|\n| 第二人称 | \"You should do X\" | 改为 \"To do X, execute Y\" |\n| 过长内容 | SKILL.md超过5000字 | 将详细文档移至references/ |\n| 路径错误 | 使用绝对路径 | 使用相对于基础目录的相对路径 |\n| 命名不当 | `mySkillName` | 改为 `my-skill-name` |\n\n资料来源：[examples/my-first-skill/SKILL.md:30-50]()\n\n## 完整示例\n\n```markdown\n---\nname: pdf-editor\ndescription: Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms.\n---\n\n# PDF Editor Skill\n\n## Purpose\n\nThis skill provides comprehensive PDF manipulation capabilities.\n\n## When to Use\n\nLoad this skill when:\n- Extracting text from PDF documents\n- Merging or splitting PDF files\n- Creating new PDFs from scratch\n- Working with PDF forms\n\n## Instructions\n\nTo accomplish PDF tasks:\n\n1. Install dependencies: `pip install pypdf2`\n2. Extract text using scripts/extract_text.py\n3. Use references/api-docs.md for detailed API information\n\n## Bundled Resources\n\n- `references/api-docs.md` - Complete API documentation\n- `references/format-guide.md` - PDF format specifications\n- `scripts/extract_text.py` - Text extraction utility\n- `scripts/merge_pdfs.py` - PDF merging tool\n\n## Best Practices\n\n- Always verify PDF encoding before processing\n- Use batch processing for large document sets\n- Handle password-protected files with appropriate permissions\n```\n\n资料来源：[examples/my-first-skill/references/skill-format.md:1-95]()\n\n## 命令行工具集成\n\nOpenSkills提供了一系列命令行工具用于管理SKILL.md格式的技能：\n\n| 命令 | 功能 |\n|------|------|\n| `npx openskills install ` | 从GitHub或本地路径安装技能 |\n| `npx openskills sync` | 同步技能列表到AGENTS.md |\n| `npx openskills list` | 列出已安装的技能 |\n| `npx openskills read ` | 读取技能内容供智能体使用 |\n| `npx openskills update` | 从源更新已安装的技能 |\n| `npx openskills remove ` | 移除指定技能 |\n\n资料来源：[README.md:50-80]()\n\n## 技术实现\n\n### 文件解析流程\n\n```mermaid\ngraph LR\n A[SKILL.md文件] --> B[YAML解析器]\n B --> C[YAML前端块]\n C --> D{验证必需字段}\n D -->|name| E[提取技能名称]\n D -->|description| F[提取描述]\n B --> G[Markdown解析器]\n G --> H[核心指令内容]\n H --> I[上下文注入]\n \n style A fill:#f9f\n style I fill:#9f9\n```\n\n### 元数据存储\n\n技能元数据以JSON格式存储在`.claude/skills/`或`.agent/skills/`目录中：\n\n```json\n{\n \"source\": \"anthropics/skills\",\n \"sourceType\": \"git\",\n \"repoUrl\": \"https://github.com/anthropics/skills\",\n \"subpath\": \"pdf-editor\",\n \"installedAt\": \"2025-01-15T10:30:00Z\"\n}\n```\n\n资料来源：[src/commands/install.ts:1-50]()\n\n\n---\n\n\n\n## 数据存储与管理\n\n### 相关页面\n\n相关主题：[install命令详解](#page-install-command), [update命令详解](#page-update-command)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/utils/dirs.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/dirs.ts)\n- [src/utils/skills.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skills.ts)\n- [src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)\n- [src/utils/skill-names.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-names.ts)\n- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n- [src/commands/sync.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/sync.ts)\n \n\n# 数据存储与管理\n\nOpenSkills 的数据存储与管理模块负责管理技能的安装位置、元数据持久化、技能发现机制以及与 `AGENTS.md` 的同步功能。该模块确保技能能够被正确安装、定位、追踪来源，并在 AI 代理需要时提供可用技能列表。\n\n## 目录结构\n\nOpenSkills 采用分层目录结构存储技能数据，支持项目级别和全局级别的安装。\n\n```mermaid\ngraph TD\n A[用户项目] --> B[.claude/skills/]\n A --> C[.agent/skills/]\n D[用户主目录] --> E[~/.claude/skills/]\n B --> F[skill-name/]\n C --> G[skill-name/]\n E --> H[skill-name/]\n F --> I[SKILL.md]\n F --> J[metadata.json]\n G --> K[SKILL.md]\n G --> K2[metadata.json]\n H --> L[SKILL.md]\n H --> L2[metadata.json]\n```\n\n### 目录层级与优先级\n\n| 位置 | 路径 | 说明 | 优先级 |\n|------|------|------|--------|\n| 项目目录 | `./.claude/skills/` | 项目本地安装（默认） | 最高 |\n| 通用目录 | `./.agent/skills/` | 使用 `--universal` 参数 | 高 |\n| 用户目录 | `~/.claude/skills/` | 全局安装（需 `-g` 参数） | 低 |\n\n资料来源：[src/utils/dirs.ts]() \n\n### 目录路径解析\n\n```typescript\n// 技能目录名称常量\nexport const SKILLS_DIR_NAME = '.claude';\nexport const SKILLS_SUBDIR = 'skills';\n\n// 获取技能安装根目录\nexport function getSkillsRoot(isGlobal: boolean): string {\n if (isGlobal) {\n return join(homedir(), SKILLS_DIR_NAME, SKILLS_SUBDIR);\n }\n return join(process.cwd(), SKILLS_DIR_NAME, SKILLS_SUBDIR);\n}\n```\n\n资料来源：[src/utils/dirs.ts:1-20]()\n\n## 元数据管理\n\n每个已安装的技能都包含一个 `metadata.json` 文件，用于记录技能的来源和安装信息。\n\n### 元数据结构\n\n```typescript\ninterface SkillSourceMetadata {\n source: string; // 原始安装源\n sourceType: 'git' | 'local'; // 源类型\n repoUrl?: string; // Git 仓库 URL（git 类型）\n subpath?: string; // 仓库内子路径（git 类型）\n localPath?: string; // 本地路径（local 类型）\n installedAt: string; // ISO 格式安装时间\n}\n```\n\n资料来源：[src/commands/install.ts:80-95]()\n\n### 元数据写入\n\n```typescript\nfunction writeSkillMetadata(skillPath: string, metadata: SkillSourceMetadata): void {\n const metadataPath = join(skillPath, 'metadata.json');\n writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));\n}\n```\n\n资料来源：[src/commands/install.ts:120-125]()\n\n### 元数据用途\n\n元数据主要用于以下场景：\n\n1. **更新技能**：通过 `openskills update` 命令重新拉取最新版本\n2. **来源追溯**：了解技能的原始安装位置\n3. **冲突检测**：避免与 Claude Code 插件市场产生冲突\n\n资料来源：[src/commands/install.ts:127-145]()\n\n## 技能发现机制\n\n技能发现是定位系统中所有已安装技能的核心功能。\n\n### 技能发现流程\n\n```mermaid\ngraph TD\n A[开始查找技能] --> B[检查 .claude/skills/]\n B --> C{存在?}\n C -->|是| D[遍历子目录]\n C -->|否| E[返回空列表]\n D --> F{包含 SKILL.md?}\n F -->|是| G[添加技能到列表]\n F -->|否| H[跳过目录]\n G --> I{还有更多目录?}\n I -->|是| D\n I -->|否| J[检查全局目录 ~/.claude/skills/]\n J --> K{存在?}\n K -->|是| L[遍历子目录]\n K -->|否| M[返回所有发现的技能]\n L --> F2{SKILL.md?}\n F2 -->|是| G2[添加技能到列表]\n F2 -->|否| H2[跳过]\n G2 --> I2{还有更多?}\n I2 -->|是| L\n I2 -->|否| M[返回技能列表]\n```\n\n### 技能查找实现\n\n```typescript\nexport function findAllSkills(): Skill[] {\n const skills: Skill[] = [];\n \n // 检查项目目录\n const projectDir = join(process.cwd(), '.claude', 'skills');\n if (existsSync(projectDir)) {\n skills.push(...findSkillsInDir(projectDir, 'project'));\n }\n \n // 检查全局目录\n const globalDir = join(homedir(), '.claude', 'skills');\n if (existsSync(globalDir)) {\n skills.push(...findSkillsInDir(globalDir, 'global'));\n }\n \n return skills;\n}\n```\n\n资料来源：[src/utils/skills.ts:10-35]()\n\n### 技能目录遍历\n\n```typescript\nfunction findSkillsInDir(baseDir: string, location: 'project' | 'global'): Skill[] {\n const skills: Skill[] = [];\n const entries = readdirSync(baseDir, { withFileTypes: true });\n \n for (const entry of entries) {\n if (!entry.isDirectory()) continue;\n \n const skillPath = join(baseDir, entry.name);\n const skillMdPath = join(skillPath, 'SKILL.md');\n \n // 跳过符号链接指向不存在的路径\n if (lstatSync(skillPath).isSymbolicLink() && !existsSync(skillPath)) {\n continue;\n }\n \n if (existsSync(skillMdPath)) {\n const skill = parseSkillInfo(skillPath, location);\n if (skill) {\n skills.push(skill);\n }\n }\n }\n \n return skills;\n}\n```\n\n资料来源：[src/utils/skills.ts:40-65]()\n\n### 符号链接处理\n\nOpenSkills 在本地开发工作流中支持符号链接。被破坏的符号链接会被优雅地跳过，不会导致错误：\n\n```typescript\n// 跳过断裂的符号链接\nif (lstatSync(skillPath).isSymbolicLink() && !existsSync(skillPath)) {\n continue;\n}\n```\n\n资料来源：[src/utils/skills.ts:50-52]()\n\n## 技能信息解析\n\n### SKILL.md 文件解析\n\n```typescript\nexport function parseSkillInfo(skillPath: string, location: 'project' | 'global'): Skill | null {\n const skillMdPath = join(skillPath, 'SKILL.md');\n const content = readFileSync(skillMdPath, 'utf-8');\n \n // 解析 YAML frontmatter\n const frontmatterMatch = content.match(/^---\\n([\\s\\S]*?)\\n---/);\n if (!frontmatterMatch) {\n return null;\n }\n \n const frontmatter = parseFrontmatter(frontmatterMatch[1]);\n const name = frontmatter.name || basename(skillPath);\n const description = frontmatter.description || '';\n \n return { name, description, path: skillPath, location };\n}\n```\n\n资料来源：[src/utils/skills.ts:70-95]()\n\n### Frontmatter 解析\n\n```typescript\nfunction parseFrontmatter(yaml: string): Record {\n const result: Record = {};\n const lines = yaml.split('\\n');\n \n for (const line of lines) {\n const match = line.match(/^(\\w+):\\s*(.+)$/);\n if (match) {\n result[match[1]] = match[2].trim();\n }\n }\n \n return result;\n}\n```\n\n资料来源：[src/utils/skills.ts:100-115]()\n\n## AGENTS.md 同步管理\n\n`AGENTS.md` 是 AI 代理读取技能列表的关键文件，sync 命令负责维护其中的技能列表。\n\n### 同步数据流\n\n```mermaid\ngraph LR\n A[技能目录] --> B[findAllSkills]\n B --> C[Skill 对象数组]\n C --> D[generateSkillsXml]\n D --> E[ XML]\n E --> F[replaceSkillsSection]\n F --> G[AGENTS.md 文件]\n```\n\n### 技能 XML 生成\n\n```typescript\nexport function generateSkillsXml(skills: Skill[]): string {\n const skillTags = skills\n .map(\n (s) => `\n${s.name}\n${s.description}\n${s.location}\n`\n )\n .join('\\n\\n');\n \n // 完整的 skills_system XML 结构\n return `\n...\n\n\n${skillTags}\n\n\n`;\n}\n```\n\n资料来源：[src/utils/agents-md.ts:50-80]()\n\n### 当前技能解析\n\n```typescript\nexport function parseCurrentSkills(content: string): string[] {\n const skillNames: string[] = [];\n const skillRegex = /[\\s\\S]*?([^<]+)<\\/name>[\\s\\S]*?<\\/skill>/g;\n \n let match;\n while ((match = skillRegex.exec(content)) !== null) {\n skillNames.push(match[1].trim());\n }\n \n return skillNames;\n}\n```\n\n资料来源：[src/utils/agents-md.ts:85-100]()\n\n### 交互式同步选择\n\nsync 命令支持交互式选择界面：\n\n```typescript\n// 排序：项目级别优先\nconst sorted = skills.sort((a, b) => {\n if (a.location !== b.location) {\n return a.location === 'project' ? -1 : 1;\n }\n return a.name.localeCompare(b.name);\n});\n\n// 预选当前文件中已存在的技能\nconst choices = sorted.map((skill) => ({\n name: `${skill.name} ${skill.location === 'project' ? '(project)' : '(global)'}`,\n value: skill.name,\n description: skill.description.slice(0, 70),\n checked: currentSkills.includes(skill.name) || \n (currentSkills.length === 0 && skill.location === 'project'),\n}));\n```\n\n资料来源：[src/commands/sync.ts:45-65]()\n\n## 技能来源类型\n\n### Git 来源\n\n从 GitHub 仓库安装的技能存储以下信息：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `source` | 原始安装命令参数 | `anthropics/skills/pdf` |\n| `sourceType` | 固定值 `'git'` | `git` |\n| `repoUrl` | 完整仓库 URL | `https://github.com/anthropics/skills` |\n| `subpath` | 仓库内的子目录路径 | `pdf` |\n| `installedAt` | ISO 时间戳 | `2025-10-27T10:30:00.000Z` |\n\n资料来源：[src/commands/install.ts:80-95]()\n\n### 本地来源\n\n从本地路径安装的技能存储以下信息：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `source` | 原始安装命令参数 | `./my-skills/pdf` |\n| `sourceType` | 固定值 `'local'` | `local` |\n| `localPath` | 绝对路径 | `/Users/dev/my-skills/pdf` |\n| `installedAt` | ISO 时间戳 | `2025-10-27T10:30:00.000Z` |\n\n资料来源：[src/commands/install.ts:97-107]()\n\n### 元数据构建\n\n```typescript\nfunction buildMetadataFromSource(\n sourceInfo: InstallSourceInfo,\n skillDir: string,\n repoDir: string\n): SkillSourceMetadata {\n if (sourceInfo.sourceType === 'local') {\n return buildLocalMetadata(sourceInfo, skillDir);\n }\n \n const subpath = relative(repoDir, skillDir);\n const normalizedSubpath = subpath === '' ? '' : subpath;\n return buildGitMetadata(sourceInfo, normalizedSubpath);\n}\n```\n\n资料来源：[src/commands/install.ts:70-85]()\n\n## 技能更新机制\n\n更新功能利用存储的元数据重新拉取技能：\n\n```mermaid\ngraph TD\n A[update 命令] --> B[读取 metadata.json]\n B --> C{检查 sourceType}\n C -->|local| D[验证 localPath 存在]\n C -->|git| E[克隆 repoUrl 仓库]\n D --> F{SKILL.md 存在?}\n E --> G[复制文件到技能目录]\n F -->|是| H[从 localPath 复制]\n F -->|否| I[跳过并警告]\n G --> J[更新 installedAt]\n H --> J\n J --> K[更新完成]\n I --> K\n```\n\n### 本地技能更新\n\n```typescript\nif (metadata.sourceType === 'local') {\n const localPath = metadata.localPath;\n if (!existsSync(localPath)) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (local source missing)`));\n continue;\n }\n if (!existsSync(join(localPath, 'SKILL.md'))) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (SKILL.md missing at local source)`));\n continue;\n }\n updateSkillFromDir(skill.path, localPath);\n writeSkillMetadata(skill.path, { ...metadata, installedAt: new Date().toISOString() });\n}\n```\n\n资料来源：[src/commands/update.ts:10-35]()\n\n### Git 技能更新\n\n```typescript\nconst tempDir = join(homedir(), `.openskills-temp-${Date.now()}`);\nmkdirSync(tempDir, { recursive: true });\n\n// 克隆仓库（浅克隆，仅获取最新）\nexecSync(`git clone --depth 1 --quiet \"${metadata.repoUrl}\" \"${tempDir}/repo\"`, { stdio: 'pipe' });\n\nconst repoDir = join(tempDir, 'repo');\nconst subpath = metadata.subpath && metadata.subpath !== '.' ? metadata.subpath : '';\nconst sourceDir = subpath ? join(repoDir, subpath) : repoDir;\n```\n\n资料来源：[src/commands/update.ts:40-55]()\n\n## 数据模型汇总\n\n### Skill 接口\n\n```typescript\ninterface Skill {\n name: string; // 技能名称（必需）\n description: string; // 技能描述（必需）\n path: string; // 技能文件系统路径\n location: 'project' | 'global'; // 安装位置\n}\n```\n\n### InstallSourceInfo 接口\n\n```typescript\ninterface InstallSourceInfo {\n source: string;\n sourceType: 'git' | 'local';\n repoUrl?: string;\n localPath?: string;\n isUrl: boolean;\n skillName: string;\n skillDir: string;\n}\n```\n\n### AGENTS.md 输出结构\n\n```xml\n\n\n## Available Skills\n\n\n\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.\n...\n\n\n\n\npdf\nComprehensive PDF manipulation toolkit...\nproject\n\n\n\n\n\n```\n\n资料来源：[src/utils/agents-md.ts:1-50]()\n\n## 文件清单\n\n| 文件路径 | 职责 |\n|---------|------|\n| `src/utils/dirs.ts` | 定义目录路径常量和获取函数 |\n| `src/utils/skills.ts` | 技能发现、解析、遍历逻辑 |\n| `src/utils/skill-metadata.ts` | 元数据读写操作 |\n| `src/utils/skill-names.ts` | 技能名称相关工具函数 |\n| `src/commands/install.ts` | 安装命令中的元数据构建逻辑 |\n| `src/commands/sync.ts` | AGENTS.md 同步命令实现 |\n| `src/utils/agents-md.ts` | AGENTS.md XML 生成和解析 |\n\n## 最佳实践\n\n1. **项目级别优先**：默认使用项目级别安装，便于版本控制和团队协作\n2. **元数据完整性**：安装后检查 `metadata.json` 确保信息正确\n3. **符号链接开发**：本地开发时使用符号链接避免重复复制\n4. **定期同步**：更新技能后执行 `npx openskills sync` 保持 AGENTS.md 最新\n5. **冲突预防**：使用 `--universal` 参数避免与 Claude Code 插件市场冲突\n\n---\n\n\n\n## 贡献指南\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/numman-ali/openskills/blob/main/CONTRIBUTING.md)\n- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n \n\n# 贡献指南\n\n本文档为希望参与 OpenSkills 项目开发的贡献者提供完整的开发指南，涵盖开发环境配置、代码规范、测试流程以及提交流程等内容。\n\n## 项目概述\n\nOpenSkills 是一个跨平台的多代理技能管理系统，兼容 Anthropic 的 Agent Skills 规范，支持 Claude Code、Cursor、Windsurf、Aider、Codex 等多种 AI 编码代理工具。项目使用 Node.js 20.6.0+ 作为运行时环境，通过 TypeScript 实现，依赖包括 Commander.js 用于 CLI 框架、Chalk 用于终端着色、Ora 用于加载动画、Inquirer 用于交互式提示。 资料来源：[package.json:1-25]()\n\n## 开发环境配置\n\n### 环境要求\n\n| 组件 | 最低版本 | 说明 |\n|------|---------|------|\n| Node.js | 20.6.0+ | 运行时环境 |\n| Git | 任意版本 | 用于代码版本管理和依赖安装 |\n| npm | 与 Node.js 捆绑 | 包管理器 |\n\n资料来源：[package.json:23]()\n\n### 安装步骤\n\n```bash\n# 克隆项目\ngit clone https://github.com/numman-ali/openskills.git\ncd openskills\n\n# 安装依赖\nnpm install\n```\n\n### 本地链接与测试\n\n开发过程中可以使用 `npm link` 将本地包链接到全局，使 CLI 命令在本地可用：\n\n```bash\nnpm link\n```\n\n链接后即可在任意目录下使用 `openskills` 命令：\n\n```bash\nnpx openskills install anthropics/skills/pdf-editor --project\nnpx openskills sync\nnpx openskills read pdf-editor\n```\n\n资料来源：[CONTRIBUTING.md:1-10]()\n\n## 项目结构\n\n```\nopenskills/\n├── src/\n│ ├── cli.ts # CLI 主入口，定义命令行接口\n│ ├── commands/ # 各子命令实现\n│ │ ├── install.ts # 安装技能命令\n│ │ └── update.ts # 更新技能命令\n│ ├── utils/ # 共享工具函数\n│ │ └── agents-md.ts # AGENTS.md 生成工具\n│ └── types.ts # TypeScript 类型定义\n├── tests/\n│ └── utils/ # 单元测试\n├── package.json\n├── tsconfig.json\n└── vitest.config.ts\n```\n\n### 核心模块职责\n\n| 模块 | 职责 |\n|------|------|\n| cli.ts | 定义所有 CLI 命令及参数解析 |\n| commands/install.ts | 处理技能安装逻辑，包括本地路径、私有仓库、GitHub 等多种来源 |\n| commands/update.ts | 实现技能更新逻辑，支持从源仓库拉取最新内容 |\n| utils/agents-md.ts | 生成符合规范的 `` XML 区块 |\n| types.ts | 定义 Skill、SkillSourceMetadata 等核心数据结构 |\n\n资料来源：[CONTRIBUTING.md:18-24]()\n\n## 开发命令\n\n### 运行测试\n\n```bash\n# 运行所有测试\nnpm run test\n\n# 监听模式（文件变化自动重跑）\nnpm run test:watch\n\n# 生成覆盖率报告\nnpm run test:coverage\n```\n\nOpenSkills 使用 Vitest 作为测试框架，测试文件位于 `tests/utils/` 目录。测试覆盖包括符号链接检测、YAML 解析、install 命令集成测试、sync 命令集成测试以及完整的 E2E CLI 工作流测试。\n\n资料来源：[CONTRIBUTING.md:4-6]()\n\n### 构建项目\n\n```bash\nnpm run build\n```\n\n构建输出通过 tsup 处理，将 TypeScript 编译为 JavaScript 并生成类型声明文件。\n\n### 代码检查与格式化\n\n项目使用 TypeScript 编译器进行类型检查：\n\n```bash\nnpm run lint # 代码风格检查\nnpm run format # 代码格式化\n```\n\n## CLI 命令参考\n\n### 主要命令列表\n\n| 命令 | 功能 | 主要参数 |\n|------|------|----------|\n| `npx openskills install ` | 从 GitHub、本地路径或私有仓库安装技能 | `-g, --global`、`-u, --universal`、`-y, --yes` |\n| `npx openskills sync` | 更新 AGENTS.md 中的技能列表 | `-y, --yes`、`-o, --output ` |\n| `npx openskills list` | 列出所有已安装的技能 | - |\n| `npx openskills read ` | 读取技能内容输出到终端 | - |\n| `npx openskills update [names...]` | 更新已安装的技能 | - |\n| `npx openskills manage` | 交互式管理技能（删除） | - |\n| `npx openskills remove ` | 删除指定技能 | - |\n\n资料来源：[src/cli.ts:19-46]()\n\n### 安装命令详解\n\n```bash\n# 从 GitHub 安装\nnpx openskills install anthropics/skills\n\n# 从本地路径安装\nnpx openskills install ./local-skills/my-skill\n\n# 从私有仓库安装\nnpx openskills install git@github.com:your-org/private-skills.git\n\n# 全局安装\nnpx openskills install anthropics/skills --global\n\n# 通用模式（多代理环境）\nnpx openskills install anthropics/skills --universal\n\n# 非交互模式（CI/CD）\nnpx openskills install anthropics/skills --yes\n```\n\n安装流程会创建符号链接到指定目录（默认为 `./.claude/skills/`），并生成元数据文件记录安装来源信息，便于后续更新。\n\n资料来源：[CONTRIBUTING.md:7-10]()\n\n### 同步命令详解\n\n```bash\n# 同步到默认 AGENTS.md\nnpx openskills sync\n\n# 指定输出文件\nnpx openskills sync -o .ruler/AGENTS.md\n\n# 非交互模式\nnpx openskills sync --yes\n```\n\nsync 命令会扫描已安装技能的 SKILL.md 文件，提取 name、description、location 等元数据，生成符合 Anthropic 规范的 `` XML 区块并写入目标文件。\n\n资料来源：[src/utils/agents-md.ts:45-70]()\n\n## 代码提交规范\n\n### 提交信息格式\n\n```\n<类型>: <简短描述>\n\n[可选的详细说明]\n```\n\n### 提交类型\n\n| 类型 | 用途 |\n|------|------|\n| `feat` | 新功能 |\n| `fix` | 错误修复 |\n| `docs` | 文档更新 |\n| `test` | 测试相关 |\n| `refactor` | 代码重构 |\n| `chore` | 构建或辅助工具变更 |\n\n### 提交前检查清单\n\n- [ ] 所有测试通过 `npm run test`\n- [ ] 代码符合 TypeScript 类型检查\n- [ ] 新功能包含相应的测试用例\n- [ ] 更新了相关文档（如有 API 变更）\n\n## 问题报告指南\n\n报告问题时，请确保包含以下信息：\n\n| 信息项 | 说明 |\n|--------|------|\n| 问题类型 | Bug 报告或功能请求 |\n| 复现步骤 | 详细的操作步骤 |\n| 版本信息 | `npx openskills --version` 输出 |\n| Node.js 版本 | `node --version` 输出 |\n| 预期行为 | 希望看到的正确行为 |\n| 实际行为 | 当前观察到的行为 |\n\n资料来源：[CONTRIBUTING.md:26-32]()\n\n## 许可协议\n\n通过向 OpenSkills 项目提交贡献，您同意您的贡献将按照 Apache 2.0 许可证授权。贡献者无需签署任何额外的贡献者许可协议。\n\n资料来源：[CONTRIBUTING.md:34]()\n\n## 技能开发指南\n\nOpenSkills 兼容 Anthropic 的 SKILL.md 格式。开发新技能时，需要遵循以下结构：\n\n```bash\nmy-skill/\n├── SKILL.md # 主技能文件（必需）\n├── references/ # 参考文档目录\n├── scripts/ # 可执行脚本目录\n└── assets/ # 静态资源目录\n```\n\n### SKILL.md 格式要求\n\n```yaml\n---\nname: skill-name # 必需：小写连字符格式\ndescription: 何时使用此技能 # 必需：1-2句话描述\n---\n```\n\n### 技能安装与测试\n\n```bash\n# 本地开发链接\ngit clone git@github.com:your-org/my-skills.git ~/dev/my-skills\nmkdir -p .claude/skills\nln -s ~/dev/my-skills/my-skill .claude/skills/my-skill\n\n# 测试技能\nnpx openskills read my-skill\n```\n\n资料来源：[CONTRIBUTING.md:11-17]()\n\n## 技术架构流程\n\n### 技能安装流程\n\n```mermaid\ngraph TD\n A[用户执行 install 命令] --> B{来源类型}\n B -->|GitHub| C[解析 org/repo 格式]\n B -->|本地路径| D[验证本地目录存在]\n B -->|SSH URL| E[使用系统 SSH 密钥克隆]\n \n C --> F[克隆远程仓库]\n D --> G[复制本地技能]\n E --> F\n \n F --> H[扫描仓库中的 SKILL.md]\n G --> H\n \n H --> I[写入元数据]\n I --> J[创建符号链接]\n J --> K[安装完成]\n \n H -->|多个技能| I\n```\n\n### 技能更新流程\n\n```mermaid\ngraph TD\n A[用户执行 update 命令] --> B{技能元数据类型}\n B -->|local| C[验证本地路径存在]\n B -->|git| D[克隆源仓库]\n \n C --> E[从本地路径复制更新]\n D --> F[从子路径提取技能]\n \n E --> G[更新技能文件]\n F --> G\n \n G --> H[更新元数据 installedAt]\n H --> I[更新完成]\n```\n\n更新流程会检查本地源路径是否存在、SKILL.md 文件是否完整，然后执行文件同步并更新元数据中的安装时间戳。\n\n资料来源：[src/commands/update.ts:1-30]()\n\n## 获取帮助\n\n| 渠道 | 用途 |\n|------|------|\n| GitHub Issues | 功能请求、Bug 报告 |\n| GitHub Discussions | 贡献相关问题、架构讨论 |\n| Anthropic 文档 | SKILL.md 规范参考 |\n\n资料来源：[CONTRIBUTING.md:33-37]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：numman-ali/openskills\n\n摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：[BUG] `--universal` installs to `.agent/` not `.agents/`。\n\n## 1. 安装坑 · 来源证据：[BUG] `--universal` installs to `.agent/` not `.agents/`\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] `--universal` installs to `.agent/` not `.agents/`\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c384eba59a4f4177ace0a344b94400dc | https://github.com/numman-ali/openskills/issues/84 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[FEATURE] add cli option --skills=name1,name2 to only install selected skill from github repo non-interactivelly\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] add cli option --skills=name1,name2 to only install selected skill from github repo non-interactivelly\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ec834575446429c96f39db392b81751 | https://github.com/numman-ali/openskills/issues/53 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：[Feature]: Read skill.json from source repos for install and sync\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Read skill.json from source repos for install and sync\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8752343cfb2d4231a5eb42f242806a31 | https://github.com/numman-ali/openskills/issues/81 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：[BUG] Update command doesn't update all paths\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Update command doesn't update all paths\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8f8a414bbe634c229bf200f45014fc57 | https://github.com/numman-ali/openskills/issues/75 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：[BUG] Clone failed\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Clone failed\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_59fb2f76bd674cf2bba0efb5a57843bd | https://github.com/numman-ali/openskills/issues/85 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[BUG] EEXIST when overwriting an existing skill during installation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] EEXIST when overwriting an existing skill during installation\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ac382f17e8a744b58f7d0860617a2f19 | https://github.com/numman-ali/openskills/issues/73 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v1.2.0 - Universal Skills Support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.0 - Universal Skills Support\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_31f11650e29a4e7c9fbd4ff026d577d0 | https://github.com/numman-ali/openskills/releases/tag/v1.2.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v1.2.1 - Documentation Fixes\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.1 - Documentation Fixes\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bb36323b2acd470bb0382644fddfde5f | https://github.com/numman-ali/openskills/releases/tag/v1.2.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v1.5.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.5.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7fab452932ab47e18a1d915b327b22d2 | https://github.com/numman-ali/openskills/releases/tag/v1.5.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1083829346 | https://github.com/numman-ali/openskills | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1083829346 | https://github.com/numman-ali/openskills | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1083829346 | https://github.com/numman-ali/openskills | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1083829346 | https://github.com/numman-ali/openskills | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：[BUG] Path Resolution & Sandbox Access Conflict for Global OpenSkills on macOS\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Path Resolution & Sandbox Access Conflict for Global OpenSkills on macOS\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_92230b03d1ec434694ad8d2e5ee6441f | https://github.com/numman-ali/openskills/issues/87 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：[FEATURE] Explicit local-first precedence for synced skills\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Explicit local-first precedence for synced skills\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6a14016c475349378139fe37f465945b | https://github.com/numman-ali/openskills/issues/86 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：[FEATURE] Remote path that isn't a git repo\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Remote path that isn't a git repo\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_24fd46302500414a80566af028da3bb8 | https://github.com/numman-ali/openskills/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v1.1.0 - Comprehensive Documentation & Location Tag Fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 - Comprehensive Documentation & Location Tag Fix\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_315e89cc6fa641ceaf797b3c8a4a6f6e | https://github.com/numman-ali/openskills/releases/tag/v1.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v1.3.0 - CI/CD, Local Development & Security\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.3.0 - CI/CD, Local Development & Security\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d2fade5f1d8e4e3080b89bdeb9d7bc3f | https://github.com/numman-ali/openskills/releases/tag/v1.3.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v1.3.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.3.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_aa1710ddf10a42069b3e12cf5b4eb65a | https://github.com/numman-ali/openskills/releases/tag/v1.3.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1083829346 | https://github.com/numman-ali/openskills | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1083829346 | https://github.com/numman-ali/openskills | release_recency=unknown\n\n\n",
"markdown_key": "openskills",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1083829346",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/numman-ali/openskills"
},
{
"evidence_id": "art_25f170b6500d4d4ba11b2ea12edc9f7b",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/numman-ali/openskills#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "openskills 说明书",
"toc": [
"https://github.com/numman-ali/openskills 项目说明书",
"目录",
"项目概述",
"项目定位与核心价值",
"技术架构",
"CLI 命令体系",
"SKILL.md 格式规范",
"渐进式披露机制",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "57d933a4f0d5c8659bd8b285f50fb9554360f0b3",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"examples/my-first-skill/SKILL.md",
"examples/my-first-skill/references/skill-format.md",
"src/types.ts",
"src/cli.ts",
"src/utils/skill-metadata.ts",
"src/utils/skill-names.ts",
"src/utils/yaml.ts",
"src/utils/marketplace-skills.ts",
"src/utils/dirs.ts",
"src/utils/agents-md.ts",
"src/utils/skills.ts",
"src/commands/read.ts",
"src/commands/update.ts",
"src/commands/remove.ts",
"src/commands/list.ts",
"src/commands/manage.ts",
"src/commands/sync.ts",
"src/commands/install.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# openskills - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 openskills 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`examples/my-first-skill/SKILL.md` Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`examples/my-first-skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npx openskills install anthropics/skills` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0011` supported 0.86\n- `npx openskills sync` 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0013` supported 0.86\n- `npx openskills read ` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npx openskills install your-org/your-skills` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npx openskills install ./local-skills/my-skill` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `npx openskills install git@github.com:your-org/private-skills.git` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `npx openskills install anthropics/skills --universal` 证据：`README.md` Claim：`clm_0011` supported 0.86\n- `npx openskills install [options] # Install from GitHub, local path, or private repo` 证据：`README.md` Claim：`clm_0012` supported 0.86\n- `npx openskills sync [-y] [-o ] # Update AGENTS.md (or custom output)` 证据：`README.md` Claim：`clm_0013` supported 0.86\n- `npx openskills list # Show installed skills` 证据：`README.md` Claim：`clm_0014` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`examples/my-first-skill/SKILL.md` Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`examples/my-first-skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0011` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`, `CLAUDE.md`, `examples/my-first-skill/SKILL.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`, `CLAUDE.md`, `examples/my-first-skill/SKILL.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0024` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0025` supported 0.86\n- **源文档冲突：agent_count**：项目文档中存在数量表述不一致，AI Context Pack 必须提示用户不要把单一数字当作已验证事实。 处理方式：在 Human Manual 和 AI Context Pack 中共同标记为待核实，而不是强行选择一个数字。 证据：`.github/maintainer/notes/issues/000/ISSUE-28.md`, `.github/maintainer/notes/issues/000/ISSUE-28.md` Claim：`clm_0026` supported 0.86, `clm_0035` contradicted 0.20\n- **源文件冲突 agent_count**：发现多个值 `50, 100`，应在真实使用前核实。\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`examples/my-first-skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：93\n- 重要文件覆盖：40/93\n- 证据索引条目：68\n- 角色 / Skill 条目：1\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 openskills 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 openskills 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 openskills 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **my-first-skill**（skill）：Example skill demonstrating Anthropic SKILL.md format. Load when learning to create skills or testing the OpenSkills loader. 激活提示：当用户任务与“my-first-skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`examples/my-first-skill/SKILL.md`\n\n## 证据索引\n\n- 共索引 68 条证据。\n\n- **AGENTS**（documentation）：When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge. 证据：`AGENTS.md`\n- **Claude**（documentation）：@AGENTS.md 证据：`CLAUDE.md`\n- **✨ What Is OpenSkills?**（documentation）：Universal skills loader for AI coding agents 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"openskills\", \"version\": \"1.5.0\", \"description\": \"Universal skills loader for AI coding agents - install and load Anthropic SKILL.md format skills in any agent\", \"type\": \"module\", \"main\": \"./dist/cli.js\", \"bin\": { \"openskills\": \"dist/cli.js\" }, \"files\": \"dist\", \"examples\" , \"scripts\": { \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"test\": \"vitest run\", \"test:watch\": \"vitest\", \"test:coverage\": \"vitest run --coverage\", \"typecheck\": \"tsc --noEmit\", \"prepublishOnly\": \"npm run typecheck && npm run build && npm test\" }, \"keywords\": \"anthropic\", \"claude\", \"claude-code\", \"skills\", \"ai\", \"agents\", \"coding-agent\", \"cursor\", \"windsurf\", \"aider\", \"progressive-disclosure\", \"automation\", \"developer-… 证据：`package.json`\n- **Contributing to OpenSkills**（documentation）：Thank you for your interest in contributing to OpenSkills! 证据：`CONTRIBUTING.md`\n- **My First Skill**（skill_instruction）：This is an example skill demonstrating the Anthropic SKILL.md format. 证据：`examples/my-first-skill/SKILL.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Changelog**（documentation）：All notable changes to this project will be documented in this file. 证据：`CHANGELOG.md`\n- **Security Policy**（documentation）：We provide security updates for the latest version. 证据：`SECURITY.md`\n- **Bug Report**（documentation）：Bug Description A clear and concise description of the bug. 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Feature Request**（documentation）：Feature Description A clear description of the feature you'd like to see. 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **Project Context**（documentation）：Vision OpenSkills is a universal skills loader for AI coding agents. It enables installing and managing Anthropic SKILL.md format skills across any AI agent Claude Code, Cursor, Windsurf, Gemini, etc. , making it easy to extend agent capabilities with reusable skill definitions. 证据：`.github/maintainer/context.md`\n- **Contributor Notes**（documentation）：@username - First seen: 2025-12-15 - Contributions: 3 PRs 2 implemented , 5 issues - Strengths: Good tests, clear descriptions - Notes: Offered to help maintain. Responsive. 证据：`.github/maintainer/contributors.md`\n- **Decision Log**（documentation）：RELEASE:1.5.0 Shipped update command + source tracking Date: 2026-01-17 Decision: Release and publish 1.5.0 Reasoning: Adds openskills update , source metadata tracking, multi-skill reads, and improved update UX. 证据：`.github/maintainer/decisions.md`\n- **Intent**（documentation）：Intent - TODO: Summarize the reporter intent and underlying need. 证据：`.github/maintainer/notes/issues/000/ISSUE-13.md`\n- **Intent**（documentation）：Intent Prevent AGENTS usage text from triggering a bash call in Gemini CLI. 证据：`.github/maintainer/notes/issues/000/ISSUE-16.md`\n- **Intent**（documentation）：Intent - TODO: Summarize the reporter intent and underlying need. 证据：`.github/maintainer/notes/issues/000/ISSUE-17.md`\n- **Intent**（documentation）：Intent - TODO: Summarize the reporter intent and underlying need. 证据：`.github/maintainer/notes/issues/000/ISSUE-19.md`\n- **Intent**（documentation）：Intent User installed openskills@1.3.0 but CLI reports 1.2.1 and installs fail on Windows with “Security error: Installation path outside target directory.” They need correct version reporting and Windows installs to work. 证据：`.github/maintainer/notes/issues/000/ISSUE-20.md`\n- **Intent**（documentation）：Intent - TODO: Summarize the reporter intent and underlying need. 证据：`.github/maintainer/notes/issues/000/ISSUE-24.md`\n- **Intent**（documentation）：Intent Reporter cannot install ANY skills on Windows. Every skill installation fails with \"Security error: Installation path outside target directory\". This is a critical bug blocking Windows platform entirely. 证据：`.github/maintainer/notes/issues/000/ISSUE-28.md`\n- **Intent**（documentation）：Intent - TODO: Summarize the reporter intent and underlying need. 证据：`.github/maintainer/notes/issues/000/ISSUE-29.md`\n- **Intent**（documentation）：Intent - TODO: Summarize the reporter intent and underlying need. 证据：`.github/maintainer/notes/issues/000/ISSUE-32.md`\n- **Intent**（documentation）：Intent - TODO: Summarize the reporter intent and underlying need. 证据：`.github/maintainer/notes/issues/000/ISSUE-34.md`\n- **Intent**（documentation）：Intent - TODO: Summarize the reporter intent and underlying need. 证据：`.github/maintainer/notes/issues/000/ISSUE-35.md`\n- **Intent**（documentation）：Intent - TODO: Summarize the reporter intent and underlying need. 证据：`.github/maintainer/notes/issues/000/ISSUE-41.md`\n- **Intent**（documentation）：Intent User installed openskills@1.3.0 but openskills --version still prints 1.2.1 . They want the CLI to report the actual package version and the build/publish process corrected. 证据：`.github/maintainer/notes/issues/000/ISSUE-42.md`\n- **Intent**（documentation）：Intent - TODO: Summarize the reporter intent and underlying need. 证据：`.github/maintainer/notes/issues/000/ISSUE-43.md`\n- **Intent**（documentation）：Intent - TODO: Summarize the reporter intent and underlying need. 证据：`.github/maintainer/notes/issues/000/ISSUE-47.md`\n- **Intent**（documentation）：Intent - TODO: Summarize the reporter intent and underlying need. 证据：`.github/maintainer/notes/issues/000/ISSUE-48.md`\n- **Intent**（documentation）：Intent - TODO: Summarize the reporter intent and underlying need. 证据：`.github/maintainer/notes/issues/000/ISSUE-50.md`\n- **Intent**（documentation）：Intent User tried installing a repo with a root-level SKILL.md and got “No SKILL.md files found in repository.” They need installs to work when a repo is a single skill at the root. 证据：`.github/maintainer/notes/issues/000/ISSUE-51.md`\n- **Intent**（documentation）：Intent Enable fully non-interactive installs where --yes also accepts overwrite prompts. 证据：`.github/maintainer/notes/issues/000/ISSUE-6.md`\n- **Intent**（documentation）：Intent Provide a clear workflow for updating skills installed from upstream git repos. 证据：`.github/maintainer/notes/issues/000/ISSUE-9.md`\n- **Intent**（documentation）：Intent - TODO: Summarize what the PR tries to solve and how. 证据：`.github/maintainer/notes/prs/000/PR-18.md`\n- **Intent**（documentation）：Intent Clarify that installs are project-local by default so non‑Claude users don’t assume global install behavior. 证据：`.github/maintainer/notes/prs/000/PR-23.md`\n- **Intent**（documentation）：Intent Add Nix flake support for reproducible builds and dev shells nix build , nix run , nix develop . 证据：`.github/maintainer/notes/prs/000/PR-25.md`\n- **Intent**（documentation）：Intent Replace string-based path checks with path.relative for cross-platform safety and add extensive test coverage. 证据：`.github/maintainer/notes/prs/000/PR-26.md`\n- **Intent**（documentation）：Intent Bump the CLI version string to 1.3.0. 证据：`.github/maintainer/notes/prs/000/PR-27.md`\n- **Intent**（documentation）：Intent Improve UX during git clone by using async spawn so the spinner animates and swap ora for nanospinner . Also claims to fix a JSON import warning. 证据：`.github/maintainer/notes/prs/000/PR-30.md`\n- **Intent**（documentation）：Intent Add a --symlink flag to install local skills by creating symlinks instead of copying, enabling live updates from a dev repo. 证据：`.github/maintainer/notes/prs/000/PR-31.md`\n- **Intent**（documentation）：Intent Fix Windows install failures by replacing hardcoded / with path.relative -based validation, and fix CLI version output by reading from package.json . 证据：`.github/maintainer/notes/prs/000/PR-37.md`\n- **Intent**（documentation）：Intent Fix Windows path security check by using path.sep instead of hardcoded / . The PR correctly identifies the root cause and provides a clean, minimal fix. 证据：`.github/maintainer/notes/prs/000/PR-38.md`\n- **Intent**（documentation）：Intent Prevent accidental permanent deletions by moving skills to the system trash/recycle bin by default. Adds a --force flag for permanent deletes and introduces a trash helper. 证据：`.github/maintainer/notes/prs/000/PR-39.md`\n- **Intent**（documentation）：Intent - TODO: Summarize what the PR tries to solve and how. 证据：`.github/maintainer/notes/prs/000/PR-40.md`\n- **Intent**（documentation）：Intent Add a line to AGENTS.md usage instructions telling users to install OpenSkills if it’s missing. This is a documentation nudge to help new developers in repos where AGENTS.md already exists. 证据：`.github/maintainer/notes/prs/000/PR-49.md`\n- **Observed Patterns**（documentation）：Windows Path Handling - First seen: 2025-12-15 - Frequency: 8 duplicate reports - Root cause: Hardcoded / instead of path.sep - Resolution: Fixed in v1.3.1 - Prevention: Added Windows CI 证据：`.github/maintainer/patterns.md`\n- **Release Checklist**（documentation）：Use this when shipping a new OpenSkills version so we do not repeat the same guidance every time. 证据：`.github/maintainer/release-checklist.md`\n- **Run Ledger**（documentation）：Date Report Path Summary ------ ------------- --------- 证据：`.github/maintainer/runs.md`\n- **Standing Rules**（documentation）：Condition Days Action ----------- ------ -------- Issue waiting on reporter 30 Comment asking for update Issue waiting on reporter 60 Close as stale PR waiting on author 30 Close as stale 证据：`.github/maintainer/standing-rules.md`\n- **Agent Briefs**（documentation）：Generated: 2026-01-17 Repository: numman-ali/openskills 证据：`.github/maintainer/work/agent-briefs.md`\n- **Agent Prompts**（documentation）：Use this file to draft executable prompts for each brief. 证据：`.github/maintainer/work/agent-prompts.md`\n- **Opportunity Backlog**（documentation）：- Add a short FAQ/troubleshooting section install modes, AGENTS.md, “skill not found” . - Add a “default install is project-local” clarification in README if still ambiguous . - Consider a brief guide for non-Claude agents Cursor/Windsurf/Aider/Codex . 证据：`.github/maintainer/work/opportunities.md`\n- **Maintainer Queue**（documentation）：- Windows install path validation issues 28, 34, 43, 48, 17, 29 - CLI version mismatch 20, 42 - Root SKILL.md install failure 51 证据：`.github/maintainer/work/queue.md`\n- **SKILL.md Format Reference**（documentation）：Every SKILL.md must start with YAML frontmatter: 证据：`examples/my-first-skill/references/skill-format.md`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"ESNext\", \"lib\": \"ES2022\" , \"moduleResolution\": \"node\", \"resolveJsonModule\": true, \"allowSyntheticDefaultImports\": true, \"esModuleInterop\": true, \"strict\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true, \"outDir\": \"./dist\", \"rootDir\": \"./src\" }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\", \"tests\" } 证据：`tsconfig.json`\n- **Config**（structured_config）：{ \"schemaVersion\": 1, \"reportsDir\": \"reports\", \"stateFile\": \".github/maintainer/state.json\", \"noMergeExternalPRs\": true, \"semantics\": { \"intent\": { \"bug\": \"bug\", \"crash\", \"error\", \"exception\", \"fails\", \"failing\", \"broken\", \"regression\" , \"feature\": \"feature\", \"enhancement\", \"feature request\", \"would be nice\", \"add support\", \"request\" , \"question\": \"how do i\", \"how can i\", \"is it possible\", \"what does\", \"question\" , \"support\": \"help\", \"support\", \"troubleshoot\", \"configure\", \"configuration\", \"setup\", \"install\" , \"meta\": \"roadmap\", \"governance\", \"maintainer\", \"community\", \"discussion\" }, \"needsInfo\": { \"repro\": \"steps to reproduce\", \"repro steps\", \"reproduction\" , \"expected\": \"expected behavio… 证据：`.github/maintainer/config.json`\n- **Graph**（structured_config）：{ \"generatedAt\": \"2026-01-17T19:26:09.772Z\", \"nodes\": { \"id\": \"issue:35\", \"type\": \"issue\", \"title\": \" I NEED YOU! Request for a Core Contributor!\", \"priorityScore\": 9, \"actionability\": \"ready\" }, { \"id\": \"issue:50\", \"type\": \"issue\", \"title\": \"now i have skills and model api ,but i can' use claude ,should i write workflow to let the model use skill or how can i create a project like claude to use the skills\", \"priorityScore\": 7, \"actionability\": \"ready\" }, { \"id\": \"issue:47\", \"type\": \"issue\", \"title\": \" FEATURE \", \"priorityScore\": 5, \"actionability\": \"ready\" }, { \"id\": \"issue:41\", \"type\": \"issue\", \"title\": \" FEATURE support multiple skill reads at once OR explain that they should be read spa… 证据：`.github/maintainer/index/graph.json`\n- **Items**（structured_config）：{ \"generatedAt\": \"2026-01-17T19:26:09.772Z\", \"count\": 32, \"items\": { \"id\": 6, \"type\": \"issue\", \"title\": \"\", \"actionability\": \"done\", \"priorityScore\": 17, \"sentimentScore\": 0, \"needsInfoScore\": 0, \"needsInfoSignals\": , \"linkedIssues\": , \"labels\": \"enhancement\" , \"notePath\": \".github/maintainer/notes/issues/000/ISSUE-6.md\", \"lastSeenAt\": \"2026-01-17T19:10:52.058Z\" }, { \"id\": 9, \"type\": \"issue\", \"title\": \"\", \"actionability\": \"done\", \"priorityScore\": 17, \"sentimentScore\": 0, \"needsInfoScore\": 0, \"needsInfoSignals\": , \"linkedIssues\": , \"labels\": \"enhancement\" , \"notePath\": \".github/maintainer/notes/issues/000/ISSUE-9.md\", \"lastSeenAt\": \"2026-01-17T19:25:46Z\" }, { \"id\": 13, \"type\": \"issue\", \"titl… 证据：`.github/maintainer/index/items.json`\n- **Semantics.Generated**（structured_config）：{ \"schemaVersion\": 1, \"generatedAt\": \"2026-01-17T13:12:54.700Z\", \"sources\": \"/Users/numman/Repos/openskills/.github/ISSUE TEMPLATE/bug report.md\", \"/Users/numman/Repos/openskills/.github/ISSUE TEMPLATE/config.yml\", \"/Users/numman/Repos/openskills/.github/ISSUE TEMPLATE/feature request.md\", \"/Users/numman/Repos/openskills/CONTRIBUTING.md\" , \"overrides\": { \"semantics\": { \"intent\": { \"bug\": \"bug description\" , \"feature\": \"feature description\", \"feature requests\" , \"question\": \"questions?\" , \"support\": , \"meta\": \"contributing: open a discussion thread\" }, \"needsInfo\": { \"repro\": \"steps to reproduce\", \"provide clear reproduction steps\" , \"expected\": \"expected behavior\" , \"actual\": \"actual behavi… 证据：`.github/maintainer/semantics.generated.json`\n- 其余 8 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`AGENTS.md`, `CLAUDE.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`AGENTS.md`, `CLAUDE.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, package.json, AGENTS.md\n- **快速开始**：importance `high`\n - source_paths: README.md, src/cli.ts, examples/my-first-skill/SKILL.md\n- **系统架构**：importance `high`\n - source_paths: src/cli.ts, src/types.ts, src/utils/skills.ts, src/utils/agents-md.ts\n- **CLI命令参考**：importance `high`\n - source_paths: src/cli.ts, src/commands/install.ts, src/commands/list.ts, src/commands/read.ts, src/commands/manage.ts\n- **install命令详解**：importance `high`\n - source_paths: src/commands/install.ts, src/utils/skill-metadata.ts, src/utils/marketplace-skills.ts, src/utils/yaml.ts\n- **sync命令详解**：importance `high`\n - source_paths: src/commands/sync.ts, src/utils/agents-md.ts\n- **update命令详解**：importance `medium`\n - source_paths: src/commands/update.ts, src/utils/skill-metadata.ts, src/utils/skills.ts\n- **SKILL.md格式规范**：importance `high`\n - source_paths: examples/my-first-skill/SKILL.md, examples/my-first-skill/references/skill-format.md, src/utils/yaml.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `57d933a4f0d5c8659bd8b285f50fb9554360f0b3`\n- inspected_files: `package.json`, `README.md`, `examples/my-first-skill/SKILL.md`, `examples/my-first-skill/references/skill-format.md`, `src/types.ts`, `src/cli.ts`, `src/utils/skill-metadata.ts`, `src/utils/skill-names.ts`, `src/utils/yaml.ts`, `src/utils/marketplace-skills.ts`, `src/utils/dirs.ts`, `src/utils/agents-md.ts`, `src/utils/skills.ts`, `src/commands/read.ts`, `src/commands/update.ts`, `src/commands/remove.ts`, `src/commands/list.ts`, `src/commands/manage.ts`, `src/commands/sync.ts`, `src/commands/install.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[BUG] `--universal` installs to `.agent/` not `.agents/`\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] `--universal` installs to `.agent/` not `.agents/`\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_c384eba59a4f4177ace0a344b94400dc | https://github.com/numman-ali/openskills/issues/84 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：[FEATURE] add cli option --skills=name1,name2 to only install selected skill from github repo non-interactivelly\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] add cli option --skills=name1,name2 to only install selected skill from github repo non-interactivelly\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3ec834575446429c96f39db392b81751 | https://github.com/numman-ali/openskills/issues/53 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：[Feature]: Read skill.json from source repos for install and sync\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Read skill.json from source repos for install and sync\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_8752343cfb2d4231a5eb42f242806a31 | https://github.com/numman-ali/openskills/issues/81 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：[BUG] Update command doesn't update all paths\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Update command doesn't update all paths\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_8f8a414bbe634c229bf200f45014fc57 | https://github.com/numman-ali/openskills/issues/75 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：[BUG] Clone failed\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Clone failed\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_59fb2f76bd674cf2bba0efb5a57843bd | https://github.com/numman-ali/openskills/issues/85 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：[BUG] EEXIST when overwriting an existing skill during installation\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] EEXIST when overwriting an existing skill during installation\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_ac382f17e8a744b58f7d0860617a2f19 | https://github.com/numman-ali/openskills/issues/73 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v1.2.0 - Universal Skills Support\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.0 - Universal Skills Support\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_31f11650e29a4e7c9fbd4ff026d577d0 | https://github.com/numman-ali/openskills/releases/tag/v1.2.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：v1.2.1 - Documentation Fixes\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.1 - Documentation Fixes\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_bb36323b2acd470bb0382644fddfde5f | https://github.com/numman-ali/openskills/releases/tag/v1.2.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：v1.5.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.5.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_7fab452932ab47e18a1d915b327b22d2 | https://github.com/numman-ali/openskills/releases/tag/v1.5.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1083829346 | https://github.com/numman-ali/openskills | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：numman-ali/openskills\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：[BUG] `--universal` installs to `.agent/` not `.agents/`（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[FEATURE] add cli option --skills=name1,name2 to only install selected skill from github repo non-interactivelly（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Feature]: Read skill.json from source repos for install and sync（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[BUG] Update command doesn't update all paths（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[BUG] Clone failed（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/numman-ali/openskills 项目说明书\n\n生成时间：2026-05-16 16:02:37 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [快速开始](#page-quick-start)\n- [系统架构](#page-architecture)\n- [CLI命令参考](#page-cli-commands)\n- [install命令详解](#page-install-command)\n- [sync命令详解](#page-sync-command)\n- [update命令详解](#page-update-command)\n- [SKILL.md格式规范](#page-skill-md-format)\n- [数据存储与管理](#page-data-storage)\n- [贡献指南](#page-contributing)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[快速开始](#page-quick-start), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/numman-ali/openskills/blob/main/README.md)\n- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)\n- [examples/my-first-skill/SKILL.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/SKILL.md)\n- [examples/my-first-skill/references/skill-format.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/references/skill-format.md)\n- [CHANGELOG.md](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)\n- [CONTRIBUTING.md](https://github.com/numman-ali/openskills/blob/main/CONTRIBUTING.md)\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)\n \n\n# 项目概述\n\nOpenSkills 是一个开源的 Node.js CLI 工具，旨在为 AI 编码代理提供标准化的技能（Skills）管理和分发机制。该项目完全兼容 Anthropic 的 SKILL.md 格式规范，使技能可以在不同的 AI 代理平台之间无缝移植和使用。\n\n## 项目定位与核心价值\n\nOpenSkills 的核心定位是**通用技能加载器**。在 AI 代理的工作场景中，技能是静态的指令和资源的集合，与 MCP（Model Context Protocol）的动态工具调用形成互补。项目采用 SKILL.md 文件作为技能的唯一载体，无需运行服务器，使得技能具备天然的跨平台兼容性。\n\n**核心价值主张：**\n\n- **Exact Claude Code 兼容性** — 采用相同的提示格式、市场和文件夹结构 资料来源：[README.md]()\n- **通用性** — 支持 Claude Code、Cursor、Windsurf、Aider、Codex 等多种代理 资料来源：[README.md]()\n- **渐进式披露** — 按需加载技能，保持代理上下文的精简 资料来源：[README.md]()\n- **仓库友好** — 技能与项目代码一同版本化管理 资料来源：[README.md]()\n- **私有化友好** — 支持从本地路径或私有 Git 仓库安装技能 资料来源：[README.md]()\n\n## 技术架构\n\n### 技术栈\n\nOpenSkills 基于现代 Node.js 生态构建，对运行环境有明确要求：\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Node.js | >= 20.6.0 | 项目引擎要求 |\n| Git | 任意版本 | 用于克隆仓库 |\n| TypeScript | 5.9.3 | 开发语言 |\n| Vitest | 4.0.3 | 测试框架 |\n\n**核心依赖库：**\n\n| 库名 | 版本 | 用途 |\n|------|------|------|\n| commander | ^12.1.0 | CLI 命令框架 |\n| chalk | ^5.6.2 | 终端着色 |\n| ora | ^9.0.0 | 加载动画 |\n| @inquirer/prompts | ^7.9.0 | 交互式提示 |\n\n资料来源：[package.json]()\n\n### 项目结构\n\n```\nopenskills/\n├── src/\n│ ├── cli.ts # CLI 主入口，定义命令路由\n│ ├── commands/ # 各命令实现\n│ │ ├── update.ts # 技能更新逻辑\n│ │ ├── install.ts # 技能安装逻辑\n│ │ └── ...\n│ ├── utils/ # 共享工具\n│ │ ├── agents-md.ts # AGENTS.md 生成\n│ │ └── ...\n│ └── types.ts # TypeScript 接口定义\n├── tests/ # 测试套件（88+ 测试用例）\n├── examples/\n│ └── my-first-skill/ # 示例技能\n└── package.json\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[用户执行 CLI 命令] --> B{npx openskills}\n B --> C[install 安装技能]\n B --> D[sync 同步 AGENTS.md]\n B --> E[list 列出技能]\n B --> F[read 读取技能内容]\n B --> G[update 更新技能]\n B --> H[manage/remove 管理技能]\n \n C --> C1[解析安装源]\n C1 --> C2{GitHub 仓库?}\n C2 -->|是| C3[git clone 克隆仓库]\n C2 -->|否| C4{本地路径?}\n C4 -->|是| C5[使用本地目录]\n C4 -->|否| C6[私有 Git 仓库]\n C3 --> C7[复制到技能目录]\n C5 --> C7\n C6 --> C7\n C7 --> C8[写入元数据]\n \n F --> F1[定位 SKILL.md]\n F1 --> F2[输出技能内容]\n F2 --> F3[提供基础目录]\n```\n\n## CLI 命令体系\n\n### 命令总览\n\n| 命令 | 描述 | 主要选项 |\n|------|------|----------|\n| `install ` | 从 GitHub/Git URL 安装技能 | `--global`, `--universal`, `--yes` |\n| `sync` | 更新 AGENTS.md | `--yes`, `--output ` |\n| `list` | 列出已安装技能 | - |\n| `read ` | 读取技能内容到 stdout | - |\n| `update [skill-names]` | 更新已安装技能 | - |\n| `manage` | 交互式管理技能 | - |\n| `remove ` | 移除指定技能 | - |\n\n资料来源：[src/cli.ts]()\n\n### 安装来源类型\n\nOpenSkills 支持多种安装来源，覆盖了典型的使用场景：\n\n| 来源类型 | 示例 | 说明 |\n|----------|------|------|\n| Anthropic 市场 | `anthropics/skills` | 从 Anthropic 官方技能库安装 |\n| GitHub 仓库 | `your-org/your-skills` | 从任意 GitHub 仓库安装 |\n| 本地路径 | `./local-skills/my-skill` | 从本地目录安装 |\n| 私有仓库 | `git@github.com:org/private-skills.git` | 通过 SSH 安装私有仓库 |\n\n资料来源：[README.md]()\n\n### 安装位置优先级\n\n```mermaid\ngraph LR\n A[安装请求] --> B{--universal 标志?}\n B -->|是| C[.agent/skills/]\n B -->|否| D{--global 标志?}\n D -->|是| E[~/.claude/skills/]\n D -->|否| F[项目本地]\n F --> G{存在 .claude/skills?}\n G -->|是| H[./.claude/skills/]\n G -->|否| I[./.agent/skills/]\n \n C --> J[优先级 1: 最高]\n H --> K[优先级 2]\n E --> L[优先级 3]\n I --> M[优先级 4]\n```\n\n优先级顺序：**`.agent/skills/` > `~/.agent/skills/` > `./.claude/skills/` > `~/.claude/skills/`**\n\n资料来源：[README.md]()\n\n## SKILL.md 格式规范\n\nSKILL.md 是 OpenSkills 技能的核心文件，采用 YAML frontmatter + Markdown 的混合格式。\n\n### 文件结构\n\n```\nskill-name/\n├── SKILL.md # 必需：技能主文件\n├── references/ # 可选：参考文档（按需加载）\n├── scripts/ # 可选：可执行脚本\n└── assets/ # 可选：资源文件（不加载到上下文）\n```\n\n资料来源：[examples/my-first-skill/references/skill-format.md]()\n\n### YAML Frontmatter\n\n每个 SKILL.md 必须以 YAML frontmatter 开头：\n\n```yaml\n---\nname: skill-name # 必需：连字符格式标识符\ndescription: When to use # 必需：1-2 句话描述，第三人称\n---\n```\n\n### 内容写作规范\n\n**推荐风格：**\n\n- 使用祈使句/不定式：\"To accomplish X, execute Y\"\n- 被动表述：\"This skill is loaded when Z\"\n- 引用资源：\"See references/guide.md for details\"\n\n**应避免：**\n\n- 第二人称：\"You should do X\"\n- 条件式：\"If you need Y\"\n\n资料来源：[examples/my-first-skill/references/skill-format.md]()\n\n### 文件大小指南\n\n| 部分 | 限制 | 说明 |\n|------|------|------|\n| SKILL.md | < 5,000 词 | 核心指令，保持精简 |\n| references/ | 无限制 | 按需选择性加载 |\n| scripts/ | 可执行 | 不计入上下文大小 |\n| assets/ | 任意 | 不加载到上下文 |\n\n资料来源：[examples/my-first-skill/references/skill-format.md]()\n\n## 渐进式披露机制\n\nOpenSkills 实现了三级渐进式加载策略，优化 AI 代理的上下文使用效率：\n\n```mermaid\ngraph TD\n A[技能元数据] --> B[SKILL.md 核心指令]\n A --> C[references/ 详细文档]\n A --> D[scripts/ 可执行脚本]\n \n B --> E[始终加载]\n C --> F[按需加载]\n D --> G[执行时调用]\n \n style A fill:#e1f5fe\n style B fill:#fff3e0\n style C fill:#f3e5f5\n style D fill:#e8f5e9\n```\n\n| 级别 | 内容 | 加载时机 | 说明 |\n|------|------|----------|------|\n| 1 | 元数据 | 始终在上下文中 | name + description |\n| 2 | SKILL.md | 技能被调用时 | 核心指令流程 |\n| 3 | references/ | 需要时 | 详细 API 文档、指南 |\n\n资料来源：[examples/my-first-skill/references/skill-format.md]()\n资料来源：[README.md]()\n\n## AGENTS.md 集成\n\n### 生成机制\n\n`sync` 命令负责生成包含技能信息的 AGENTS.md 文件段：\n\n```mermaid\ngraph LR\n A[扫描技能目录] --> B[读取元数据]\n B --> C[解析 SKILL.md]\n C --> D[生成 XML 块]\n D --> E[替换 AGENTS.md 内容]\n```\n\n生成的 XML 块结构：\n\n```xml\n\n\n...\n\n\n\npdf\nPDF manipulation toolkit...\nproject\n\n\n\n```\n\n资料来源：[src/utils/agents-md.ts]()\n\n### 输出配置\n\n`sync` 命令支持自定义输出路径：\n\n| 选项 | 说明 |\n|------|------|\n| `-o, --output ` | 指定输出文件路径（默认：AGENTS.md） |\n| `-y, --yes` | 跳过交互式选择，同步所有技能 |\n\n资料来源：[README.md]()\n\n## 技能更新机制\n\nupdate 命令支持三种来源类型的技能更新：\n\n```mermaid\ngraph TD\n A[update 命令] --> B{技能来源类型}\n \n B --> C[本地类型 local]\n B --> D[Git 类型 git]\n B --> E[未知类型]\n \n C --> C1{本地路径存在?}\n C1 -->|否| C2[跳过 - 源缺失]\n C1 -->|是| C3{SKILL.md 存在?}\n C3 -->|否| C4[跳过 - 文件缺失]\n C3 -->|是| C5[从本地目录复制]\n \n D --> D1{元数据包含 repoUrl?}\n D1 -->|否| D2[跳过 - 缺少仓库 URL]\n D1 -->|是| D3[git clone 临时目录]\n D3 --> D4[复制到技能目录]\n \n E --> E1[输出警告]\n \n style C5 fill:#c8e6c9\n style D4 fill:#c8e6c9\n```\n\n**更新流程要点：**\n\n1. **本地技能**：直接使用 `localPath` 指向的目录作为更新源\n2. **Git 技能**：克隆到临时目录后复制内容\n3. **缺少元数据**：跳过更新并输出警告\n\n资料来源：[src/commands/update.ts]()\n\n## 版本演进\n\n### 版本历史\n\n| 版本 | 发布日期 | 关键特性 |\n|------|----------|----------|\n| 1.0.0 | 2025-10-26 | 初始版本，核心 CLI 功能 |\n| 1.1.0 | 2025-10-27 | README 完善，位置标签修复 |\n| 1.2.0 | 2025-10-27 | 增加 `--universal` 标志，项目本地安装成为默认 |\n| 1.2.1 | 2025-10-27 | 文档清理，移除重复部分 |\n| 1.3.0 | 2025-11-12 | 本地路径安装、私有仓库支持、88+ 测试用例 |\n| 1.3.1-1.3.2 | 2026-01 | 符号链接支持、可配置输出路径 |\n| 1.4.0 | 2026-01-17 | README 澄清、项目本地默认说明 |\n| 1.5.0 | 2026-01-17 | 完整功能集发布 |\n\n资料来源：[CHANGELOG.md]()\n\n### 里程碑特性\n\n**v1.3.0 新增特性：**\n\n- 本地技能开发工作流支持\n- 损坏的符号链接自动跳过\n- 可配置输出路径（`--output` 标志）\n- 从本地目录安装技能\n- 私有 Git 仓库支持（SSH/HTTPS）\n- 完整的测试套件\n\n**v1.2.0 重大变更：**\n\n- 项目安装成为默认行为（之前是全局安装）\n- 技能默认安装到 `./.claude/skills/`\n\n资料来源：[CHANGELOG.md]()\n\n## 测试体系\n\nOpenSkills 采用 Vitest 作为测试框架，构建了多层次的测试覆盖：\n\n| 测试类型 | 测试文件数 | 说明 |\n|----------|------------|------|\n| 单元测试 | 多个 | 符号链接检测、YAML 解析 |\n| 集成测试 | 多个 | install、sync 命令 |\n| E2E 测试 | 多个 | 完整 CLI 工作流 |\n\n资料来源：[CHANGELOG.md]()\n\n**测试命令：**\n\n```bash\nnpm run test # 运行所有测试\nnpm run test:watch # 监听模式\nnpm run test:coverage # 覆盖率报告\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 与 MCP 的对比\n\n| 方面 | Skills | MCP |\n|------|--------|-----|\n| 实现方式 | 静态文件 | 动态服务器 |\n| 通信协议 | 无需网络 | 需要 MCP 服务器 |\n| 上下文加载 | 按需渐进式 | 实时查询 |\n| 跨代理兼容性 | 高 | 依赖 MCP 支持 |\n| 适用场景 | 固定指令集 | 动态工具调用 |\n\n**设计理念差异：**\n\n- **MCP 面向动态工具** — 适合需要实时交互、数据获取的场景\n- **Skills 面向静态指令** — 适合流程指导、领域知识、模板生成\n\n资料来源：[README.md]()\n\n## 快速开始\n\n### 安装方式\n\n```bash\n# 通过 npx 运行（无需安装）\nnpx openskills install anthropics/skills\nnpx openskills sync\n\n# 全局安装\nnpm install -g openskills\n```\n\n### 本地开发\n\n```bash\n# 克隆项目\ngit clone git@github.com:your-org/openskills.git\ncd openskills\n\n# 链接本地 CLI\nnpm link\n\n# 测试安装\nnpx openskills install anthropics/skills/pdf-editor --project\nnpx openskills sync\nnpx openskills read pdf-editor\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 系统要求\n\n| 要求 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | 20.6.0+ | 项目引擎限制 |\n| Git | 任意版本 | 用于仓库克隆操作 |\n\n资料来源：[README.md]()\n\n## 开源许可\n\nOpenSkills 采用 **Apache 2.0** 开源许可证。项目实现了 Anthropic 的 Agent Skills 规范规范，并在 README 中标注了 Attribution。\n\n资料来源：[README.md]()\n资料来源：[CONTRIBUTING.md]()\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [CLI命令参考](#page-cli-commands)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/numman-ali/openskills/blob/main/README.md)\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [examples/my-first-skill/SKILL.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/SKILL.md)\n- [examples/my-first-skill/references/skill-format.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/references/skill-format.md)\n- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n- [src/commands/sync.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/sync.ts)\n- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)\n- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)\n \n\n# 快速开始\n\n本页面介绍如何快速上手 OpenSkills，包括环境准备、技能安装、AGENTS.md 同步以及基本使用流程。\n\n## 系统要求\n\n| 要求 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | 20.6.0+ | 核心运行环境 |\n| Git | 任意版本 | 用于克隆技能仓库 |\n\n> 资料来源：[package.json:23-24]()\n\n## 安装 OpenSkills\n\nOpenSkills 无需全局安装，可直接通过 `npx` 运行。\n\n### 方式一：直接使用 npx（推荐）\n\n```bash\nnpx openskills --version\n```\n\n### 方式二：全局安装（可选）\n\n```bash\nnpm install -g openskills\n```\n\n> 资料来源：[README.md:1-5]()\n\n## 安装技能包\n\n### 从 Anthropic 市场安装\n\n```bash\nnpx openskills install anthropics/skills\n```\n\n> 资料来源：[README.md:12-15]()\n\n### 从 GitHub 仓库安装\n\n```bash\nnpx openskills install your-org/your-skills\n```\n\n> 资料来源：[README.md:17-19]()\n\n### 从本地路径安装\n\n```bash\nnpx openskills install ./local-skills/my-skill\n```\n\n支持绝对路径、相对路径和波浪号展开路径。\n\n> 资料来源：[CHANGELOG.md:25-30]()\n\n### 从私有仓库安装\n\n```bash\nnpx openskills install git@github.com:your-org/private-skills.git\n```\n\nOpenSkills 自动使用系统 SSH 密钥进行身份验证。\n\n> 资料来源：[CHANGELOG.md:31-35]()\n\n## 安装选项说明\n\n| 选项 | 说明 | 默认值 |\n|------|------|--------|\n| `--global` | 全局安装到 `~/.claude/skills` | 禁用 |\n| `--universal` | 安装到 `.agent/skills/` | 禁用 |\n| `-y, --yes` | 跳过交互确认，用于 CI/CD | 禁用 |\n| `-o, --output ` | 指定输出路径（sync 命令） | AGENTS.md |\n\n> 资料来源：[README.md:48-55]()\n\n### 安装位置优先级\n\n当使用 `--universal` 选项时，安装目录优先级如下：\n\n1. `./.agent/skills/`\n2. `~/.agent/skills/`\n3. `./.claude/skills/`\n4. `~/.claude/skills/`\n\n> 资料来源：[README.md:27-34]()\n\n## 同步技能到 AGENTS.md\n\n安装技能后，需要运行同步命令将技能信息写入 `AGENTS.md` 文件。\n\n### 基本同步流程\n\n```bash\nnpx openskills sync\n```\n\n同步过程会：\n1. 扫描已安装的技能目录\n2. 读取每个技能的 `SKILL.md` 元数据\n3. 生成 `` XML 块\n4. 更新目标 `AGENTS.md` 文件\n\n> 资料来源：[src/commands/sync.ts:1-15]()\n\n### 生成的文件格式\n\n同步后的 `AGENTS.md` 包含以下结构：\n\n```xml\n\n\n\nskill-name\n技能描述\nproject\n\n\n\n```\n\n> 资料来源：[src/utils/agents-md.ts:45-60]()\n\n## 使用技能\n\n### 查看已安装的技能\n\n```bash\nnpx openskills list\n```\n\n> 资料来源：[README.md:57-60]()\n\n### 读取技能内容\n\n```bash\nnpx openskills read \n```\n\n例如读取 PDF 技能：\n\n```bash\nnpx openskills read pdf\n```\n\n> 资料来源：[README.md:1-7]()\n\n### 加载多个技能\n\n```bash\nnpx openskills read skill-one,skill-two\n```\n\n> 资料来源：[README.md:1-7]()\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[安装 OpenSkills] --> B[安装技能包]\n B --> C[运行 sync 同步]\n C --> D[AGENTS.md 已更新]\n D --> E[AI 代理读取 AGENTS.md]\n E --> F[根据任务调用 npx openskills read]\n F --> G[技能内容加载到上下文]\n G --> H[执行技能指令]\n```\n\n## 常用命令速查表\n\n| 命令 | 功能 |\n|------|------|\n| `npx openskills install ` | 从指定源安装技能 |\n| `npx openskills sync` | 同步技能到 AGENTS.md |\n| `npx openskills list` | 列出已安装的技能 |\n| `npx openskills read ` | 读取技能内容 |\n| `npx openskills update [name]` | 更新已安装的技能 |\n| `npx openskills remove ` | 移除指定技能 |\n| `npx openskills manage` | 交互式管理技能 |\n\n> 资料来源：[README.md:57-60]()\n\n## 本地技能开发\n\n### 创建最小技能结构\n\n```\nmy-skill/\n└── SKILL.md\n```\n\n### 带资源的技能结构\n\n```\nmy-skill/\n├── SKILL.md\n├── references/\n├── scripts/\n└── assets/\n```\n\n> 资料来源：[README.md:85-95]()\n\n### 使用符号链接进行开发\n\n```bash\ngit clone git@github.com:your-org/my-skills.git ~/dev/my-skills\nmkdir -p .claude/skills\nln -s ~/dev/my-skills/my-skill .claude/skills/my-skill\n```\n\n> 资料来源：[README.md:103-108]()\n\n## SKILL.md 格式简介\n\n每个技能必须包含 YAML 前置内容和 Markdown 正文：\n\n```yaml\n---\nname: skill-name\ndescription: 技能描述（1-2句话，第三人称）\n---\n\n# 技能标题\n\n技能使用说明...\n```\n\n> 资料来源：[examples/my-first-skill/SKILL.md:1-15]()\n\n## 下一步\n\n- 查看 [SKILL.md 格式参考](examples/my-first-skill/references/skill-format.md) 了解完整格式规范\n- 查看 [CHANGELOG.md](../../CHANGELOG.md) 了解版本更新历史\n- 查看 [CONTRIBUTING.md](../../CONTRIBUTING.md) 了解贡献指南\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[CLI命令参考](#page-cli-commands), [SKILL.md格式规范](#page-skill-md-format)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [src/types.ts](https://github.com/numman-ali/openskills/blob/main/src/types.ts)\n- [src/utils/skills.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skills.ts)\n- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)\n- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)\n \n\n# 系统架构\n\n## 概述\n\nOpenSkills 是一个通用的 AI 代理技能管理系统，旨在为各种 AI 编码代理提供标准化的技能加载机制。该项目采用 TypeScript 开发，基于 Node.js 20.6+ 运行时运行，通过命令行界面（CLI）提供技能安装、同步和管理功能。\n\n核心设计理念是实现与 Anthropic Claude Code 技能格式的完全兼容，同时支持跨平台、多代理环境使用。技能以 `SKILL.md` 文件为核心，配合可选的 `references/`、`scripts/` 和 `assets/` 目录形成完整的技能包结构。\n\n## 架构分层\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ CLI 交互层 (cli.ts) │\n│ commander 解析命令 + chalk/ora 美化输出 │\n├─────────────────────────────────────────────────────────────┤\n│ 命令实现层 (commands/) │\n│ install │ read │ sync │ list │ update │ manage │ remove │\n├─────────────────────────────────────────────────────────────┤\n│ 工具函数层 (utils/) │\n│ agents-md.ts │ skills.ts │ yaml.ts │ symlink.ts │\n├─────────────────────────────────────────────────────────────┤\n│ 类型定义层 (types.ts) │\n│ Skill │ SkillSourceMetadata │ ... │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 核心依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| commander | ^12.1.0 | CLI 命令解析 |\n| chalk | ^5.6.2 | 终端输出着色 |\n| ora | ^9.0.0 | 加载动画 |\n| @inquirer/prompts | ^7.9.0 | 交互式提示 |\n| typescript | ^5.9.3 | 类型检查 |\n| vitest | ^4.0.3 | 单元测试 |\n\n资料来源：[package.json:1-25]()\n\n## 命令模块设计\n\n### 命令注册机制\n\nCLI 采用 Commander.js 框架进行命令注册和参数解析。主入口文件 `src/cli.ts` 负责定义所有可用命令：\n\n```typescript\nprogram\n .command('list')\n .description('List all installed skills')\n .action(listSkills);\n\nprogram\n .command('install ')\n .description('Install skill from GitHub or Git URL')\n .option('-g, --global', 'Install globally (default: project install)')\n .option('-u, --universal', 'Install to .agent/skills/')\n .option('-y, --yes', 'Skip interactive selection')\n .action(installSkill);\n```\n\n资料来源：[src/cli.ts:1-50]()\n\n### 支持的命令列表\n\n| 命令 | 功能 | 选项 |\n|------|------|------|\n| `install ` | 从 GitHub/本地路径安装技能 | `--global`, `--universal`, `--yes` |\n| `sync` | 同步技能到 AGENTS.md | `--yes`, `--output ` |\n| `list` | 列出已安装的技能 | - |\n| `read ` | 读取技能内容输出到终端 | - |\n| `update [skill-names]` | 更新已安装的技能 | - |\n| `manage` | 交互式管理（删除）技能 | - |\n| `remove ` | 移除指定技能 | - |\n\n## 数据模型\n\n### 技能元数据结构\n\n```typescript\ninterface Skill {\n name: string; // 技能标识符（连字符格式）\n description: string; // 技能描述（1-2句）\n location: 'project' | 'global' | 'plugin';\n}\n```\n\n资料来源：[src/types.ts]()\n\n### 技能来源元数据\n\n```typescript\ninterface SkillSourceMetadata {\n source: string; // 原始安装来源\n sourceType: 'git' | 'local';\n repoUrl?: string; // Git 仓库 URL\n subpath?: string; // 子目录路径\n localPath?: string; // 本地路径\n installedAt: string; // ISO 时间戳\n}\n```\n\n资料来源：[src/commands/install.ts:80-100]()\n\n## 技能安装流程\n\n```mermaid\ngraph TD\n A[install 命令] --> B{解析来源类型}\n B -->|GitHub URL| C[克隆仓库]\n B -->|本地路径| D[验证本地目录]\n B -->|SSH URL| E[使用 SSH 克隆]\n C --> F[扫描 SKILL.md 文件]\n D --> F\n E --> F\n F --> G{检查冲突}\n G -->|项目安装| H[复制到 .claude/skills/]\n G -->|全局安装| I[复制到 ~/.claude/skills/]\n G -->|通用安装| J[复制到 .agent/skills/]\n H --> K[写入元数据]\n I --> K\n J --> K\n K --> L[安装完成]\n```\n\n### 安装元数据构建逻辑\n\n```typescript\nfunction buildMetadataFromSource(\n sourceInfo: InstallSourceInfo,\n skillDir: string,\n repoDir: string\n): SkillSourceMetadata {\n if (sourceInfo.sourceType === 'local') {\n return buildLocalMetadata(sourceInfo, skillDir);\n }\n const subpath = relative(repoDir, skillDir);\n return buildGitMetadata(sourceInfo, normalizedSubpath);\n}\n```\n\n资料来源：[src/commands/install.ts:70-85]()\n\n## AGENTS.md 同步机制\n\n### XML 结构生成\n\n`agents-md.ts` 负责生成兼容 Claude Code 的技能列表 XML：\n\n```typescript\nexport function generateSkillsXml(skills: Skill[]): string {\n const skillTags = skills\n .map((s) => `\n${s.name}\n${s.description}\n${s.location}\n`)\n .join('\\n\\n');\n // 返回完整的 skills_system XML 块\n}\n```\n\n资料来源：[src/utils/agents-md.ts:60-80]()\n\n### AGENTS.md 模板结构\n\n```xml\n\n\n## Available Skills\n\n\n\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.\n- Invoke: `npx openskills read ` (run in your shell)\n- Only use skills listed in \n\n\n\n\n${skillTags}\n\n\n\n\n\n```\n\n资料来源：[src/utils/agents-md.ts:1-30]()\n\n### 内容替换策略\n\n```mermaid\ngraph LR\n A[读取 AGENTS.md] --> B{检测标记类型}\n B -->|XML 标记| C[使用正则替换 skills_system 块]\n B -->|HTML 注释| D[使用正则替换 TABLE 块]\n C --> E[写入更新后的内容]\n D --> E\n```\n\n替换逻辑支持两种标记格式以保证向后兼容：\n- XML 格式：`...`\n- HTML 注释格式：`...`\n\n资料来源：[src/utils/agents-md.ts:40-55]()\n\n## 技能更新机制\n\n### 更新流程\n\n```mermaid\ngraph TD\n A[update 命令] --> B[读取技能元数据]\n B --> C{判断来源类型}\n C -->|local| D[验证本地路径存在]\n C -->|git| E[克隆最新仓库]\n D -->|路径缺失| F[跳过并警告]\n D -->|路径有效| G[复制文件到安装目录]\n E --> G\n G --> H[更新 installedAt 时间戳]\n H --> I[更新完成]\n```\n\n### 本地源处理\n\n```typescript\nif (metadata.sourceType === 'local') {\n const localPath = metadata.localPath;\n if (!localPath || !existsSync(localPath)) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (local source missing)`));\n continue;\n }\n if (!existsSync(join(localPath, 'SKILL.md'))) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (SKILL.md missing)`));\n continue;\n }\n updateSkillFromDir(skill.path, localPath);\n}\n```\n\n资料来源：[src/commands/update.ts:1-30]()\n\n## 技能目录结构\n\n### 安装优先级\n\n系统支持多层级的技能安装目录，按优先级从高到低排列：\n\n| 优先级 | 目录 | 说明 |\n|--------|------|------|\n| 1 | `./.agent/skills/` | 通用安装（多代理环境） |\n| 2 | `~/.agent/skills/` | 用户级通用安装 |\n| 3 | `./.claude/skills/` | 项目本地安装 |\n| 4 | `~/.claude/skills/` | 全局安装 |\n\n安装时使用 `--universal` 标志会将技能安装到 `.agent/skills/`，适用于同时使用 Claude Code 和其他代理（如 Cursor、Windsurf、Aider）的场景。\n\n资料来源：[README.md]() 和 [src/cli.ts]()\n\n### 技能包标准结构\n\n```\nskill-name/\n├── SKILL.md # 必需：技能定义文件\n├── references/ # 可选：参考文档（API 文档、详细指南）\n├── scripts/ # 可选：可执行脚本（Python/Bash）\n└── assets/ # 可选：静态资源（模板、图片）\n```\n\n## 错误处理机制\n\n```typescript\n// 错误处理流程\nif (err.code === 'commander.unknownOption' || err.code === 'commander.invalidArgument') {\n // 参数错误：Commander 已显示错误信息\n process.exit(1);\n}\n// 其他错误\nprocess.exit(err.exitCode || 1);\n```\n\n资料来源：[src/cli.ts:10-20]()\n\n### 冲突检测\n\n安装前会检查目标路径是否已存在技能：\n\n```typescript\nasync function warnIfConflict(\n skillName: string, \n targetPath: string, \n isProject: boolean, \n skipPrompt = false\n): Promise {\n if (existsSync(targetPath)) {\n if (skipPrompt) {\n // 自动覆盖模式\n }\n // 交互式确认模式\n }\n return true;\n}\n```\n\n资料来源：[src/commands/install.ts:95-110]()\n\n## SKILL.md 格式规范\n\n### YAML 前置元数据\n\n每个技能必须以 YAML frontmatter 开头：\n\n```yaml\n---\nname: skill-name # 必需：连字符格式标识符\ndescription: 技能用途描述 # 必需：1-2句话，第三人称\n---\n```\n\n### 渐进式加载策略\n\n| 层级 | 内容 | 加载时机 |\n|------|------|----------|\n| 元数据层 | name + description | 始终在上下文中 |\n| 技能说明层 | SKILL.md 内容 | 相关任务时加载 |\n| 资源层 | references/ | 按需选择性加载 |\n\n### 编写规范\n\n- 使用祈使语气：\"To do X, execute Y\"\n- 避免第二人称：\"You should...\" 改为 \"执行...\"\n- SKILL.md 控制在 5000 词以内\n- 详细内容移至 `references/` 目录\n\n资料来源：[examples/my-first-skill/references/skill-format.md]()\n\n## 测试覆盖\n\n项目使用 Vitest 框架进行测试，测试套件包含：\n\n| 测试类型 | 覆盖范围 |\n|----------|----------|\n| 单元测试 | 符号链接检测、YAML 解析 |\n| 集成测试 | install、sync 命令 |\n| 端到端测试 | 完整 CLI 工作流 |\n\n运行测试命令：\n```bash\nnpm run test # 运行所有测试\nnpm run test:watch # 监听模式\nnpm run test:coverage # 覆盖率报告\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 技术栈总结\n\n| 层级 | 技术选型 | 理由 |\n|------|----------|------|\n| 运行时 | Node.js 20.6+ | 现代化异步特性支持 |\n| 开发语言 | TypeScript 5.9 | 类型安全保证 |\n| CLI 框架 | Commander 12 | 成熟的命令行解析 |\n| 用户交互 | Inquirer 7 + Ora | 美观的交互体验 |\n| 构建工具 | tsup 8 | 快速的 TypeScript 打包 |\n| 测试框架 | Vitest 4 | 高性能的 Vite 集成测试 |\n\n此架构设计确保了 OpenSkills 能够作为一个轻量级、跨平台、与 Claude Code 完全兼容的技能管理系统运行。\n\n---\n\n\n\n## CLI命令参考\n\n### 相关页面\n\n相关主题：[install命令详解](#page-install-command), [sync命令详解](#page-sync-command), [update命令详解](#page-update-command)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n- [src/commands/list.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/list.ts)\n- [src/commands/read.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/read.ts)\n- [src/commands/manage.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/manage.ts)\n- [src/commands/remove.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/remove.ts)\n- [src/commands/sync.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/sync.ts)\n- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n \n\n# CLI命令参考\n\nOpenSkills 是一个为AI编码助手设计的通用技能加载工具，通过命令行接口（CLI）实现技能的安装、管理和同步功能。本页面详细介绍 OpenSkills CLI 的所有命令及其用法。\n\n## 概述\n\nOpenSkills CLI 提供了一套完整的命令，用于管理 AI 代理技能的生命周期。CLI 基于 Node.js 构建，使用 Commander.js 作为命令行参数解析框架，并集成了 Inquirer.js 用于交互式提示。 资料来源：[src/cli.ts:1-50]()\n\n### 核心功能模块\n\n| 模块 | 功能描述 |\n|------|----------|\n| `install` | 从各种来源安装技能（GitHub、本地路径、私有仓库） |\n| `list` | 列出所有已安装的技能 |\n| `read` | 读取技能内容并输出到标准输出 |\n| `update` | 从源更新已安装的技能 |\n| `sync` | 同步技能信息到 AGENTS.md 文件 |\n| `manage` | 交互式管理技能（删除） |\n| `remove` | 移除指定的技能 |\n\n## 命令详解\n\n### install - 安装技能\n\n`install` 命令用于从多种来源安装 AI 技能到本地环境。\n\n#### 基本语法\n\n```bash\nnpx openskills install [options]\n```\n\n#### 参数与选项\n\n| 参数/选项 | 类型 | 说明 |\n|-----------|------|------|\n| `` | 位置参数 | 安装来源（GitHub仓库、本地路径、Git URL） |\n| `-g, --global` | 选项 | 全局安装到 `~/.claude/skills/` |\n| `-u, --universal` | 选项 | 安装到 `.agent/skills/` 用于多代理环境 |\n| `-y, --yes` | 选项 | 跳过交互确认，自动安装所有找到的技能 |\n\n#### 安装来源类型\n\n1. **Anthropic Marketplace**\n ```bash\n npx openskills install anthropics/skills\n ```\n\n2. **任意 GitHub 仓库**\n ```bash\n npx openskills install your-org/your-skills\n ```\n\n3. **本地路径**\n ```bash\n npx openskills install ./local-skills/my-skill\n ```\n\n4. **私有 Git 仓库**\n ```bash\n npx openskills install git@github.com:your-org/private-skills.git\n ```\n\n#### 安装行为流程\n\n```mermaid\ngraph TD\n A[install 命令执行] --> B{源类型判断}\n B -->|GitHub| C[克隆远程仓库]\n B -->|本地路径| D[验证本地路径存在]\n B -->|私有仓库| E[使用SSH密钥克隆]\n C --> F[定位 SKILL.md]\n D --> F\n E --> F\n F --> G{安装位置判断}\n G -->|项目级| H[安装到 .claude/skills/]\n G -->|全局| I[安装到 ~/.claude/skills/]\n G -->|通用| J[安装到 .agent/skills/]\n H --> K[写入技能元数据]\n I --> K\n J --> K\n K --> L[安装完成]\n```\n\n#### 元数据构建\n\n安装过程中，系统会根据来源类型构建不同的元数据：\n\n| 来源类型 | 元数据字段 |\n|----------|------------|\n| Git 来源 | `sourceType: 'git'`、`repoUrl`、`subpath`、`installedAt` |\n| 本地来源 | `sourceType: 'local'`、`localPath`、`installedAt` |\n\n资料来源：[src/commands/install.ts:1-80]()\n\n---\n\n### list - 列出技能\n\n`list` 命令显示所有已安装的技能及其状态信息。\n\n#### 基本语法\n\n```bash\nnpx openskills list\n```\n\n#### 输出示例\n\n```\n📦 已安装技能\n\n├── pdf [project] /path/to/project/.claude/skills/pdf\n├── git-workflow [global] ~/.claude/skills/git-workflow\n└── check-branch-first [project] /path/to/project/.claude/skills/check-branch-first\n```\n\n---\n\n### read - 读取技能内容\n\n`read` 命令将技能内容输出到标准输出，供 AI 代理读取。\n\n#### 基本语法\n\n```bash\nnpx openskills read \n```\n\n#### 参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `` | 剩余参数 | 一个或多个技能名称，用空格分隔 |\n\n#### 使用示例\n\n```bash\n# 读取单个技能\nnpx openskills read pdf\n\n# 读取多个技能（逗号分隔）\nnpx openskills read foo,bar\n\n# 读取多个技能（空格分隔）\nnpx openskills read pdf git-workflow check-branch\n```\n\n#### 输出格式\n\n读取技能时，输出包含以下信息：\n\n- **基础目录路径**：用于解析相对资源路径\n- **完整 SKILL.md 内容**：包含技能指令和元数据\n- **引用资源路径**：references/、scripts/、assets/ 的相对路径\n\n---\n\n### update - 更新技能\n\n`update` 命令从原始源重新获取并更新已安装的技能。\n\n#### 基本语法\n\n```bash\nnpx openskills update [skill-names...]\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `[skill-names...]` | 可选参数 | 指定要更新的技能名称，默认为全部 |\n\n#### 更新流程\n\n```mermaid\ngraph TD\n A[update 命令执行] --> B{是否指定技能}\n B -->|是| C[筛选目标技能]\n B -->|否| D[加载所有技能]\n C --> E{技能元数据检查}\n D --> E\n E -->|本地来源| F[验证本地路径存在]\n E -->|Git 来源| G[克隆远程仓库]\n F -->|路径无效| H[跳过并警告]\n F -->|路径有效| I[复制 SKILL.md]\n G --> J[定位子路径]\n I --> K[更新 installedAt 时间戳]\n J --> K\n K --> L[更新完成]\n H --> M[报告跳过列表]\n```\n\n#### 特殊处理\n\n| 场景 | 处理方式 |\n|------|----------|\n| 本地源缺失 | 输出黄色警告并跳过 |\n| SKILL.md 不存在 | 输出警告并跳过 |\n| 缺少仓库 URL | 输出警告并跳过 |\n| Git 克隆失败 | 显示错误信息 |\n\n资料来源：[src/commands/update.ts:1-60]()\n\n---\n\n### sync - 同步到 AGENTS.md\n\n`sync` 命令将已安装的技能信息生成为 `` XML 块，并插入或更新 AGENTS.md 文件。\n\n#### 基本语法\n\n```bash\nnpx openskills sync [options]\n```\n\n#### 选项说明\n\n| 选项 | 说明 |\n|------|------|\n| `-y, --yes` | 跳过交互确认，同步所有技能 |\n| `-o, --output ` | 指定输出文件路径（默认：AGENTS.md） |\n\n#### 输出文件格式\n\n```markdown\n\n\n## Available Skills\n\n\n\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively...\n\nHow to use skills:\n- Invoke: `npx openskills read ` (run in your shell)\n- The skill content will load with detailed instructions...\n\n\n\n\npdf\nComprehensive PDF manipulation toolkit...\nproject\n\n\n\n\n\n```\n\n#### XML 标记说明\n\n| 标记 | 说明 |\n|------|------|\n| `` | 根元素，包含优先级属性 |\n| `` | 技能列表容器 |\n| `` | 单个技能定义块 |\n| `` | 技能名称（英文、中划线分隔） |\n| `` | 技能描述（1-2句话） |\n| `` | 安装位置（project/global） |\n\n---\n\n### manage - 交互式管理\n\n`manage` 命令提供交互式界面用于管理已安装的技能。\n\n#### 基本语法\n\n```bash\nnpx openskills manage\n```\n\n#### 交互流程\n\n1. 显示已安装技能列表\n2. 提供多选界面选择要移除的技能\n3. 确认后执行删除操作\n4. 更新 AGENTS.md（如需要）\n\n---\n\n### remove - 移除技能\n\n`remove` 命令直接移除指定的技能，无需交互确认。\n\n#### 基本语法\n\n```bash\nnpx openskills remove \n```\n\n#### 参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `` | 位置参数 | 要移除的技能名称 |\n\n#### 使用示例\n\n```bash\nnpx openskills remove pdf\nnpx openskills remove git-workflow\n```\n\n---\n\n## 安装优先级\n\n当使用 `--universal` 选项或存在多个安装位置时，技能加载遵循以下优先级顺序（优先级高者优先）：\n\n```mermaid\ngraph LR\n A1[.agent/skills/] --> A[优先级 1]\n A2[~/.agent/skills/] --> A\n B1[.claude/skills/] --> B[优先级 2]\n B2[~/.claude/skills/] --> B\n A --> C[技能加载顺序]\n B --> C\n```\n\n| 优先级 | 路径 | 用途 |\n|--------|------|------|\n| 1 | `./.agent/skills/` | 多代理通用设置 |\n| 1 | `~/.agent/skills/` | 全局多代理设置 |\n| 2 | `./.claude/skills/` | 项目级 Claude Code 设置 |\n| 2 | `~/.claude/skills/` | 全局 Claude Code 设置 |\n\n---\n\n## 环境要求\n\n| 要求 | 最低版本 |\n|------|----------|\n| Node.js | 20.6.0+ |\n| Git | 任意版本 |\n\n---\n\n## 命令速查表\n\n| 命令 | 用法 | 核心功能 |\n|------|------|----------|\n| `install` | `npx openskills install ` | 安装技能 |\n| `list` | `npx openskills list` | 列出已安装技能 |\n| `read` | `npx openskills read [,...]` | 读取技能内容 |\n| `update` | `npx openskills update [name...]` | 更新技能 |\n| `sync` | `npx openskills sync [-y] [-o ]` | 同步到 AGENTS.md |\n| `manage` | `npx openskills manage` | 交互式管理 |\n| `remove` | `npx openskills remove ` | 移除技能 |\n\n---\n\n\n\n## install命令详解\n\n### 相关页面\n\n相关主题：[CLI命令参考](#page-cli-commands), [数据存储与管理](#page-data-storage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)\n- [src/utils/marketplace-skills.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/marketplace-skills.ts)\n- [src/utils/yaml.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/yaml.ts)\n- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)\n \n\n# install命令详解\n\n## 概述\n\n`install` 是 OpenSkills 的核心命令之一，负责从各种来源安装技能（Skills）。该命令支持从 GitHub 仓库、本地路径、Git 远程仓库以及私有仓库安装技能，并自动处理技能元数据的存储和更新。\n\n**功能范围：**\n\n- 从 Anthropic Marketplace 安装预制技能\n- 从任意 GitHub 仓库安装技能\n- 从本地目录安装本地开发的技能\n- 支持私有 Git 仓库安装（SSH/HTTPS）\n- 自动检测并处理符号链接冲突\n- 支持全局安装和项目级安装\n\n**版本历史：**\n- v1.0.0：初始发布\n- v1.2.0：新增 `--universal` 标志\n- v1.5.0：新增本地路径安装和私有仓库支持\n\n资料来源：[package.json:3-24](https://github.com/numman-ali/openskills/blob/main/package.json)\n\n---\n\n## 命令语法\n\n```bash\nnpx openskills install [options]\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `` | string | 是 | 安装来源，可以是 GitHub 仓库、本地路径或 Git URL |\n\n### 可用选项\n\n| 选项 | 简写 | 类型 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `--global` | `-g` | boolean | false | 全局安装到 `~/.claude/skills/` |\n| `--universal` | `-u` | boolean | false | 安装到 `.agent/skills/` 用于多智能体环境 |\n| `--yes` | `-y` | boolean | false | 跳过所有交互提示，自动确认 |\n\n资料来源：[src/cli.ts:26-35](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n\n---\n\n## 安装来源类型\n\nOpenSkills 支持多种安装来源，命令会自动识别来源类型并采用相应的安装策略。\n\n```mermaid\ngraph TD\n A[install source] --> B{来源类型判断}\n B -->|GitHub shorthand| C[marketplace-skills.ts]\n B -->|本地路径| D[本地目录检测]\n B -->|git@ URL| E[SSH 私有仓库]\n B -->|https:// URL| F[HTTPS 私有仓库]\n B -->|github.com URL| G[GitHub 完整 URL]\n \n C --> H[从 Marketplace 获取]\n D --> I[直接复制/Symlink]\n E --> J[SSH 认证克隆]\n F --> K[HTTPS 认证克隆]\n G --> L[直接克隆]\n```\n\n### 1. Anthropic Marketplace\n\n使用简写格式从 Anthropic 官方技能市场安装：\n\n```bash\nnpx openskills install anthropics/skills\nnpx openskills install anthropics/skills/pdf-editor\n```\n\n资料来源：[README.md:30-32](https://github.com/numman-ali/openskills/blob/main/README.md)\n\n### 2. GitHub 仓库\n\n从任意 GitHub 仓库安装，支持完整 URL 或简写格式：\n\n```bash\n# 简写格式\nnpx openskills install owner/repo\nnpx openskills install owner/repo/path/to/skill\n\n# 完整 URL 格式\nnpx openskills install https://github.com/owner/repo\n```\n\n### 3. 本地路径\n\n支持绝对路径、相对路径和波浪号展开：\n\n```bash\n# 绝对路径\nnpx openskills install /path/to/my-skill\n\n# 相对路径\nnpx openskills install ./local-skills/my-skill\nnpx openskills install ../my-skill\n\n# 波浪号展开\nnpx openskills install ~/my-skills/skill\n```\n\n资料来源：[CHANGELOG.md:47-52](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)\n\n### 4. 私有 Git 仓库\n\n支持 SSH 和 HTTPS 两种认证方式：\n\n```bash\n# SSH 方式（使用系统 SSH 密钥）\nnpx openskills install git@github.com:your-org/private-skills.git\n\n# HTTPS 方式（需要配置 Git 认证）\nnpx openskills install https://github.com/your-org/private-skills.git\n```\n\n资料来源：[CHANGELOG.md:53-58](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)\n\n---\n\n## 安装位置与优先级\n\nOpenSkills 提供了多种安装位置选项，适用于不同的使用场景。\n\n```mermaid\ngraph TD\n A[install 命令] --> B{--universal?}\n B -->|是| C[.agent/skills/]\n B -->|否| D{--global?}\n D -->|是| E[~/.claude/skills/]\n D -->|否| F[项目安装]\n F --> G{存在.claude?}\n G -->|是| H[./.claude/skills/]\n G -->|否| I[./.agent/skills/]\n \n style C fill:#ff9999\n style E fill:#99ccff\n style H fill:#99ff99\n style I fill:#99ff99\n```\n\n### 位置优先级（最高优先）\n\n| 优先级 | 位置 | 说明 |\n|--------|------|------|\n| 1 | `./.agent/skills/` | 项目级通用目录（当 `.claude` 不存在时） |\n| 2 | `./.claude/skills/` | 项目级 Claude Code 目录 |\n| 3 | `~/.agent/skills/` | 用户级通用目录 |\n| 4 | `~/.claude/skills/` | 用户级全局目录 |\n\n资料来源：[README.md:44-51](https://github.com/numman-ali/openskills/blob/main/README.md)\n\n---\n\n## 工作流程\n\n### 安装流程图\n\n```mpx openskillsxy\ngraph LR\n A[解析 source 参数] --> B{识别来源类型}\n B -->|GitHub| C[获取仓库信息]\n B -->|本地| D[验证本地路径]\n B -->|Git URL| E[解析 Git URL]\n \n C --> F[克隆或更新仓库]\n D --> G[验证 SKILL.md 存在]\n E --> H[执行 git clone]\n \n F --> I[查找 SKILL.md]\n G --> I\n H --> I\n \n I --> J[创建技能目录]\n J --> K[复制/Symlink 文件]\n K --> L[生成元数据]\n L --> M[写入 metadata.json]\n M --> N[输出安装成功信息]\n```\n\n### 详细步骤说明\n\n1. **来源解析**\n - 解析 `` 参数确定安装类型\n - 提取仓库 URL、组织/仓库名、技能路径等信息\n\n2. **获取技能**\n - GitHub：通过 Git 克隆仓库\n - 本地：验证路径存在且包含 SKILL.md\n\n3. **元数据生成**\n - 创建 `metadata.json` 记录安装来源\n - 存储安装时间、来源类型、仓库 URL 等信息\n\n4. **文件复制**\n - 根据安装类型决定复制或创建符号链接\n - 本地开发模式优先使用符号链接\n\n资料来源：[src/commands/install.ts:50-150](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n\n---\n\n## 元数据结构\n\n每个已安装的技能都包含一个 `metadata.json` 文件，记录技能的来源和安装信息。\n\n### 元数据字段\n\n| 字段 | 类型 | 说明 | 来源类型 |\n|------|------|------|----------|\n| `source` | string | 原始安装命令参数 | 所有 |\n| `sourceType` | string | 来源类型：`git` 或 `local` | 所有 |\n| `repoUrl` | string | Git 仓库 URL | git |\n| `subpath` | string | 技能在仓库中的子路径 | git |\n| `localPath` | string | 本地路径 | local |\n| `installedAt` | string | ISO 8601 安装时间戳 | 所有 |\n\n### Git 来源元数据示例\n\n```json\n{\n \"source\": \"anthropics/skills/pdf-editor\",\n \"sourceType\": \"git\",\n \"repoUrl\": \"https://github.com/anthropics/skills\",\n \"subpath\": \"pdf-editor\",\n \"installedAt\": \"2026-01-20T10:30:00.000Z\"\n}\n```\n\n### 本地来源元数据示例\n\n```json\n{\n \"source\": \"./my-skill\",\n \"sourceType\": \"local\",\n \"localPath\": \"/Users/developer/projects/my-skill\",\n \"installedAt\": \"2026-01-20T10:30:00.000Z\"\n}\n```\n\n资料来源：[src/commands/install.ts:100-120](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n\n---\n\n## 冲突检测与处理\n\n### Claude Code 市场冲突警告\n\n当安装的技能名称与 Claude Code 原生插件市场冲突时，命令会发出警告：\n\n```mermaid\ngraph TD\n A[install skill-name] --> B{目标路径存在?}\n B -->|是| C[检查是否为符号链接]\n C -->|是| D{--yes 标志?}\n C -->|否| E[警告：覆盖风险]\n D -->|是| F[自动覆盖]\n D -->|否| G[询问用户确认]\n B -->|否| H[继续安装]\n E --> G\n```\n\n### 冲突处理规则\n\n| 情况 | 行为 |\n|------|------|\n| `--yes` 模式 | 自动覆盖，不提示 |\n| 交互模式 | 询问用户确认 |\n| 符号链接断开 | 优雅跳过，显示警告 |\n\n资料来源：[src/commands/install.ts:160-180](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n\n---\n\n## 与其他命令的协作\n\n`install` 命令不独立工作，它与其他 OpenSkills 命令紧密配合：\n\n```mermaid\ngraph LR\n A[install] -->|安装技能| B[本地文件系统]\n C[sync] -->|读取安装信息| B\n C -->|生成 AGENTS.md| D[AGENTS.md]\n \n E[update] -->|读取 metadata.json| B\n E -->|更新技能| B\n \n F[read] -->|加载技能内容| B\n F -->|输出到 stdout| G[AI Agent]\n \n H[list] -->|扫描安装目录| B\n H -->|显示技能列表| I[终端]\n```\n\n| 命令 | 与 install 的关系 |\n|------|-------------------|\n| `sync` | 读取已安装技能，生成 AGENTS.md |\n| `update` | 读取 metadata.json，从原来源更新 |\n| `read` | 加载已安装技能的内容 |\n| `list` | 显示所有已安装技能 |\n\n资料来源：[src/cli.ts:20-45](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n\n---\n\n## 使用示例\n\n### 基础安装\n\n```bash\n# 从 Anthropic Marketplace 安装所有技能\nnpx openskills install anthropics/skills\n\n# 安装单个技能\nnpx openskills install anthropics/skills/pdf-editor\n\n# 从其他 GitHub 仓库安装\nnpx openskills install owner/custom-skills\n```\n\n### 项目级 vs 全局安装\n\n```bash\n# 项目级安装（默认）\nnpx openskills install anthropics/skills\n# 安装到: ./.claude/skills/\n\n# 全局安装\nnpx openskills install anthropics/skills --global\n# 安装到: ~/.claude/skills/\n```\n\n### 多智能体环境安装\n\n```bash\n# 使用 --universal 标志\nnpx openskills install anthropics/skills --universal\n# 安装到: ./.agent/skills/\n\n# 可被 Claude Code、Cursor、Windsurf、Aider 等共用\n```\n\n### CI/CD 环境使用\n\n```bash\n# 使用 --yes 跳过所有交互\nnpx openskills install your-org/your-skills --yes\n\n# 指定输出文件\nnpx openskills install your-org/your-skills --yes --output .ruler/AGENTS.md\n```\n\n### 本地开发工作流\n\n```bash\n# 克隆技能仓库到开发目录\ngit clone git@github.com:your-org/my-skills.git ~/dev/my-skills\n\n# 创建符号链接进行开发\nmkdir -p .claude/skills\nln -s ~/dev/my-skills/pdf-editor .claude/skills/pdf-editor\n\n# 安装后更新\nnpx openskills update pdf-editor\n```\n\n资料来源：[README.md:54-66](https://github.com/numman-ali/openskills/blob/main/README.md)\n\n---\n\n## 依赖项\n\n`install` 命令依赖以下核心依赖包：\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| `commander` | ^12.1.0 | CLI 参数解析和命令定义 |\n| `@inquirer/prompts` | ^7.9.0 | 交互式提示（冲突确认等） |\n| `chalk` | ^5.6.2 | 终端彩色输出 |\n| `ora` | ^9.0.0 | 加载动画 |\n\n**系统要求：**\n\n- Node.js >= 20.6.0\n- Git（用于克隆仓库）\n\n资料来源：[package.json:15-20](https://github.com/numman-ali/openskills/blob/main/package.json)\n\n---\n\n## 常见问题\n\n### Q: 安装后技能没有出现在 list 中？\n\n检查技能目录是否正确：\n```bash\nls -la .claude/skills/ # 项目级\nls -la ~/.claude/skills/ # 全局\n```\n\n### Q: 如何安装私有仓库？\n\n确保：\n1. SSH 方式已配置 SSH 密钥\n2. HTTPS 方式已配置 Git 凭证\n\n```bash\n# SSH 方式\ngit clone git@github.com:org/private-skills.git\n\n# 验证 SSH 密钥\nssh -T git@github.com\n```\n\n### Q: 如何处理符号链接冲突？\n\n使用 `--yes` 标志自动覆盖，或手动删除后重新安装：\n```bash\nrm -rf .claude/skills/conflicting-skill\nnpx openskills install owner/skill\n\n---\n\n\n\n## sync命令详解\n\n### 相关页面\n\n相关主题：[CLI命令参考](#page-cli-commands), [SKILL.md格式规范](#page-skill-md-format)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/commands/sync.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/sync.ts)\n- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [src/types.ts](https://github.com/numman-ali/openskills/blob/main/src/types.ts)\n- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n \n\n# sync命令详解\n\n`sync` 是 OpenSkills 的核心命令之一，用于将已安装的技能（Skills）同步到 `AGENTS.md` 文件中，生成可供 AI Agent 识别的 `` XML 区块。本文详细解析该命令的实现原理、工作流程和配置选项。\n\n## 功能概述\n\n`sync` 命令的主要职责是根据已安装技能的元数据，动态生成符合 Anthropic Agent Skills 规范的 XML 内容，并将其注入到 `AGENTS.md` 文件中。生成的 XML 遵循特定的优先级机制，支持渐进式加载（Progressive Disclosure）模式。\n\n**核心功能：**\n\n| 功能 | 描述 |\n|------|------|\n| 技能扫描 | 读取 `.claude/skills/` 或 `.agent/skills/` 目录下的已安装技能 |\n| XML生成 | 生成包含 name、description、location 的 skill 标签 |\n| 文件更新 | 将生成的 XML 区块替换或插入到目标 Markdown 文件 |\n| 输出控制 | 支持自定义输出路径 |\n\n资料来源：[src/cli.ts:35-38]()\n\n## 命令行接口\n\n### 基本语法\n\n```bash\nnpx openskills sync [选项]\n```\n\n### 参数与选项\n\n| 选项 | 简写 | 类型 | 默认值 | 描述 |\n|------|------|------|--------|------|\n| `--yes` | `-y` | 布尔 | `false` | 跳过交互式确认，同步所有技能 |\n| `--output` | `-o` | 路径 | `AGENTS.md` | 指定输出文件路径 |\n\n**使用示例：**\n\n```bash\n# 默认同步到 AGENTS.md\nnpx openskills sync\n\n# 跳过交互确认\nnpx openskills sync -y\n\n# 输出到自定义路径\nnpx openskills sync -o .ruler/AGENTS.md\n```\n\n资料来源：[src/cli.ts:42-45]()\n\n## 工作流程\n\n`sync` 命令的执行流程可分为三个主要阶段：\n\n```mermaid\ngraph TD\n A[启动 sync 命令] --> B[解析命令行参数]\n B --> C{是否指定 -y?}\n C -->|是| D[跳过交互式选择]\n C -->|否| E[显示技能选择列表]\n E --> F[用户选择要同步的技能]\n D --> G[读取已安装技能元数据]\n F --> G\n G --> H[扫描 skills 目录]\n H --> I[解析每个技能的 SKILL.md]\n I --> J[生成 XML 内容]\n J --> K[更新目标文件]\n K --> L[输出完成信息]\n```\n\n### 阶段一：参数解析\n\nCLI 框架（Commander.js）负责解析用户输入的选项。如果未指定 `-y` 标志，命令将启动交互式界面让用户选择要同步的技能。\n\n资料来源：[src/cli.ts:42-45]()\n\n### 阶段二：技能扫描与 XML 生成\n\n系统会遍历指定的 skills 目录（默认为 `.claude/skills/`），读取每个技能目录下的 `SKILL.md` 文件，解析 YAML frontmatter 中的 `name` 和 `description` 字段。\n\n生成的 XML 结构如下：\n\n```xml\n\n\n## Available Skills\n\n\n\n当用户请求任务时，检查以下可用技能...\n\n\n\n\nskill-name\n技能描述\nproject\n\n\n\n\n\n```\n\n资料来源：[src/utils/agents-md.ts:55-85]()\n\n### 阶段三：文件更新\n\n`sync` 命令使用 `replaceSkillsSection` 函数处理目标文件。该函数支持两种标记格式：\n\n1. **XML 标记格式**（首选）：\n ```html\n ...\n ```\n\n2. **HTML 注释格式**（向后兼容）：\n ```html\n ...\n ```\n\n函数会自动检测文件中存在的标记格式，并执行相应的替换操作。\n\n资料来源：[src/utils/agents-md.ts:88-110]()\n\n## 核心实现\n\n### agents-md.ts 工具模块\n\n该模块提供了三个核心函数：\n\n#### `parseCurrentSkills(content: string): string[]`\n\n解析 `AGENTS.md` 文件中当前已列出的技能名称：\n\n```typescript\nconst skillRegex = /[\\s\\S]*?([^<]+)<\\/name>[\\s\\S]*?<\\/skill>/g;\n```\n\n正则表达式匹配 `` 标签块，提取其中的 `` 元素值。\n\n资料来源：[src/utils/agents-md.ts:113-122]()\n\n#### `generateSkillsXml(skills: Skill[]): string`\n\n根据技能数组生成完整的 XML 区块：\n\n```typescript\nexport function generateSkillsXml(skills: Skill[]): string {\n const skillTags = skills\n .map(\n (s) => `\n${s.name}\n${s.description}\n${s.location}\n`\n )\n .join('\\n\\n');\n // ... 生成完整 XML 结构\n}\n```\n\n每个技能生成独立的 `` 标签块，包含三个子元素：\n- ``：技能标识符\n- ``：技能描述\n- ``：安装位置（`project` 或 `global`）\n\n资料来源：[src/utils/agents-md.ts:125-148]()\n\n#### `replaceSkillsSection(content: string, newSection: string): string`\n\n执行实际的文件替换操作：\n\n```typescript\nexport function replaceSkillsSection(content: string, newSection: string): string {\n const startMarker = ']*>[\\s\\S]*?<\\/skills_system>/;\n return content.replace(regex, newSection);\n }\n // ... 处理 HTML 注释格式\n}\n```\n\n函数首先尝试使用 XML 标记进行匹配和替换，如果失败则回退到 HTML 注释格式。\n\n资料来源：[src/utils/agents-md.ts:88-110]()\n\n### Skill 数据模型\n\n```typescript\ninterface Skill {\n name: string; // 技能标识符\n description: string; // 技能描述\n location: string; // 安装位置：'project' | 'global'\n}\n```\n\n资料来源：[src/types.ts]()\n\n## 与 update 命令的协同\n\n`sync` 命令与 `update` 命令存在密切配合关系。当用户执行 `npx openskills update` 时，更新后的技能元数据会被重新写入，此时可以使用 `sync` 命令将更新后的技能信息同步到 `AGENTS.md`：\n\n```bash\n# 更新所有技能后同步\nnpx openskills update\nnpx openskills sync\n```\n\n`update` 命令支持更新本地路径安装的技能：\n\n```typescript\nif (metadata.sourceType === 'local') {\n const localPath = metadata.localPath;\n if (!existsSync(localPath)) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (local source missing)`));\n continue;\n }\n updateSkillFromDir(skill.path, localPath);\n writeSkillMetadata(skill.path, { ...metadata, installedAt: new Date().toISOString() });\n}\n```\n\n资料来源：[src/commands/update.ts:89-102]()\n\n## 输出文件格式\n\n`sync` 命令生成的文件采用固定的模板结构，包含以下部分：\n\n| 部分 | 描述 |\n|------|------|\n| `` | 根元素，包含 `priority=\"1\"` 属性 |\n| `` | 使用说明文本，指导 AI Agent 如何调用技能 |\n| `` | 技能列表容器 |\n| `` | 单个技能定义块 |\n\n**生成的完整结构示例：**\n\n```xml\n\n\n## Available Skills\n\n\n\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.\n\nHow to use skills:\n- Invoke: `npx openskills read ` (run in your shell)\n - For multiple: `npx openskills read skill-one,skill-two`\n- The skill content will load with detailed instructions\n- Base directory provided in output for resolving bundled resources\n\nUsage notes:\n- Only use skills listed in below\n- Do not invoke a skill that is already loaded in your context\n\n\n\n\npdf\nComprehensive PDF manipulation toolkit...\nproject\n\n\n\n\n\n```\n\n资料来源：[src/utils/agents-md.ts:55-85]()\n\n## 配置选项详解\n\n### 输出路径配置\n\n`sync` 命令支持通过 `-o` 或 `--output` 选项指定输出文件路径：\n\n| 输入 | 输出位置 |\n|------|----------|\n| `npx openskills sync` | `./AGENTS.md` |\n| `npx openskills sync -o .ruler/AGENTS.md` | `./.ruler/AGENTS.md` |\n| `npx openskills sync -o /absolute/path/file.md` | `/absolute/path/file.md` |\n\n**特殊功能：**\n\n- **自动创建目录**：如果指定的输出路径包含不存在的目录，系统会自动创建\n- **自动创建文件**：如果目标文件不存在，系统会创建文件并添加标题\n- **自动创建区块**：如果文件中不存在 `` 区块，系统会自动插入\n\n资料来源：[src/cli.ts:42-45]()\n\n### 非交互模式\n\n使用 `-y` 或 `--yes` 标志可以跳过所有交互式确认，直接同步所有已安装的技能：\n\n```bash\n# CI/CD 环境推荐用法\nnpx openskills sync -y\n```\n\n此模式适用于自动化脚本和持续集成环境。\n\n## 最佳实践\n\n### 1. 定期同步\n\n建议在以下时机执行 `sync` 命令：\n\n| 时机 | 原因 |\n|------|------|\n| 安装新技能后 | 确保新技能被 AI Agent 识别 |\n| 移除技能后 | 清理 AGENTS.md 中的过时信息 |\n| 更新技能描述后 | 同步最新的技能元数据 |\n\n### 2. 多代理环境配置\n\n在同时使用 Claude Code 和其他 Agent（如 Cursor、Windsurf）的环境中，推荐使用 `--universal` 标志安装技能到 `.agent/skills/` 目录：\n\n```bash\nnpx openskills install your-org/your-skills --universal\nnpx openskills sync -o .agent/AGENTS.md\n```\n\n这样可以避免与 Claude Code 原生插件市场的冲突。\n\n### 3. 版本控制建议\n\n将 `AGENTS.md` 纳入版本控制，确保团队成员获得一致的技能配置。\n\n## 错误处理\n\n`sync` 命令可能遇到的错误场景及处理方式：\n\n| 错误场景 | 处理方式 |\n|----------|----------|\n| 目标目录不存在 | 自动创建目录结构 |\n| 目标文件只读 | 报错并提示修改权限 |\n| skills 目录为空 | 生成空的 `` 区块 |\n| YAML 解析失败 | 跳过该技能，显示警告信息 |\n\n## 相关命令\n\n| 命令 | 功能 | 关系 |\n|------|------|------|\n| `install` | 安装技能到本地 | sync 依赖已安装的技能 |\n| `update` | 更新技能版本 | 与 sync 配合使用 |\n| `list` | 列出已安装技能 | 提供参考信息 |\n| `read` | 读取技能内容 | AI Agent 实际调用技能 |\n\n## 总结\n\n`sync` 命令是 OpenSkills 生态系统的关键连接点，它将本地安装的技能与 AI Agent 的上下文系统桥接起来。通过解析已安装技能的元数据并生成符合规范的 XML 内容，该命令使得 AI Agent 能够在需要时动态加载相应的技能指导。\n\n核心要点：\n- 使用 `-o` 选项支持灵活的输出路径配置\n- `-y` 标志实现完全非交互式同步\n- 支持 XML 和 HTML 注释两种标记格式\n- 自动处理文件创建和目录结构\n\n---\n\n\n\n## update命令详解\n\n### 相关页面\n\n相关主题：[install命令详解](#page-install-command), [数据存储与管理](#page-data-storage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n- [src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)\n- [src/utils/skills.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skills.ts)\n- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n \n\n# update命令详解\n\n## 概述\n\n`update` 命令是 OpenSkills 提供的核心功能之一，用于从已记录的源代码刷新已安装的技能（Skills）。该命令在 v1.5.0 版本中引入，解决了用户安装技能后如何获取更新的问题。\n\n### 核心功能\n\n- 从 Git 仓库更新技能\n- 从本地目录更新技能\n- 批量更新所有已安装的技能\n- 跳过无法确定源代码的技能并给出提示\n\n资料来源：[CHANGELOG.md](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)\n\n---\n\n## 架构设计\n\n### 模块依赖关系\n\n```mermaid\ngraph TD\n A[CLI入口 update命令] --> B[commands/update.ts]\n B --> C[skill-metadata.ts]\n B --> D[skills.ts]\n B --> E[文件系统操作]\n \n C --> F[SkillSourceMetadata接口]\n C --> G[元数据读写]\n \n D --> H[技能目录扫描]\n D --> I[SKILL.md解析]\n \n E --> J[git clone]\n E --> K[文件复制]\n```\n\n### 元数据结构\n\n```typescript\ninterface SkillSourceMetadata {\n source: string; // 安装源描述\n sourceType: 'git' | 'local'; // 源类型\n repoUrl?: string; // Git仓库URL (git类型)\n subpath?: string; // 子路径 (git类型)\n localPath?: string; // 本地路径 (local类型)\n installedAt: string; // 安装时间ISO字符串\n}\n```\n\n资料来源：[src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)\n\n---\n\n## 工作流程\n\n### 更新流程图\n\n```mermaid\ngraph TD\n Start[开始更新] --> LoadSkills[加载所有已安装技能]\n LoadSkills --> ForEach{遍历每个技能}\n \n ForEach --> |本地源| CheckLocalPath{检查localPath是否存在}\n CheckLocalPath --> |不存在| SkipMissing[跳过并提示缺失]\n SkipMissing --> Next1[下一个技能]\n \n CheckLocalPath --> |存在| CheckSkillMd{检查SKILL.md}\n CheckSkillMd --> |不存在| SkipNoSkillMd[跳过并提示SKILL.md缺失]\n SkipNoSkillMd --> Next2[下一个技能]\n \n CheckSkillMd --> |存在| CopyFromLocal[从本地复制文件]\n CopyFromLocal --> UpdateMeta[更新元数据installedAt]\n UpdateMeta --> Next3[下一个技能]\n \n ForEach --> |Git源| CheckRepoUrl{检查repoUrl}\n CheckRepoUrl --> |不存在| SkipNoUrl[跳过并提示缺失repoUrl]\n SkipNoUrl --> Next4[下一个技能]\n \n CheckRepoUrl --> |存在| CloneTemp[克隆到临时目录]\n CloneTemp --> ExtractSource[提取子目录源文件]\n ExtractSource --> CopyToTarget[复制到技能目录]\n CopyToTarget --> UpdateMeta2[更新元数据installedAt]\n UpdateMeta2 --> Next5[下一个技能]\n \n Next1 --> |完成| Cleanup[清理临时目录]\n Next2 --> Cleanup\n Next3 --> Cleanup\n Next4 --> Cleanup\n Next5 --> Cleanup\n \n Cleanup --> Report[输出更新结果统计]\n```\n\n---\n\n## 源码解析\n\n### 命令注册\n\n`update` 命令通过 Commander.js 在 CLI 入口点注册：\n\n```typescript\nprogram\n .command('update [skill-names...]')\n .description('Update installed skills from their source (default: all)')\n .action(updateSkills);\n```\n\n资料来源：[src/cli.ts:51-53](https://github.com/numman-ali/openskills/blob/main/src/cli.ts#L51-L53)\n\n### 本地源更新逻辑\n\n当技能源类型为 `local` 时，执行以下流程：\n\n```typescript\nif (metadata.sourceType === 'local') {\n const localPath = metadata.localPath;\n \n // 检查本地路径是否存在\n if (!localPath || !existsSync(localPath)) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (local source missing)`));\n missingLocalSource.push(skill.name);\n skipped++;\n continue;\n }\n \n // 检查SKILL.md是否存在\n if (!existsSync(join(localPath, 'SKILL.md'))) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (SKILL.md missing at local source)`));\n missingLocalSkillFile.push(skill.name);\n skipped++;\n continue;\n }\n \n // 执行更新\n updateSkillFromDir(skill.path, localPath);\n writeSkillMetadata(skill.path, { ...metadata, installedAt: new Date().toISOString() });\n console.log(chalk.green(`✅ Updated: ${skill.name}`));\n updated++;\n}\n```\n\n资料来源：[src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n\n### Git源更新逻辑\n\n当技能源类型为 `git` 时，执行以下流程：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Update as update命令\n participant FS as 文件系统\n participant Git as Git\n \n User->>Update: 执行 update 命令\n Update->>FS: 创建临时目录 ~/.openskills-temp-{timestamp}\n Update->>Git: git clone --depth 1 {repoUrl}\n Git-->>FS: 克隆到 tempDir/repo\n Update->>FS: 提取子目录文件\n Update->>FS: 复制到技能安装目录\n Update->>FS: 更新元数据 (installedAt)\n Update->>FS: 清理临时目录\n Update->>User: 输出更新结果\n```\n\n关键实现代码：\n\n```typescript\nif (!metadata.repoUrl) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (missing repo URL metadata)`));\n missingRepoUrl.push(skill.name);\n skipped++;\n continue;\n}\n\nconst tempDir = join(homedir(), `.openskills-temp-${Date.now()}`);\nmkdirSync(tempDir, { recursive: true });\n\nconst spinner = ora(`Updating ${skill.name}...`).start();\ntry {\n execSync(`git clone --depth 1 --quiet \"${metadata.repoUrl}\" \"${tempDir}/repo\"`, { \n stdio: 'pipe' \n });\n \n const repoDir = join(tempDir, 'repo');\n const subpath = metadata.subpath && metadata.subpath !== '.' ? metadata.subpath : '';\n const sourceDir = subpath ? join(repoDir, subpath) : repoDir;\n \n // 继续处理...\n} finally {\n // 清理临时目录\n}\n```\n\n资料来源：[src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n\n---\n\n## 使用方法\n\n### 基本语法\n\n```bash\nnpx openskills update [skill-names...]\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| skill-names | string[] | 否 | 要更新的技能名称，不提供则更新所有技能 |\n\n### 使用场景\n\n#### 更新所有技能\n\n```bash\n# 更新所有已安装的技能\nnpx openskills update\n```\n\n#### 更新指定技能\n\n```bash\n# 更新单个技能\nnpx openskills update pdf\n\n# 更新多个技能\nnpx openskills update pdf,git-workflow,check-branch-first\n```\n\n---\n\n## 输出示例\n\n### 成功更新\n\n```\n✅ Updated: pdf\n✅ Updated: git-workflow\n✅ Updated: check-branch-first\n\n更新完成: 3 个技能已更新\n```\n\n### 跳过技能\n\n```\nSkipped: some-skill (missing repo URL metadata)\n\n⚠️ 1 个技能跳过（无源代码信息）\n```\n\n### 输出统计\n\n```typescript\n// 更新完成后显示统计\nconsole.log(`\\n✅ 更新完成: ${updated} 个技能已更新`);\n\nif (skipped > 0) {\n console.log(`⚠️ ${skipped} 个技能跳过`);\n console.log('提示: 重新安装技能以获取源代码信息');\n}\n```\n\n资料来源：[src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n\n---\n\n## 错误处理\n\n### 错误类型与处理策略\n\n| 错误类型 | 处理策略 | 用户提示 |\n|----------|----------|----------|\n| 本地源路径不存在 | 跳过 | `Skipped: {name} (local source missing)` |\n| 本地源缺少SKILL.md | 跳过 | `Skipped: {name} (SKILL.md missing at local source)` |\n| Git仓库URL缺失 | 跳过 | `Skipped: {name} (missing repo URL metadata)` |\n| Git克隆失败 | 标记失败 | 显示错误信息 |\n| 文件复制失败 | 标记失败 | 显示错误信息 |\n\n### 临时目录清理\n\n更新完成后，无论成功与否，都会清理临时目录：\n\n```typescript\nfinally {\n if (existsSync(tempDir)) {\n rmSync(tempDir, { recursive: true, force: true });\n }\n}\n```\n\n---\n\n## 相关配置\n\n### 元数据存储位置\n\n每个技能的元数据存储在 `~/.claude/skills/{skill-name}/.skill-metadata.json` 或 `./.claude/skills/{skill-name}/.skill-metadata.json` 文件中。\n\n### 完整元数据接口\n\n```typescript\ninterface SkillSourceMetadata {\n source: string; // 原始安装源\n sourceType: 'git' | 'local'; // 源类型\n repoUrl?: string; // Git仓库地址 (git类型必须)\n subpath?: string; // 仓库中的子路径\n localPath?: string; // 本地绝对路径 (local类型必须)\n installedAt: string; // 安装时间 (ISO 8601格式)\n}\n```\n\n资料来源：[src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)\n\n---\n\n## 版本历史\n\n| 版本 | 发布日期 | 变更内容 |\n|------|----------|----------|\n| 1.5.0 | 2026-01-17 | 新增 `openskills update` 命令，支持从源代码刷新已安装技能 |\n| 1.5.0 | 2026-01-17 | 新增源元数据跟踪功能，为更新提供可靠依据 |\n\n资料来源：[CHANGELOG.md](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)\n\n---\n\n## 最佳实践\n\n1. **定期更新**：建议在开始新项目前运行 `npx openskills update` 获取最新技能\n2. **版本控制**：将技能目录加入版本控制可以追踪技能版本变化\n3. **本地开发**：使用符号链接（symlink）可以在开发时实时测试技能更新\n4. **批量处理**：不传参数时自动更新所有技能，适合定期维护\n\n---\n\n\n\n## SKILL.md格式规范\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/my-first-skill/SKILL.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/SKILL.md)\n- [examples/my-first-skill/references/skill-format.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/references/skill-format.md)\n- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)\n- [README.md](https://github.com/numman-ali/openskills/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)\n \n\n# SKILL.md格式规范\n\n## 概述\n\nSKILL.md是OpenSkills项目的核心技能描述格式，它采用Anthropic提出的智能体技能（Agent Skills）规范。该格式基于Markdown语法，结合YAML元数据前端块，用于定义AI编码智能体在执行特定任务时应加载的技能指令和资源文件。\n\nSKILL.md的设计理念是实现**渐进式披露（Progressive Disclosure）**，即根据任务需要动态加载不同详细程度的技能信息，而非一次性将所有内容加载到智能体上下文中。这种方式有效控制了上下文窗口的占用，同时保证了技能使用的灵活性。\n\n资料来源：[examples/my-first-skill/references/skill-format.md:1-25]()\n\n## 文件结构\n\n### 最小化结构\n\n一个基础的SKILL.md技能只需要一个目录和主文件：\n\n```\nmy-skill/\n└── SKILL.md\n```\n\n### 完整结构\n\n包含完整资源的技能应包含以下目录结构：\n\n```\nskill-name/\n├── SKILL.md # 核心指令文档（约2,000字）\n├── references/ # 参考文档目录\n│ ├── api-docs.md # API详细文档\n│ └── guide.md # 使用指南\n├── scripts/ # 可执行脚本目录\n│ ├── helper.sh # Shell脚本\n│ └── process.py # Python脚本\n└── assets/ # 静态资源目录\n └── template.pdf # 模板文件\n```\n\n资料来源：[examples/my-first-skill/references/skill-format.md:60-75]()\n\n### 目录职责\n\n| 目录 | 用途 | 加载到上下文 | 计数限制 |\n|------|------|-------------|---------|\n| `references/` | 详细API文档、数据库schema、指南 | 按需加载 | 无限制 |\n| `scripts/` | Python/Bash等可执行代码 | 不加载 | 不计入字数 |\n| `assets/` | 模板、图片等输出文件 | 不加载 | 不计入字数 |\n\n资料来源：[examples/my-first-skill/references/skill-format.md:45-60]()\n\n## YAML前端块规范\n\n每个SKILL.md文件必须以YAML前端块开始，该块用于定义技能的基本元数据。\n\n### 必需字段\n\n```yaml\n---\nname: skill-name # 必需：连字符分隔的标识符\ndescription: When to use # 必需：1-2句话的第三人称描述\n---\n```\n\n### 字段说明\n\n| 字段 | 类型 | 必填 | 格式要求 | 示例 |\n|------|------|------|----------|------|\n| `name` | string | 是 | 小写字母、连字符 | `pdf-editor`、`git-workflow` |\n| `description` | string | 是 | 第三人称、1-2句 | `Comprehensive PDF manipulation toolkit...` |\n\n### 命名规范\n\n- 仅使用小写字母\n- 使用连字符（`-`）分隔单词\n- 避免使用下划线或驼峰命名\n- 名称应简洁且具有描述性\n\n资料来源：[examples/my-first-skill/references/skill-format.md:3-12]()\n\n## Markdown正文规范\n\n### 语气要求\n\n正文内容应使用**祈使句/不定式形式**编写，避免使用第二人称。\n\n**推荐写法：**\n```markdown\nTo accomplish X, execute Y\nLoad this skill when Z\nSee references/guide.md for details\n```\n\n**应避免的写法：**\n```markdown\nYou should do X\nIf you need Y, you should...\nWhen you want Z, you can...\n```\n\n### 段落结构\n\n建议按以下顺序组织内容：\n\n1. **标题** - 使用技能名称作为主标题\n2. **目的说明** - 简要说明技能用途\n3. **使用场景** - 何时应加载此技能\n4. **执行步骤** - 完成任务的具体指令\n5. **资源引用** - 指向bundled resources的链接\n\n资料来源：[examples/my-first-skill/SKILL.md:1-40]()\n\n## 渐进式披露机制\n\nSKILL.md采用三级渐进式信息披露机制，智能体根据任务需求动态加载不同层级的信息。\n\n```mermaid\ngraph TD\n A[任务请求] --> B{技能匹配}\n B -->|匹配成功| C[Level 1: 元数据]\n B -->|需要核心指令| D[Level 2: SKILL.md]\n B -->|需要详细文档| E[Level 3: Resources]\n \n C --> F[name + description]\n D --> G[核心指令步骤]\n E --> H[references/]\n E --> I[scripts/]\n \n style C fill:#90EE90\n style D fill:#87CEEB\n style E fill:#DDA0DD\n```\n\n### 三级加载机制\n\n| 级别 | 内容 | 何时加载 | 上下文占用 |\n|------|------|----------|-----------|\n| **Level 1** | 元数据（name + description） | 始终在上下文中 | 极小 |\n| **Level 2** | SKILL.md核心指令 | 技能被请求时 | 中等 |\n| **Level 3** | resources资源文件 | 按需加载 | 可变 |\n\n资料来源：[examples/my-first-skill/references/skill-format.md:20-30]()\n\n## 文件大小限制\n\n为保证技能加载效率和上下文管理，OpenSkills对不同类型的文件设定了大小限制：\n\n| 文件类型 | 建议大小 | 限制 | 说明 |\n|----------|----------|------|------|\n| SKILL.md | ~2,000字 | < 5,000字 | 核心指令应保持简洁 |\n| references/ | 无限制 | 无限制 | 按需选择性加载 |\n| scripts/ | 可执行 | 不计数 | 不加载到上下文 |\n| assets/ | 无限制 | 无限制 | 仅作为输出使用 |\n\n资料来源：[examples/my-first-skill/references/skill-format.md:35-50]()\n\n## 资源解析机制\n\n当技能被加载时，OpenSkills会提供基础目录路径，技能内的相对路径应从该基础目录解析。\n\n### 资源解析示例\n\n```\nBase directory: /path/to/my-first-skill\n```\n\n相对路径解析规则：\n\n| 相对路径 | 解析结果 |\n|----------|----------|\n| `references/skill-format.md` | `/path/to/my-first-skill/references/skill-format.md` |\n| `scripts/helper.sh` | `/path/to/my-first-skill/scripts/helper.sh` |\n| `assets/template.pdf` | `/path/to/my-first-skill/assets/template.pdf` |\n\n资料来源：[examples/my-first-skill/SKILL.md:55-65]()\n\n## AGENTS.md集成\n\nOpenSkills通过生成特定的XML格式实现与AGENTS.md的集成。技能信息以``块的形式嵌入到AGENTS.md中。\n\n### 生成格式\n\n```xml\n\n\npdf\nComprehensive PDF manipulation toolkit...\nplugin\n\n\n```\n\n### 使用方式\n\n当AI智能体需要使用技能时，应通过以下命令加载：\n\n```bash\nnpx openskills read \n```\n\n对于多个技能，使用逗号分隔：\n\n```bash\nnpx openskills read skill-one,skill-two\n```\n\n资料来源：[src/utils/agents-md.ts:1-50]()\n\n## 最佳实践\n\n### 编写规范\n\n1. **使用祈使语气** - 直接描述操作而非建议\n2. **保持简洁** - SKILL.md应聚焦核心指令，细节移至references\n3. **明确触发条件** - 说明何时应加载此技能\n4. **引用资源** - 使用相对路径引用bundled resources\n\n### 结构建议\n\n```\nskill/\n├── SKILL.md # 简洁的核心指令\n├── references/ # 详细文档\n│ ├── api.md # API参考\n│ └── schemas.md # 数据结构\n└── scripts/ # 辅助脚本\n```\n\n### 常见错误\n\n| 错误类型 | 问题 | 修正方式 |\n|----------|------|----------|\n| 第二人称 | \"You should do X\" | 改为 \"To do X, execute Y\" |\n| 过长内容 | SKILL.md超过5000字 | 将详细文档移至references/ |\n| 路径错误 | 使用绝对路径 | 使用相对于基础目录的相对路径 |\n| 命名不当 | `mySkillName` | 改为 `my-skill-name` |\n\n资料来源：[examples/my-first-skill/SKILL.md:30-50]()\n\n## 完整示例\n\n```markdown\n---\nname: pdf-editor\ndescription: Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms.\n---\n\n# PDF Editor Skill\n\n## Purpose\n\nThis skill provides comprehensive PDF manipulation capabilities.\n\n## When to Use\n\nLoad this skill when:\n- Extracting text from PDF documents\n- Merging or splitting PDF files\n- Creating new PDFs from scratch\n- Working with PDF forms\n\n## Instructions\n\nTo accomplish PDF tasks:\n\n1. Install dependencies: `pip install pypdf2`\n2. Extract text using scripts/extract_text.py\n3. Use references/api-docs.md for detailed API information\n\n## Bundled Resources\n\n- `references/api-docs.md` - Complete API documentation\n- `references/format-guide.md` - PDF format specifications\n- `scripts/extract_text.py` - Text extraction utility\n- `scripts/merge_pdfs.py` - PDF merging tool\n\n## Best Practices\n\n- Always verify PDF encoding before processing\n- Use batch processing for large document sets\n- Handle password-protected files with appropriate permissions\n```\n\n资料来源：[examples/my-first-skill/references/skill-format.md:1-95]()\n\n## 命令行工具集成\n\nOpenSkills提供了一系列命令行工具用于管理SKILL.md格式的技能：\n\n| 命令 | 功能 |\n|------|------|\n| `npx openskills install ` | 从GitHub或本地路径安装技能 |\n| `npx openskills sync` | 同步技能列表到AGENTS.md |\n| `npx openskills list` | 列出已安装的技能 |\n| `npx openskills read ` | 读取技能内容供智能体使用 |\n| `npx openskills update` | 从源更新已安装的技能 |\n| `npx openskills remove ` | 移除指定技能 |\n\n资料来源：[README.md:50-80]()\n\n## 技术实现\n\n### 文件解析流程\n\n```mermaid\ngraph LR\n A[SKILL.md文件] --> B[YAML解析器]\n B --> C[YAML前端块]\n C --> D{验证必需字段}\n D -->|name| E[提取技能名称]\n D -->|description| F[提取描述]\n B --> G[Markdown解析器]\n G --> H[核心指令内容]\n H --> I[上下文注入]\n \n style A fill:#f9f\n style I fill:#9f9\n```\n\n### 元数据存储\n\n技能元数据以JSON格式存储在`.claude/skills/`或`.agent/skills/`目录中：\n\n```json\n{\n \"source\": \"anthropics/skills\",\n \"sourceType\": \"git\",\n \"repoUrl\": \"https://github.com/anthropics/skills\",\n \"subpath\": \"pdf-editor\",\n \"installedAt\": \"2025-01-15T10:30:00Z\"\n}\n```\n\n资料来源：[src/commands/install.ts:1-50]()\n\n\n---\n\n\n\n## 数据存储与管理\n\n### 相关页面\n\n相关主题：[install命令详解](#page-install-command), [update命令详解](#page-update-command)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/utils/dirs.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/dirs.ts)\n- [src/utils/skills.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skills.ts)\n- [src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)\n- [src/utils/skill-names.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-names.ts)\n- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n- [src/commands/sync.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/sync.ts)\n \n\n# 数据存储与管理\n\nOpenSkills 的数据存储与管理模块负责管理技能的安装位置、元数据持久化、技能发现机制以及与 `AGENTS.md` 的同步功能。该模块确保技能能够被正确安装、定位、追踪来源，并在 AI 代理需要时提供可用技能列表。\n\n## 目录结构\n\nOpenSkills 采用分层目录结构存储技能数据，支持项目级别和全局级别的安装。\n\n```mermaid\ngraph TD\n A[用户项目] --> B[.claude/skills/]\n A --> C[.agent/skills/]\n D[用户主目录] --> E[~/.claude/skills/]\n B --> F[skill-name/]\n C --> G[skill-name/]\n E --> H[skill-name/]\n F --> I[SKILL.md]\n F --> J[metadata.json]\n G --> K[SKILL.md]\n G --> K2[metadata.json]\n H --> L[SKILL.md]\n H --> L2[metadata.json]\n```\n\n### 目录层级与优先级\n\n| 位置 | 路径 | 说明 | 优先级 |\n|------|------|------|--------|\n| 项目目录 | `./.claude/skills/` | 项目本地安装（默认） | 最高 |\n| 通用目录 | `./.agent/skills/` | 使用 `--universal` 参数 | 高 |\n| 用户目录 | `~/.claude/skills/` | 全局安装（需 `-g` 参数） | 低 |\n\n资料来源：[src/utils/dirs.ts]() \n\n### 目录路径解析\n\n```typescript\n// 技能目录名称常量\nexport const SKILLS_DIR_NAME = '.claude';\nexport const SKILLS_SUBDIR = 'skills';\n\n// 获取技能安装根目录\nexport function getSkillsRoot(isGlobal: boolean): string {\n if (isGlobal) {\n return join(homedir(), SKILLS_DIR_NAME, SKILLS_SUBDIR);\n }\n return join(process.cwd(), SKILLS_DIR_NAME, SKILLS_SUBDIR);\n}\n```\n\n资料来源：[src/utils/dirs.ts:1-20]()\n\n## 元数据管理\n\n每个已安装的技能都包含一个 `metadata.json` 文件，用于记录技能的来源和安装信息。\n\n### 元数据结构\n\n```typescript\ninterface SkillSourceMetadata {\n source: string; // 原始安装源\n sourceType: 'git' | 'local'; // 源类型\n repoUrl?: string; // Git 仓库 URL（git 类型）\n subpath?: string; // 仓库内子路径（git 类型）\n localPath?: string; // 本地路径（local 类型）\n installedAt: string; // ISO 格式安装时间\n}\n```\n\n资料来源：[src/commands/install.ts:80-95]()\n\n### 元数据写入\n\n```typescript\nfunction writeSkillMetadata(skillPath: string, metadata: SkillSourceMetadata): void {\n const metadataPath = join(skillPath, 'metadata.json');\n writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));\n}\n```\n\n资料来源：[src/commands/install.ts:120-125]()\n\n### 元数据用途\n\n元数据主要用于以下场景：\n\n1. **更新技能**：通过 `openskills update` 命令重新拉取最新版本\n2. **来源追溯**：了解技能的原始安装位置\n3. **冲突检测**：避免与 Claude Code 插件市场产生冲突\n\n资料来源：[src/commands/install.ts:127-145]()\n\n## 技能发现机制\n\n技能发现是定位系统中所有已安装技能的核心功能。\n\n### 技能发现流程\n\n```mermaid\ngraph TD\n A[开始查找技能] --> B[检查 .claude/skills/]\n B --> C{存在?}\n C -->|是| D[遍历子目录]\n C -->|否| E[返回空列表]\n D --> F{包含 SKILL.md?}\n F -->|是| G[添加技能到列表]\n F -->|否| H[跳过目录]\n G --> I{还有更多目录?}\n I -->|是| D\n I -->|否| J[检查全局目录 ~/.claude/skills/]\n J --> K{存在?}\n K -->|是| L[遍历子目录]\n K -->|否| M[返回所有发现的技能]\n L --> F2{SKILL.md?}\n F2 -->|是| G2[添加技能到列表]\n F2 -->|否| H2[跳过]\n G2 --> I2{还有更多?}\n I2 -->|是| L\n I2 -->|否| M[返回技能列表]\n```\n\n### 技能查找实现\n\n```typescript\nexport function findAllSkills(): Skill[] {\n const skills: Skill[] = [];\n \n // 检查项目目录\n const projectDir = join(process.cwd(), '.claude', 'skills');\n if (existsSync(projectDir)) {\n skills.push(...findSkillsInDir(projectDir, 'project'));\n }\n \n // 检查全局目录\n const globalDir = join(homedir(), '.claude', 'skills');\n if (existsSync(globalDir)) {\n skills.push(...findSkillsInDir(globalDir, 'global'));\n }\n \n return skills;\n}\n```\n\n资料来源：[src/utils/skills.ts:10-35]()\n\n### 技能目录遍历\n\n```typescript\nfunction findSkillsInDir(baseDir: string, location: 'project' | 'global'): Skill[] {\n const skills: Skill[] = [];\n const entries = readdirSync(baseDir, { withFileTypes: true });\n \n for (const entry of entries) {\n if (!entry.isDirectory()) continue;\n \n const skillPath = join(baseDir, entry.name);\n const skillMdPath = join(skillPath, 'SKILL.md');\n \n // 跳过符号链接指向不存在的路径\n if (lstatSync(skillPath).isSymbolicLink() && !existsSync(skillPath)) {\n continue;\n }\n \n if (existsSync(skillMdPath)) {\n const skill = parseSkillInfo(skillPath, location);\n if (skill) {\n skills.push(skill);\n }\n }\n }\n \n return skills;\n}\n```\n\n资料来源：[src/utils/skills.ts:40-65]()\n\n### 符号链接处理\n\nOpenSkills 在本地开发工作流中支持符号链接。被破坏的符号链接会被优雅地跳过，不会导致错误：\n\n```typescript\n// 跳过断裂的符号链接\nif (lstatSync(skillPath).isSymbolicLink() && !existsSync(skillPath)) {\n continue;\n}\n```\n\n资料来源：[src/utils/skills.ts:50-52]()\n\n## 技能信息解析\n\n### SKILL.md 文件解析\n\n```typescript\nexport function parseSkillInfo(skillPath: string, location: 'project' | 'global'): Skill | null {\n const skillMdPath = join(skillPath, 'SKILL.md');\n const content = readFileSync(skillMdPath, 'utf-8');\n \n // 解析 YAML frontmatter\n const frontmatterMatch = content.match(/^---\\n([\\s\\S]*?)\\n---/);\n if (!frontmatterMatch) {\n return null;\n }\n \n const frontmatter = parseFrontmatter(frontmatterMatch[1]);\n const name = frontmatter.name || basename(skillPath);\n const description = frontmatter.description || '';\n \n return { name, description, path: skillPath, location };\n}\n```\n\n资料来源：[src/utils/skills.ts:70-95]()\n\n### Frontmatter 解析\n\n```typescript\nfunction parseFrontmatter(yaml: string): Record {\n const result: Record = {};\n const lines = yaml.split('\\n');\n \n for (const line of lines) {\n const match = line.match(/^(\\w+):\\s*(.+)$/);\n if (match) {\n result[match[1]] = match[2].trim();\n }\n }\n \n return result;\n}\n```\n\n资料来源：[src/utils/skills.ts:100-115]()\n\n## AGENTS.md 同步管理\n\n`AGENTS.md` 是 AI 代理读取技能列表的关键文件，sync 命令负责维护其中的技能列表。\n\n### 同步数据流\n\n```mermaid\ngraph LR\n A[技能目录] --> B[findAllSkills]\n B --> C[Skill 对象数组]\n C --> D[generateSkillsXml]\n D --> E[ XML]\n E --> F[replaceSkillsSection]\n F --> G[AGENTS.md 文件]\n```\n\n### 技能 XML 生成\n\n```typescript\nexport function generateSkillsXml(skills: Skill[]): string {\n const skillTags = skills\n .map(\n (s) => `\n${s.name}\n${s.description}\n${s.location}\n`\n )\n .join('\\n\\n');\n \n // 完整的 skills_system XML 结构\n return `\n...\n\n\n${skillTags}\n\n\n`;\n}\n```\n\n资料来源：[src/utils/agents-md.ts:50-80]()\n\n### 当前技能解析\n\n```typescript\nexport function parseCurrentSkills(content: string): string[] {\n const skillNames: string[] = [];\n const skillRegex = /[\\s\\S]*?([^<]+)<\\/name>[\\s\\S]*?<\\/skill>/g;\n \n let match;\n while ((match = skillRegex.exec(content)) !== null) {\n skillNames.push(match[1].trim());\n }\n \n return skillNames;\n}\n```\n\n资料来源：[src/utils/agents-md.ts:85-100]()\n\n### 交互式同步选择\n\nsync 命令支持交互式选择界面：\n\n```typescript\n// 排序：项目级别优先\nconst sorted = skills.sort((a, b) => {\n if (a.location !== b.location) {\n return a.location === 'project' ? -1 : 1;\n }\n return a.name.localeCompare(b.name);\n});\n\n// 预选当前文件中已存在的技能\nconst choices = sorted.map((skill) => ({\n name: `${skill.name} ${skill.location === 'project' ? '(project)' : '(global)'}`,\n value: skill.name,\n description: skill.description.slice(0, 70),\n checked: currentSkills.includes(skill.name) || \n (currentSkills.length === 0 && skill.location === 'project'),\n}));\n```\n\n资料来源：[src/commands/sync.ts:45-65]()\n\n## 技能来源类型\n\n### Git 来源\n\n从 GitHub 仓库安装的技能存储以下信息：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `source` | 原始安装命令参数 | `anthropics/skills/pdf` |\n| `sourceType` | 固定值 `'git'` | `git` |\n| `repoUrl` | 完整仓库 URL | `https://github.com/anthropics/skills` |\n| `subpath` | 仓库内的子目录路径 | `pdf` |\n| `installedAt` | ISO 时间戳 | `2025-10-27T10:30:00.000Z` |\n\n资料来源：[src/commands/install.ts:80-95]()\n\n### 本地来源\n\n从本地路径安装的技能存储以下信息：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `source` | 原始安装命令参数 | `./my-skills/pdf` |\n| `sourceType` | 固定值 `'local'` | `local` |\n| `localPath` | 绝对路径 | `/Users/dev/my-skills/pdf` |\n| `installedAt` | ISO 时间戳 | `2025-10-27T10:30:00.000Z` |\n\n资料来源：[src/commands/install.ts:97-107]()\n\n### 元数据构建\n\n```typescript\nfunction buildMetadataFromSource(\n sourceInfo: InstallSourceInfo,\n skillDir: string,\n repoDir: string\n): SkillSourceMetadata {\n if (sourceInfo.sourceType === 'local') {\n return buildLocalMetadata(sourceInfo, skillDir);\n }\n \n const subpath = relative(repoDir, skillDir);\n const normalizedSubpath = subpath === '' ? '' : subpath;\n return buildGitMetadata(sourceInfo, normalizedSubpath);\n}\n```\n\n资料来源：[src/commands/install.ts:70-85]()\n\n## 技能更新机制\n\n更新功能利用存储的元数据重新拉取技能：\n\n```mermaid\ngraph TD\n A[update 命令] --> B[读取 metadata.json]\n B --> C{检查 sourceType}\n C -->|local| D[验证 localPath 存在]\n C -->|git| E[克隆 repoUrl 仓库]\n D --> F{SKILL.md 存在?}\n E --> G[复制文件到技能目录]\n F -->|是| H[从 localPath 复制]\n F -->|否| I[跳过并警告]\n G --> J[更新 installedAt]\n H --> J\n J --> K[更新完成]\n I --> K\n```\n\n### 本地技能更新\n\n```typescript\nif (metadata.sourceType === 'local') {\n const localPath = metadata.localPath;\n if (!existsSync(localPath)) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (local source missing)`));\n continue;\n }\n if (!existsSync(join(localPath, 'SKILL.md'))) {\n console.log(chalk.yellow(`Skipped: ${skill.name} (SKILL.md missing at local source)`));\n continue;\n }\n updateSkillFromDir(skill.path, localPath);\n writeSkillMetadata(skill.path, { ...metadata, installedAt: new Date().toISOString() });\n}\n```\n\n资料来源：[src/commands/update.ts:10-35]()\n\n### Git 技能更新\n\n```typescript\nconst tempDir = join(homedir(), `.openskills-temp-${Date.now()}`);\nmkdirSync(tempDir, { recursive: true });\n\n// 克隆仓库（浅克隆，仅获取最新）\nexecSync(`git clone --depth 1 --quiet \"${metadata.repoUrl}\" \"${tempDir}/repo\"`, { stdio: 'pipe' });\n\nconst repoDir = join(tempDir, 'repo');\nconst subpath = metadata.subpath && metadata.subpath !== '.' ? metadata.subpath : '';\nconst sourceDir = subpath ? join(repoDir, subpath) : repoDir;\n```\n\n资料来源：[src/commands/update.ts:40-55]()\n\n## 数据模型汇总\n\n### Skill 接口\n\n```typescript\ninterface Skill {\n name: string; // 技能名称（必需）\n description: string; // 技能描述（必需）\n path: string; // 技能文件系统路径\n location: 'project' | 'global'; // 安装位置\n}\n```\n\n### InstallSourceInfo 接口\n\n```typescript\ninterface InstallSourceInfo {\n source: string;\n sourceType: 'git' | 'local';\n repoUrl?: string;\n localPath?: string;\n isUrl: boolean;\n skillName: string;\n skillDir: string;\n}\n```\n\n### AGENTS.md 输出结构\n\n```xml\n\n\n## Available Skills\n\n\n\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.\n...\n\n\n\n\npdf\nComprehensive PDF manipulation toolkit...\nproject\n\n\n\n\n\n```\n\n资料来源：[src/utils/agents-md.ts:1-50]()\n\n## 文件清单\n\n| 文件路径 | 职责 |\n|---------|------|\n| `src/utils/dirs.ts` | 定义目录路径常量和获取函数 |\n| `src/utils/skills.ts` | 技能发现、解析、遍历逻辑 |\n| `src/utils/skill-metadata.ts` | 元数据读写操作 |\n| `src/utils/skill-names.ts` | 技能名称相关工具函数 |\n| `src/commands/install.ts` | 安装命令中的元数据构建逻辑 |\n| `src/commands/sync.ts` | AGENTS.md 同步命令实现 |\n| `src/utils/agents-md.ts` | AGENTS.md XML 生成和解析 |\n\n## 最佳实践\n\n1. **项目级别优先**：默认使用项目级别安装，便于版本控制和团队协作\n2. **元数据完整性**：安装后检查 `metadata.json` 确保信息正确\n3. **符号链接开发**：本地开发时使用符号链接避免重复复制\n4. **定期同步**：更新技能后执行 `npx openskills sync` 保持 AGENTS.md 最新\n5. **冲突预防**：使用 `--universal` 参数避免与 Claude Code 插件市场冲突\n\n---\n\n\n\n## 贡献指南\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/numman-ali/openskills/blob/main/CONTRIBUTING.md)\n- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)\n- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)\n- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)\n- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)\n \n\n# 贡献指南\n\n本文档为希望参与 OpenSkills 项目开发的贡献者提供完整的开发指南，涵盖开发环境配置、代码规范、测试流程以及提交流程等内容。\n\n## 项目概述\n\nOpenSkills 是一个跨平台的多代理技能管理系统，兼容 Anthropic 的 Agent Skills 规范，支持 Claude Code、Cursor、Windsurf、Aider、Codex 等多种 AI 编码代理工具。项目使用 Node.js 20.6.0+ 作为运行时环境，通过 TypeScript 实现，依赖包括 Commander.js 用于 CLI 框架、Chalk 用于终端着色、Ora 用于加载动画、Inquirer 用于交互式提示。 资料来源：[package.json:1-25]()\n\n## 开发环境配置\n\n### 环境要求\n\n| 组件 | 最低版本 | 说明 |\n|------|---------|------|\n| Node.js | 20.6.0+ | 运行时环境 |\n| Git | 任意版本 | 用于代码版本管理和依赖安装 |\n| npm | 与 Node.js 捆绑 | 包管理器 |\n\n资料来源：[package.json:23]()\n\n### 安装步骤\n\n```bash\n# 克隆项目\ngit clone https://github.com/numman-ali/openskills.git\ncd openskills\n\n# 安装依赖\nnpm install\n```\n\n### 本地链接与测试\n\n开发过程中可以使用 `npm link` 将本地包链接到全局，使 CLI 命令在本地可用：\n\n```bash\nnpm link\n```\n\n链接后即可在任意目录下使用 `openskills` 命令：\n\n```bash\nnpx openskills install anthropics/skills/pdf-editor --project\nnpx openskills sync\nnpx openskills read pdf-editor\n```\n\n资料来源：[CONTRIBUTING.md:1-10]()\n\n## 项目结构\n\n```\nopenskills/\n├── src/\n│ ├── cli.ts # CLI 主入口，定义命令行接口\n│ ├── commands/ # 各子命令实现\n│ │ ├── install.ts # 安装技能命令\n│ │ └── update.ts # 更新技能命令\n│ ├── utils/ # 共享工具函数\n│ │ └── agents-md.ts # AGENTS.md 生成工具\n│ └── types.ts # TypeScript 类型定义\n├── tests/\n│ └── utils/ # 单元测试\n├── package.json\n├── tsconfig.json\n└── vitest.config.ts\n```\n\n### 核心模块职责\n\n| 模块 | 职责 |\n|------|------|\n| cli.ts | 定义所有 CLI 命令及参数解析 |\n| commands/install.ts | 处理技能安装逻辑，包括本地路径、私有仓库、GitHub 等多种来源 |\n| commands/update.ts | 实现技能更新逻辑，支持从源仓库拉取最新内容 |\n| utils/agents-md.ts | 生成符合规范的 `` XML 区块 |\n| types.ts | 定义 Skill、SkillSourceMetadata 等核心数据结构 |\n\n资料来源：[CONTRIBUTING.md:18-24]()\n\n## 开发命令\n\n### 运行测试\n\n```bash\n# 运行所有测试\nnpm run test\n\n# 监听模式（文件变化自动重跑）\nnpm run test:watch\n\n# 生成覆盖率报告\nnpm run test:coverage\n```\n\nOpenSkills 使用 Vitest 作为测试框架，测试文件位于 `tests/utils/` 目录。测试覆盖包括符号链接检测、YAML 解析、install 命令集成测试、sync 命令集成测试以及完整的 E2E CLI 工作流测试。\n\n资料来源：[CONTRIBUTING.md:4-6]()\n\n### 构建项目\n\n```bash\nnpm run build\n```\n\n构建输出通过 tsup 处理，将 TypeScript 编译为 JavaScript 并生成类型声明文件。\n\n### 代码检查与格式化\n\n项目使用 TypeScript 编译器进行类型检查：\n\n```bash\nnpm run lint # 代码风格检查\nnpm run format # 代码格式化\n```\n\n## CLI 命令参考\n\n### 主要命令列表\n\n| 命令 | 功能 | 主要参数 |\n|------|------|----------|\n| `npx openskills install ` | 从 GitHub、本地路径或私有仓库安装技能 | `-g, --global`、`-u, --universal`、`-y, --yes` |\n| `npx openskills sync` | 更新 AGENTS.md 中的技能列表 | `-y, --yes`、`-o, --output ` |\n| `npx openskills list` | 列出所有已安装的技能 | - |\n| `npx openskills read ` | 读取技能内容输出到终端 | - |\n| `npx openskills update [names...]` | 更新已安装的技能 | - |\n| `npx openskills manage` | 交互式管理技能（删除） | - |\n| `npx openskills remove ` | 删除指定技能 | - |\n\n资料来源：[src/cli.ts:19-46]()\n\n### 安装命令详解\n\n```bash\n# 从 GitHub 安装\nnpx openskills install anthropics/skills\n\n# 从本地路径安装\nnpx openskills install ./local-skills/my-skill\n\n# 从私有仓库安装\nnpx openskills install git@github.com:your-org/private-skills.git\n\n# 全局安装\nnpx openskills install anthropics/skills --global\n\n# 通用模式（多代理环境）\nnpx openskills install anthropics/skills --universal\n\n# 非交互模式（CI/CD）\nnpx openskills install anthropics/skills --yes\n```\n\n安装流程会创建符号链接到指定目录（默认为 `./.claude/skills/`），并生成元数据文件记录安装来源信息，便于后续更新。\n\n资料来源：[CONTRIBUTING.md:7-10]()\n\n### 同步命令详解\n\n```bash\n# 同步到默认 AGENTS.md\nnpx openskills sync\n\n# 指定输出文件\nnpx openskills sync -o .ruler/AGENTS.md\n\n# 非交互模式\nnpx openskills sync --yes\n```\n\nsync 命令会扫描已安装技能的 SKILL.md 文件，提取 name、description、location 等元数据，生成符合 Anthropic 规范的 `` XML 区块并写入目标文件。\n\n资料来源：[src/utils/agents-md.ts:45-70]()\n\n## 代码提交规范\n\n### 提交信息格式\n\n```\n<类型>: <简短描述>\n\n[可选的详细说明]\n```\n\n### 提交类型\n\n| 类型 | 用途 |\n|------|------|\n| `feat` | 新功能 |\n| `fix` | 错误修复 |\n| `docs` | 文档更新 |\n| `test` | 测试相关 |\n| `refactor` | 代码重构 |\n| `chore` | 构建或辅助工具变更 |\n\n### 提交前检查清单\n\n- [ ] 所有测试通过 `npm run test`\n- [ ] 代码符合 TypeScript 类型检查\n- [ ] 新功能包含相应的测试用例\n- [ ] 更新了相关文档（如有 API 变更）\n\n## 问题报告指南\n\n报告问题时，请确保包含以下信息：\n\n| 信息项 | 说明 |\n|--------|------|\n| 问题类型 | Bug 报告或功能请求 |\n| 复现步骤 | 详细的操作步骤 |\n| 版本信息 | `npx openskills --version` 输出 |\n| Node.js 版本 | `node --version` 输出 |\n| 预期行为 | 希望看到的正确行为 |\n| 实际行为 | 当前观察到的行为 |\n\n资料来源：[CONTRIBUTING.md:26-32]()\n\n## 许可协议\n\n通过向 OpenSkills 项目提交贡献，您同意您的贡献将按照 Apache 2.0 许可证授权。贡献者无需签署任何额外的贡献者许可协议。\n\n资料来源：[CONTRIBUTING.md:34]()\n\n## 技能开发指南\n\nOpenSkills 兼容 Anthropic 的 SKILL.md 格式。开发新技能时，需要遵循以下结构：\n\n```bash\nmy-skill/\n├── SKILL.md # 主技能文件（必需）\n├── references/ # 参考文档目录\n├── scripts/ # 可执行脚本目录\n└── assets/ # 静态资源目录\n```\n\n### SKILL.md 格式要求\n\n```yaml\n---\nname: skill-name # 必需：小写连字符格式\ndescription: 何时使用此技能 # 必需：1-2句话描述\n---\n```\n\n### 技能安装与测试\n\n```bash\n# 本地开发链接\ngit clone git@github.com:your-org/my-skills.git ~/dev/my-skills\nmkdir -p .claude/skills\nln -s ~/dev/my-skills/my-skill .claude/skills/my-skill\n\n# 测试技能\nnpx openskills read my-skill\n```\n\n资料来源：[CONTRIBUTING.md:11-17]()\n\n## 技术架构流程\n\n### 技能安装流程\n\n```mermaid\ngraph TD\n A[用户执行 install 命令] --> B{来源类型}\n B -->|GitHub| C[解析 org/repo 格式]\n B -->|本地路径| D[验证本地目录存在]\n B -->|SSH URL| E[使用系统 SSH 密钥克隆]\n \n C --> F[克隆远程仓库]\n D --> G[复制本地技能]\n E --> F\n \n F --> H[扫描仓库中的 SKILL.md]\n G --> H\n \n H --> I[写入元数据]\n I --> J[创建符号链接]\n J --> K[安装完成]\n \n H -->|多个技能| I\n```\n\n### 技能更新流程\n\n```mermaid\ngraph TD\n A[用户执行 update 命令] --> B{技能元数据类型}\n B -->|local| C[验证本地路径存在]\n B -->|git| D[克隆源仓库]\n \n C --> E[从本地路径复制更新]\n D --> F[从子路径提取技能]\n \n E --> G[更新技能文件]\n F --> G\n \n G --> H[更新元数据 installedAt]\n H --> I[更新完成]\n```\n\n更新流程会检查本地源路径是否存在、SKILL.md 文件是否完整，然后执行文件同步并更新元数据中的安装时间戳。\n\n资料来源：[src/commands/update.ts:1-30]()\n\n## 获取帮助\n\n| 渠道 | 用途 |\n|------|------|\n| GitHub Issues | 功能请求、Bug 报告 |\n| GitHub Discussions | 贡献相关问题、架构讨论 |\n| Anthropic 文档 | SKILL.md 规范参考 |\n\n资料来源：[CONTRIBUTING.md:33-37]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：numman-ali/openskills\n\n摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：[BUG] `--universal` installs to `.agent/` not `.agents/`。\n\n## 1. 安装坑 · 来源证据：[BUG] `--universal` installs to `.agent/` not `.agents/`\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] `--universal` installs to `.agent/` not `.agents/`\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c384eba59a4f4177ace0a344b94400dc | https://github.com/numman-ali/openskills/issues/84 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[FEATURE] add cli option --skills=name1,name2 to only install selected skill from github repo non-interactivelly\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] add cli option --skills=name1,name2 to only install selected skill from github repo non-interactivelly\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ec834575446429c96f39db392b81751 | https://github.com/numman-ali/openskills/issues/53 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：[Feature]: Read skill.json from source repos for install and sync\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Read skill.json from source repos for install and sync\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8752343cfb2d4231a5eb42f242806a31 | https://github.com/numman-ali/openskills/issues/81 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：[BUG] Update command doesn't update all paths\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Update command doesn't update all paths\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8f8a414bbe634c229bf200f45014fc57 | https://github.com/numman-ali/openskills/issues/75 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：[BUG] Clone failed\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Clone failed\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_59fb2f76bd674cf2bba0efb5a57843bd | https://github.com/numman-ali/openskills/issues/85 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[BUG] EEXIST when overwriting an existing skill during installation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] EEXIST when overwriting an existing skill during installation\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ac382f17e8a744b58f7d0860617a2f19 | https://github.com/numman-ali/openskills/issues/73 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v1.2.0 - Universal Skills Support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.0 - Universal Skills Support\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_31f11650e29a4e7c9fbd4ff026d577d0 | https://github.com/numman-ali/openskills/releases/tag/v1.2.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v1.2.1 - Documentation Fixes\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.1 - Documentation Fixes\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bb36323b2acd470bb0382644fddfde5f | https://github.com/numman-ali/openskills/releases/tag/v1.2.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v1.5.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.5.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7fab452932ab47e18a1d915b327b22d2 | https://github.com/numman-ali/openskills/releases/tag/v1.5.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1083829346 | https://github.com/numman-ali/openskills | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1083829346 | https://github.com/numman-ali/openskills | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1083829346 | https://github.com/numman-ali/openskills | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1083829346 | https://github.com/numman-ali/openskills | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：[BUG] Path Resolution & Sandbox Access Conflict for Global OpenSkills on macOS\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Path Resolution & Sandbox Access Conflict for Global OpenSkills on macOS\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_92230b03d1ec434694ad8d2e5ee6441f | https://github.com/numman-ali/openskills/issues/87 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：[FEATURE] Explicit local-first precedence for synced skills\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Explicit local-first precedence for synced skills\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6a14016c475349378139fe37f465945b | https://github.com/numman-ali/openskills/issues/86 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：[FEATURE] Remote path that isn't a git repo\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Remote path that isn't a git repo\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_24fd46302500414a80566af028da3bb8 | https://github.com/numman-ali/openskills/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v1.1.0 - Comprehensive Documentation & Location Tag Fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 - Comprehensive Documentation & Location Tag Fix\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_315e89cc6fa641ceaf797b3c8a4a6f6e | https://github.com/numman-ali/openskills/releases/tag/v1.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v1.3.0 - CI/CD, Local Development & Security\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.3.0 - CI/CD, Local Development & Security\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d2fade5f1d8e4e3080b89bdeb9d7bc3f | https://github.com/numman-ali/openskills/releases/tag/v1.3.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v1.3.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.3.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_aa1710ddf10a42069b3e12cf5b4eb65a | https://github.com/numman-ali/openskills/releases/tag/v1.3.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1083829346 | https://github.com/numman-ali/openskills | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1083829346 | https://github.com/numman-ali/openskills | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：numman-ali/openskills\n\n摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：[BUG] `--universal` installs to `.agent/` not `.agents/`。\n\n## 1. 安装坑 · 来源证据：[BUG] `--universal` installs to `.agent/` not `.agents/`\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] `--universal` installs to `.agent/` not `.agents/`\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c384eba59a4f4177ace0a344b94400dc | https://github.com/numman-ali/openskills/issues/84 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[FEATURE] add cli option --skills=name1,name2 to only install selected skill from github repo non-interactivelly\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] add cli option --skills=name1,name2 to only install selected skill from github repo non-interactivelly\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ec834575446429c96f39db392b81751 | https://github.com/numman-ali/openskills/issues/53 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：[Feature]: Read skill.json from source repos for install and sync\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Read skill.json from source repos for install and sync\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8752343cfb2d4231a5eb42f242806a31 | https://github.com/numman-ali/openskills/issues/81 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：[BUG] Update command doesn't update all paths\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Update command doesn't update all paths\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8f8a414bbe634c229bf200f45014fc57 | https://github.com/numman-ali/openskills/issues/75 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：[BUG] Clone failed\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Clone failed\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_59fb2f76bd674cf2bba0efb5a57843bd | https://github.com/numman-ali/openskills/issues/85 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[BUG] EEXIST when overwriting an existing skill during installation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] EEXIST when overwriting an existing skill during installation\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ac382f17e8a744b58f7d0860617a2f19 | https://github.com/numman-ali/openskills/issues/73 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v1.2.0 - Universal Skills Support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.0 - Universal Skills Support\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_31f11650e29a4e7c9fbd4ff026d577d0 | https://github.com/numman-ali/openskills/releases/tag/v1.2.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v1.2.1 - Documentation Fixes\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.1 - Documentation Fixes\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bb36323b2acd470bb0382644fddfde5f | https://github.com/numman-ali/openskills/releases/tag/v1.2.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v1.5.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.5.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7fab452932ab47e18a1d915b327b22d2 | https://github.com/numman-ali/openskills/releases/tag/v1.5.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1083829346 | https://github.com/numman-ali/openskills | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1083829346 | https://github.com/numman-ali/openskills | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1083829346 | https://github.com/numman-ali/openskills | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1083829346 | https://github.com/numman-ali/openskills | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：[BUG] Path Resolution & Sandbox Access Conflict for Global OpenSkills on macOS\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Path Resolution & Sandbox Access Conflict for Global OpenSkills on macOS\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_92230b03d1ec434694ad8d2e5ee6441f | https://github.com/numman-ali/openskills/issues/87 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：[FEATURE] Explicit local-first precedence for synced skills\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Explicit local-first precedence for synced skills\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6a14016c475349378139fe37f465945b | https://github.com/numman-ali/openskills/issues/86 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：[FEATURE] Remote path that isn't a git repo\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Remote path that isn't a git repo\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_24fd46302500414a80566af028da3bb8 | https://github.com/numman-ali/openskills/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v1.1.0 - Comprehensive Documentation & Location Tag Fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 - Comprehensive Documentation & Location Tag Fix\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_315e89cc6fa641ceaf797b3c8a4a6f6e | https://github.com/numman-ali/openskills/releases/tag/v1.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v1.3.0 - CI/CD, Local Development & Security\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.3.0 - CI/CD, Local Development & Security\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d2fade5f1d8e4e3080b89bdeb9d7bc3f | https://github.com/numman-ali/openskills/releases/tag/v1.3.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v1.3.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.3.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_aa1710ddf10a42069b3e12cf5b4eb65a | https://github.com/numman-ali/openskills/releases/tag/v1.3.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1083829346 | https://github.com/numman-ali/openskills | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1083829346 | https://github.com/numman-ali/openskills | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# openskills - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 openskills 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-cli-commands：CLI命令参考。围绕“CLI命令参考”模拟一次用户任务，不展示安装或运行结果。\n5. page-install-command：install命令详解。围绕“install命令详解”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-cli-commands\n输入：用户提供的“CLI命令参考”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-install-command\n输入：用户提供的“install命令详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-cli-commands：Step 4 必须围绕“CLI命令参考”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-install-command：Step 5 必须围绕“install命令详解”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/numman-ali/openskills\n- https://github.com/numman-ali/openskills#readme\n- examples/my-first-skill/SKILL.md\n- README.md\n- package.json\n- AGENTS.md\n- src/cli.ts\n- src/types.ts\n- src/utils/skills.ts\n- src/utils/agents-md.ts\n- src/commands/install.ts\n- src/commands/list.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 openskills 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：numman-ali/openskills\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx openskills\n```\n\n来源：https://github.com/numman-ali/openskills#readme\n\n## 来源\n\n- repo: https://github.com/numman-ali/openskills\n- docs: https://github.com/numman-ali/openskills#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_6945712b05d448cb8c09fcd8d85981c9"
}