{ "canonical_name": "heilcheng/awesome-agent-skills", "compilation_id": "pack_d4c256ef956248e1b117bffc431e5005", "created_at": "2026-05-13T04:03:01.201218+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 skills` 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 skills", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_99c3b617ad4c443185b0b0a761d0591d" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_06bd66350a0fedaae34f119e3df28fc8", "canonical_name": "heilcheng/awesome-agent-skills", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/heilcheng/awesome-agent-skills", "slug": "awesome-agent-skills", "source_packet_id": "phit_c30472d60a604792a7ddaf8f87cde3f6", "source_validation_id": "dval_e7849b22030c458ea2d2e6c83b3bd1f6" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 claude的用户", "github_forks": 440, "github_stars": 4748, "one_liner_en": "Tutorials, Guides and Agent Skills Directories", "one_liner_zh": "Tutorials, Guides and Agent Skills Directories", "primary_category": { "category_id": "software-development", "confidence": "medium", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:git" }, "target_user": "使用 claude 等宿主 AI 的用户", "title_en": "awesome-agent-skills", "title_zh": "awesome-agent-skills 能力包", "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": "Visual Workflow Orchestration", "label_zh": "视觉工作流编排", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-visual-workflow-orchestration", "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_c30472d60a604792a7ddaf8f87cde3f6", "page_model": { "artifacts": { "artifact_slug": "awesome-agent-skills", "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 skills", "label": "Node.js / npx · 官方安装入口", "source": "https://github.com/heilcheng/awesome-agent-skills#readme", "verified": true } ], "display_tags": [ "MCP 工具", "视觉工作流编排", "流程自动化", "节点式流程编排", "本地优先" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 claude的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "Tutorials, Guides and Agent Skills Directories" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "claude", "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": "仓库名 `awesome-agent-skills` 与安装入口 `skills` 不完全一致。", "category": "身份坑", "evidence": [ "identity.distribution | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | repo=awesome-agent-skills; install=skills" ], "severity": "medium", "suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。", "title": "仓库名和安装名不一致", "user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。" }, { "body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。", "category": "配置坑", "evidence": [ "capability.host_targets | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | host_targets=claude" ], "severity": "medium", "suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。", "title": "可能修改宿主 AI 配置", "user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | 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:1124920990 | https://github.com/heilcheng/awesome-agent-skills | 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:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana)", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_dc99192b4a9b4b8089f4f6696f332a7d | https://github.com/heilcheng/awesome-agent-skills/issues/218 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana)", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402)", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_0703404b82014fe3baddd3eaab1100bd | https://github.com/heilcheng/awesome-agent-skills/issues/226 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402)", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" }, { "body": "release_recency=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。", "title": "踩坑日志" }, "snapshot": { "contributors": 39, "forks": 440, "license": "unknown", "note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。", "stars": 4748, "open_issues": 121, "pushed_at": "2026-04-05T20:39:24.000Z" }, "source_url": "https://github.com/heilcheng/awesome-agent-skills", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "Tutorials, Guides and Agent Skills Directories", "title": "awesome-agent-skills 能力包", "trial_prompt": "# awesome-agent-skills - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 awesome-agent-skills 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Tutorials, Guides and Agent Skills Directories 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-intro：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-project-structure：项目结构。围绕“项目结构”模拟一次用户任务，不展示安装或运行结果。\n3. page-what-is-agent-skill：什么是Agent Skills。围绕“什么是Agent Skills”模拟一次用户任务，不展示安装或运行结果。\n4. page-compatible-agents：支持的AI代理。围绕“支持的AI代理”模拟一次用户任务，不展示安装或运行结果。\n5. page-quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-intro\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-project-structure\n输入：用户提供的“项目结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-what-is-agent-skill\n输入：用户提供的“什么是Agent Skills”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-compatible-agents\n输入：用户提供的“支持的AI代理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-intro：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-project-structure：Step 2 必须围绕“项目结构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-what-is-agent-skill：Step 3 必须围绕“什么是Agent Skills”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-compatible-agents：Step 4 必须围绕“支持的AI代理”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-quick-start：Step 5 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/heilcheng/awesome-agent-skills\n- https://github.com/heilcheng/awesome-agent-skills#readme\n- README.md\n- README.zh-CN.md\n- website/package.json\n- .gitignore\n- vercel.json\n- website/next.config.ts\n- website/tsconfig.json\n- website/src/components/sections/Hero.tsx\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 awesome-agent-skills 的核心服务。\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: ⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (（https://github.com/heilcheng/awesome-agent-skills/issues/226）；github/github_issue: Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x（https://github.com/heilcheng/awesome-agent-skills/issues/218）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (", "url": "https://github.com/heilcheng/awesome-agent-skills/issues/226" }, { "kind": "github_issue", "source": "github", "title": "Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x", "url": "https://github.com/heilcheng/awesome-agent-skills/issues/218" } ], "status": "已收录 2 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "Tutorials, Guides and Agent Skills Directories", "effort": "安装已验证", "forks": 436, "icon": "code", "name": "awesome-agent-skills 能力包", "risk": "需复核", "slug": "awesome-agent-skills", "stars": 4716, "tags": [ "MCP 工具", "视觉工作流编排", "流程自动化", "节点式流程编排", "本地优先" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/heilcheng/awesome-agent-skills 项目说明书\n\n生成时间：2026-05-11 16:27:26 UTC\n\n## 目录\n\n- [项目介绍](#page-project-intro)\n- [项目结构](#page-project-structure)\n- [什么是Agent Skills](#page-what-is-agent-skill)\n- [支持的AI代理](#page-compatible-agents)\n- [技能质量标准](#page-skill-quality-standards)\n- [快速开始](#page-quick-start)\n- [使用技能](#page-using-skills)\n- [创建技能](#page-creating-skills)\n- [官方技能目录分类](#page-official-skill-categories)\n- [网站架构](#page-website-architecture)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[项目结构](#page-project-structure), [什么是Agent Skills](#page-what-is-agent-skill)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.md)\n- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)\n- [README.zh-CN.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.zh-CN.md)\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/package.json](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/package.json)\n- [website/src/components/WikiSidebar.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/WikiSidebar.tsx)\n- [website/src/components/sections/Tutorials.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Tutorials.tsx)\n\n
\n\n# 项目介绍\n\n## 项目概述\n\nawesome-agent-skills 是一个专注于 AI Agent Skills（智能体技能）的开源精选列表项目，旨在成为 AI Agent 技能领域最全面的资源集合 资料来源：[README.md:1]()[README.ko.md:1]()。\n\n该项目由 @heilcheng 创建并维护，聚合了来自 Anthropic、OpenAI、GitHub 等主要 AI 平台的技能资源，为开发者提供一站式的技能发现、学习和应用平台 资料来源：[website/src/components/WikiSidebar.tsx:45-50]()。\n\n## 核心价值主张\n\n本项目围绕三大核心用户群体设计其价值主张：\n\n| 用户群体 | 价值主张 | 使用场景 |\n|---------|---------|---------|\n| 初学者 | 零门槛使用技能 | 直接复制 GitHub URL 粘贴到 AI 对话即可 |\n| 团队与企业 | 组织知识封装 | 将操作手册、风格指南、领域流程版本化管理 |\n| 技能开发者 | 一次构建，多端部署 | 一个文件，零基础设施，GitHub 即分享平台 |\n\n资料来源：[website/index.html:85-100]()\n\n## 技术架构\n\n### 项目结构\n\n```\nawesome-agent-skills/\n├── README.md # 项目主文档\n├── README.zh-CN.md # 中文文档\n├── README.ko.md # 韩文文档\n├── skills/ # 技能列表目录\n│ ├── development/ # 开发类技能\n│ ├── data/ # 数据处理类技能\n│ ├── automation/ # 自动化类技能\n│ └── security/ # 安全类技能\n└── website/ # 文档网站\n ├── src/\n │ ├── components/ # React 组件\n │ │ ├── sections/ # 页面区块\n │ │ └── WikiSidebar.tsx # 维基导航侧边栏\n │ └── pages/ # 页面文件\n └── public/ # 静态资源\n```\n\n资料来源：[website/package.json]() [website/src/components/WikiSidebar.tsx:1-60]()\n\n### 前端技术栈\n\n网站采用现代前端技术栈构建：\n\n| 技术 | 版本/用途 | 说明 |\n|-----|----------|------|\n| Next.js | 14+ | React 框架，提供 SSR 和路由 |\n| TypeScript | 类型安全 | 主要开发语言 |\n| Tailwind CSS | 样式框架 | 响应式样式系统 |\n| Lucide React | 图标库 | UI 图标组件 |\n| Framer Motion | 动画库 | 页面过渡和交互动画 |\n\n资料来源：[website/package.json]() [website/src/components/sections/Tutorials.tsx:1-30]()\n\n### Agent Skills 协议\n\nAgent Skills 是一种开放标准协议，最初由 Anthropic 开发，现已被 30+ 款 Agent 产品采用：\n\n```mermaid\ngraph LR\n A[SKILL.md 文件] --> B[元数据 Frontmatter]\n A --> C[指令内容 Markdown]\n B --> D[name 必填]\n B --> E[description 必填]\n B --> F[license 可选]\n B --> G[compatibility 可选]\n B --> H[metadata 可选]\n B --> I[allowed-tools 可选]\n C --> J[When to use]\n C --> K[Instructions]\n C --> L[Gotchas]\n C --> M[Examples]\n C --> N[Validation]\n```\n\n资料来源：[website/index.html:150-180]()\n\n## 技能加载机制\n\n### 渐进式加载流程\n\nAgent Skills 采用\"渐进式披露\"（Progressive Disclosure）设计理念，遵循四阶段加载模型：\n\n```mermaid\ngraph TD\n A[启动时] --> B[阶段1: 发现 Discovery]\n A --> A1[仅加载 name 和 description
~50-100 tokens/skill]\n \n B --> C{用户任务匹配?}\n C -->|是| D[阶段2: 激活 Activation]\n C -->|否| E[保持轻量]\n \n D --> F[加载完整 SKILL.md]\n F --> G[指令、示例、脚本]\n \n D --> H{需要脚本?}\n H -->|是| I[阶段3: 脚本执行]\n H -->|否| J[直接执行指令]\n \n I --> K[阶段4: 验证 Validation]\n J --> K\n```\n\n资料来源：[website/index.html:220-250]()\n\n### 技能存储位置\n\n技能文件支持多种存储路径，兼容不同 Agent 客户端：\n\n| 路径 | 用途 | 典型应用 |\n|-----|------|---------|\n| `~/.claude/skills/` | 用户级技能 | Claude Code / Claude.ai |\n| `~/.agents/skills/` | 全局技能 | 通用 Agent 客户端 |\n| `.claude/skills/` | 项目级技能 | 项目专属配置 |\n| `.github/skills/` | GitHub 存储 | GitHub 原生集成 |\n\n资料来源：[website/index.html:30-35]() [website/src/components/sections/UsingSkills.tsx:40-50]()\n\n## 功能特性\n\n### 技能分类体系\n\n项目按照技能功能进行系统化分类：\n\n- **development** — 开发类技能（代码审查、重构、测试生成等）\n- **data** — 数据处理类技能（数据分析、转换、ETL 等）\n- **automation** — 自动化类技能（CI/CD、部署、监控等）\n- **security** — 安全类技能（代码扫描、依赖审计等）\n\n资料来源：[website/src/components/sections/FindingSkills.tsx:1-20]()\n\n### 技能质量标准\n\n每个技能遵循统一的质量规范：\n\n| 维度 | 要求 | 说明 |\n|-----|------|------|\n| **结构化指令** | 清晰的步骤分解 | 避免模糊描述，精确指导 |\n| **触发条件** | 明确的激活条件 | 让 Agent 准确判断何时使用 |\n| **示例覆盖** | 丰富的输入输出示例 | 减少理解歧义 |\n| **验证机制** | 内置检查流程 | 自我验证输出正确性 |\n| **错误处理** | 预判常见问题 | Gotchas 章节记录坑点 |\n\n资料来源：[website/src/components/sections/QualityStandards.tsx:1-30]()\n\n### 命令行工具支持\n\n通过 `npx skills` CLI 可快速管理技能：\n\n| 命令 | 功能 |\n|-----|------|\n| `npx skills find [query]` | 搜索相关技能 |\n| `npx skills add ` | 添加技能（支持 GitHub 简写/完整 URL/本地路径） |\n| `npx skills list` | 列出已安装技能 |\n| `npx skills check` | 检查更新 |\n| `npx skills update` | 升级所有技能 |\n| `npx skills remove [skill-name]` | 移除技能 |\n\n资料来源：[README.ko.md:15-25]()\n\n## 兼容的 Agent 平台\n\n项目支持的 Agent 产品矩阵：\n\n| Agent | 文档链接 |\n|-------|---------|\n| Claude Code | code.claude.com/docs/en/skills |\n| Claude.ai | support.claude.com/articles/12512180 |\n| Codex (OpenAI) | developers.openai.com/codex |\n| Cursor | cursor.com/docs |\n| Copilot | github.com/features/copilot |\n| Gemini CLI | developers.google.com/gemini-code-assistant |\n\n资料来源：[README.ko.md:30-40]()\n\n## 快速入门\n\n### 使用现有技能\n\n```mermaid\ngraph LR\n A[浏览 awesome-agent-skills] --> B[找到目标技能]\n B --> C[复制 GitHub URL]\n C --> D{客户端类型}\n D -->|Claude Code| E[/skills add ]\n D -->|Claude.ai| F[粘贴原始 URL]\n D -->|其他 CLI| G[npx skills add]\n E --> H[用自然语言请求任务]\n F --> H\n G --> H\n```\n\n### 开发新技能\n\n创建新技能的推荐步骤：\n\n1. 创建以技能命名的文件夹\n2. 在文件夹内创建 `SKILL.md` 文件\n3. 编写 YAML frontmatter（name 和 description 必填）\n4. 在 Markdown 正文编写结构化指令\n5. （可选）在 `scripts/` 子目录添加可执行脚本\n\n资料来源：[website/index.html:40-70]()\n\n## 国际化支持\n\n项目文档支持多语言版本：\n\n| 语言 | 文件 | 路径 |\n|-----|------|------|\n| 英语 | README.md | 根目录 |\n| 中文 | README.zh-CN.md | 根目录 |\n| 韩语 | README.ko.md | 根目录 |\n\n资料来源：[README.zh-CN.md:1]() [README.ko.md:1]()\n\n## 相关资源\n\n| 资源 | 链接 |\n|-----|------|\n| 官方规范 | agentskills.io/specification |\n| CLI 工具 | vercel-labs/skills |\n| 项目网站 | agent-skill.co |\n| GitHub 仓库 | github.com/heilcheng/awesome-agent-skills |\n\n资料来源：[website/index.html:280-300]() [website/src/components/WikiSidebar.tsx:40-45]()\n\n---\n\n\n\n## 项目结构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-project-intro), [网站架构](#page-website-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/SkillDirectory.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/SkillDirectory.tsx)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/FindingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/FindingSkills.tsx)\n- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)\n- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)\n
\n\n# 项目结构\n\n## 概述\n\nawesome-agent-skills 是一个用于收录和管理 AI Agent 技能（Agent Skills）的开源项目仓库。该项目采用现代化的 Web 技术栈构建，为 AI Agent 提供可复用的技能库和文档站点。\n\n## 技术栈概览\n\n| 技术类别 | 具体技术 |\n|---------|---------|\n| 前端框架 | Next.js (TypeScript) |\n| 样式方案 | Tailwind CSS + 自定义 CSS 变量 |\n| 动画效果 | Framer Motion |\n| 图标库 | Lucide React |\n| 部署平台 | Vercel |\n| 包管理 | npm/pnpm |\n\n资料来源：[README.ko.md:1-20]()\n\n## 目录结构\n\n```text\nawesome-agent-skills/\n├── .gitignore # Git 忽略配置\n├── README.md # 项目主文档\n├── README.ko.md # 韩语文档\n├── README.zh.md # 中文文档\n├── vercel.json # Vercel 部署配置\n└── website/ # 主站点目录\n ├── next.config.ts # Next.js 配置文件\n ├── tsconfig.json # TypeScript 配置\n ├── package.json # 依赖管理\n ├── public/ # 静态资源目录\n └── src/\n ├── app/ # Next.js App Router\n │ ├── layout.tsx # 根布局组件\n │ ├── page.tsx # 首页组件\n │ └── globals.css # 全局样式\n ├── components/ # React 组件库\n │ ├── sections/ # 页面区块组件\n │ └── Footer.tsx # 页脚组件\n └── lib/ # 工具函数库\n```\n\n资料来源：[website/src/components/sections/SkillDirectory.tsx:1-50]()\n\n## Website 模块架构\n\n### 组件层级结构\n\n```mermaid\ngraph TD\n A[App Router] --> B[Root Layout]\n B --> C[Page Component]\n C --> D[Section Components]\n \n D --> E[SkillDirectory]\n D --> F[QualityStandards]\n D --> G[UsingSkills]\n D --> H[FindingSkills]\n D --> I[Footer]\n \n E --> J[Framer Motion Animations]\n F --> K[Good/Bad Pattern Cards]\n G --> L[CLI Code Panels]\n H --> M[External Resource Links]\n```\n\n### 核心组件说明\n\n#### SkillDirectory 组件\n\n负责技能目录的展示和搜索过滤功能。该组件使用 Framer Motion 实现布局动画，支持按名称和描述进行技能搜索。\n\n```typescript\n// 核心数据结构\n{ filtered: skill[] }\n```\n\n资料来源：[website/src/components/sections/SkillDirectory.tsx:1-80]()\n\n#### QualityStandards 组件\n\n展示技能的 Quality Standards（质量标准），包含好/坏代码模式对比卡片，帮助开发者理解最佳实践。\n\n| 组件元素 | 功能描述 |\n|---------|---------|\n| Good Pattern | 展示推荐代码模式 |\n| Bad Pattern | 展示应避免的代码模式 |\n| Pattern Description | 模式说明文字 |\n\n资料来源：[website/src/components/sections/QualityStandards.tsx:1-60]()\n\n#### UsingSkills 组件\n\n提供技能使用指南，包含 CLI 命令示例和复制功能。该组件实现了代码复制交互逻辑。\n\n| 功能模块 | 说明 |\n|---------|------|\n| CLI 代码面板 | 展示 `npx skills add` 等命令 |\n| 复制按钮 | 支持一键复制到剪贴板 |\n| 视觉反馈 | 复制成功后显示 Check 图标 |\n\n资料来源：[website/src/components/sections/UsingSkills.tsx:1-70]()\n\n#### FindingSkills 组件\n\n展示如何发现和获取技能的外部资源链接，支持 Marketplace 和 CLI 工具类资源的展示。\n\n```typescript\n// 资源类型\ntype ResourceType = 'marketplace' | 'leaderboard' | 'cli' | 'general'\n```\n\n资料来源：[website/src/components/sections/FindingSkills.tsx:1-60]()\n\n#### Footer 组件\n\n页面底部组件，包含版权信息、社交链接和联系方式。\n\n| 链接类型 | URL/功能 |\n|---------|---------|\n| 官方网站 | agent-skill.co |\n| GitHub | 项目仓库 |\n| Twitter/X | 开发者账号 |\n| 邮箱 | haileycheng@proton.me |\n\n资料来源：[website/src/components/Footer.tsx:1-50]()\n\n## 主题与样式系统\n\n### 暗色模式支持\n\n项目使用 CSS 变量实现暗色/亮色主题切换：\n\n```css\n:root {\n --bg: #000;\n --text: rgba(255, 255, 255, 0.95);\n --border: rgba(255, 255, 255, 0.08);\n}\n\n[data-theme=\"light\"] {\n /* 亮色模式变量覆盖 */\n}\n```\n\n### 色彩系统\n\n| 用途 | 颜色变量 |\n|-----|---------|\n| 主色（蓝色） | `#0a84ff` |\n| 辅助色（紫色） | `#bf5af2` |\n| 成功色（绿色） | `#30d158` |\n| 警告色（橙色） | `#ff9f0a` |\n\n资料来源：[website/index.html:1-100]()\n\n## 技能目录组织\n\n### 目录结构规范\n\n技能按照分类组织，每个技能包含：\n\n```\nskill-name/\n├── SKILL.md # 必选：技能定义文件\n└── scripts/ # 可选：辅助脚本目录\n ├── script.py # Python 脚本（PEP 723 格式）\n └── script.sh # Shell 脚本\n```\n\n### SKILL.md 格式规范\n\n每个技能必须包含 YAML frontmatter：\n\n```yaml\n---\nname: skill-name # 必选：技能名称（小写 + 连字符）\ndescription: >- # 必选：功能描述\n 1-512 字符，用于 Agent 发现和激活\nlicense: Apache-2.0 # 可选：开源许可证\ncompatibility: Python 3.11+ # 可选：环境要求\nmetadata: # 可选：元数据\n author: example-org\n version: \"1.0\"\nallowed-tools: Bash Read Write # 可选：预批准工具列表\n---\n```\n\n资料来源：[website/index.html:200-300]()\n\n## 构建与部署\n\n### Vercel 部署配置\n\n项目通过 `vercel.json` 配置自动化部署流程：\n\n```json\n{\n \"buildCommand\": \"npm run build\",\n \"outputDirectory\": \".next\",\n \"installCommand\": \"npm install\"\n}\n```\n\n### Next.js 配置要点\n\n| 配置项 | 说明 |\n|-------|------|\n| `reactStrictMode` | 启用 React 严格模式 |\n| `images` | 图片优化配置 |\n| `env` | 环境变量管理 |\n\n资料来源：[website/next.config.ts]()\n\n## 开发工作流\n\n```mermaid\ngraph LR\n A[代码编写] --> B[TypeScript 检查]\n B --> C[ESLint 检查]\n C --> D[Next.js Build]\n D --> E[Vercel Preview]\n E --> F[合并到 Main]\n F --> G[自动部署生产环境]\n```\n\n## 资源链接\n\n| 资源类型 | 链接 |\n|---------|------|\n| 项目官网 | agent-skill.co |\n| GitHub 仓库 | github.com/heilcheng/awesome-agent-skills |\n| 官方规范 | agentskills.io/specification |\n| CLI 工具 | vercel-labs/skills |\n\n资料来源：[website/src/components/Footer.tsx:1-40]()\n\n## 总结\n\nawesome-agent-skills 项目采用现代化的 Next.js + TypeScript 技术栈，构建了一个用于管理和展示 AI Agent 技能的文档站点。项目的组件化设计使其具有良好的可维护性和扩展性，同时通过 Vercel 平台实现了自动化的 CI/CD 流程。\n\n---\n\n\n\n## 什么是Agent Skills\n\n### 相关页面\n\n相关主题：[支持的AI代理](#page-compatible-agents), [快速开始](#page-quick-start)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/WhatIsIt.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/WhatIsIt.tsx)\n- [website/src/components/sections/Contributing.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Contributing.tsx)\n- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)\n\n
\n\n# 什么是Agent Skills\n\n## 概述\n\nAgent Skills 是一个开放的 AI Agent 技能标准，旨在让 AI 助手能够学习和掌握特定任务的执行能力。简单来说，Agent Skill 就是一个纯文本指令文件（称为 `SKILL.md`），它教会 AI 如何完成特定任务。把它想象成一张食谱卡：AI 阅读它，按照步骤执行，就能完成任务。资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 核心特点\n\nAgent Skills 具有以下核心特点，使其区别于传统的提示工程方法：\n\n| 特点 | 描述 |\n|------|------|\n| **按需加载** | 技能只在需要时加载，AI 保持快速响应 |\n| **零基础设施** | 不需要复杂的部署环境，一个文件即可 |\n| **版本控制** | 可以像普通项目一样在 GitHub 上共享和管理 |\n| **跨平台兼容** | 兼容 30+ 个 AI 开发平台，无需修改即可通用 |\n| **纯文本格式** | 使用 Markdown 编写，无需编程基础 |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## SKILL.md 文件格式规范\n\n### 文件结构\n\n每个 Agent Skill 存放在一个独立的文件夹中，文件夹内必须包含 `SKILL.md` 文件。推荐的标准目录结构如下：\n\n```\nskill-name/\n├── SKILL.md # 必需：主要指令文件\n└── scripts/ # 可选：辅助脚本目录\n └── example.py\n```\n\n### Frontmatter 元数据\n\n每个 `SKILL.md` 文件以 YAML frontmatter 开头，其中 `name` 和 `description` 是必填字段：\n\n```yaml\n---\nname: pdf-processing\ndescription: Extract and summarize text from PDF documents\n---\n```\n\n#### name 字段规范\n\n| 规则 | 要求 |\n|------|------|\n| 字符集 | 仅小写字母、数字和连字符 |\n| 长度 | 1-64 个字符 |\n| 匹配 | 必须与父目录名称一致 |\n| 禁止 | 连续连字符、首尾连字符 |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 推荐的正文章节结构\n\n`SKILL.md` 的 Markdown 正文部分没有格式限制，但推荐使用以下标准结构，以便 Agent 更好地理解和执行：\n\n```markdown\n## 何时使用此技能\n触发条件、适用范围和局限性。\n\n## 指令\n逐步操作步骤，要明确具体。\n\n## 注意事项\n特定于环境的事实，容易出错的地方。\n\n## 示例\n具体的输入 → 输出对。\n\n## 验证\n如何验证输出是否正确。\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 工作原理\n\nAgent Skills 采用渐进式披露（Progressive Disclosure）设计模式，在不同阶段加载不同深度的信息：\n\n```mermaid\ngraph TD\n A[启动 Agent] --> B[轻量级扫描]\n B --> C[加载 name 和 description]\n C --> D{任务匹配?}\n D -->|否| E[不使用技能]\n D -->|是| F[按需加载完整 SKILL.md]\n F --> G[执行技能指令]\n G --> H[运行 scripts/ 中的脚本]\n H --> I[任务完成]\n \n style B fill:#e1f5fe\n style F fill:#fff3e0\n```\n\n### 阶段一：发现（Discovery）\n\n在启动时，Agent 仅加载每个可用技能的 `name` 和 `description`，每个技能约 50-100 个 token。此阶段不会加载任何实际指令内容。资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 阶段二：激活（Activation）\n\n当用户的任务与某个技能的描述匹配时，Agent 将完整的 `SKILL.md` 读入上下文。此时加载的内容包括详细的指令、示例和脚本。\n\n### 阶段三：执行（Execution）\n\nAgent 根据技能指令执行任务，必要时可运行 `scripts/` 子目录中的可执行文件。\n\n## 安装与使用\n\n### 三种使用视角\n\n```mermaid\ngraph LR\n A[新手用户] --> |复制 GitHub URL| B[粘贴到 AI 对话]\n C[团队/企业] --> |捕获组织知识| D[版本控制的技能包]\n E[技能作者] --> |一次构建| F[跨平台部署]\n \n style A fill:#c8e6c9\n style C fill:#bbdefb\n style E fill:#ffe0b2\n```\n\n#### 新手用户\n\n1. 浏览技能目录\n2. 复制技能的 GitHub URL\n3. 将 URL 粘贴到 AI 对话中\n\n#### 团队和企业\n\n将组织知识（如操作手册、风格指南、领域流程）捕获为可移植的版本控制技能包。资料来源：[website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n\n### CLI 安装方式\n\n```bash\n# Claude Code\nnpx skills add anthropics/skills/docx\n\n# 或使用 GitHub 简写格式\nnpx skills add //\n```\n\n### 手动安装路径\n\n对于某些平台，可以直接将技能文件夹放置到指定目录：\n\n| 平台 | 安装路径 |\n|------|----------|\n| Claude Code | `~/.claude/skills/` |\n| 通用 Agent | `.agents/skills/` |\n| GitHub Actions | `.github/skills/` |\n\n资料来源：[website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n\n## 兼容平台\n\nAgent Skills 是一个被主要 AI 开发工具采用的开放标准。创建的技能无需修改即可在以下平台使用：\n\n| 平台类别 | 工具列表 |\n|----------|----------|\n| Anthropic | Claude Code, Claude.ai |\n| OpenAI | Codex |\n| Microsoft | GitHub Copilot |\n| IDE 插件 | Cursor |\n| 其他 | 30+ 兼容平台 |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 脚本支持\n\nAgent 可以运行 `scripts/` 子目录中的可执行文件。设计脚本时应考虑 Agent 的特性：\n\n```python\n#!/usr/bin/env -S uv run\n# /// script\n# requires-python = \">= 3.11\"\n# dependencies = [\"requests\", \"rich\"]\n# ///\n\nimport sys, json\n\n# 避免交互式提示\n# 使用结构化输出 (JSON/CSV)\n# 将错误写入 stderr\n# 使用有意义的退出码\nprint(json.dumps({\"result\": \"ok\"}))\n```\n\n### 脚本设计原则\n\n| 原则 | 说明 |\n|------|------|\n| 避免交互 | 不要使用 input() 或交互式提示 |\n| 结构化输出 | 使用 JSON 或 CSV 格式 |\n| 错误处理 | 将错误信息写入 stderr |\n| 明确退出码 | 使用有意义的退出码 |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 技能质量标准\n\n### 好的技能 vs 差的技能\n\n#### 优秀技能的编写模式\n\n- 使用清晰的步骤编号\n- 提供具体的触发条件\n- 包含实际的输入输出示例\n- 明确说明验证方法\n\n#### 需要避免的模式\n\n- 模糊不清的指令\n- 缺少上下文说明\n- 没有错误处理指引\n- 缺乏实际案例\n\n资料来源：[website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n\n## 创建你的第一个技能\n\n创建步骤非常简单：\n\n```mermaid\ngraph LR\n A[创建文件夹] --> B[命名技能]\n B --> C[创建 SKILL.md]\n C --> D[添加 name 和 description]\n D --> E[编写指令正文]\n E --> F[放置到 skills 目录]\n```\n\n1. 创建一个以技能名称命名的文件夹\n2. 在文件夹内创建 `SKILL.md` 文件\n3. 在文件顶部添加 YAML frontmatter（name 和 description）\n4. 在下方用纯英文编写你的指令\n5. 将文件夹放置到 `.claude/skills/` 或 `.github/skills/` 目录\n\n资料来源：[website/src/components/sections/Contributing.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Contributing.tsx)\n\n## 总结\n\nAgent Skills 提供了一种轻量级、标准化的方式来扩展 AI Agent 的能力。通过将任务指令封装为可移植的 `SKILL.md` 文件，用户可以：\n\n- **快速分享**：通过 GitHub URL 一键分享技能\n- **版本控制**：像代码一样管理技能版本\n- **跨平台使用**：一次创建，多平台通用\n- **零门槛创作**：纯文本格式，无需编程基础\n\n这种设计让 AI 助手能够\"学会\"执行特定任务，同时保持核心的快速响应特性。资料来源：[website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)\n\n---\n\n\n\n## 支持的AI代理\n\n### 相关页面\n\n相关主题：[使用技能](#page-using-skills), [什么是Agent Skills](#page-what-is-agent-skill)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)\n- [website/src/components/sections/WhatIsIt.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/WhatIsIt.tsx)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)\n
\n\n# 支持的AI代理\n\n## 概述\n\nAgent Skill Index 是一个兼容多种 AI 代理系统的技能索引平台，旨在为不同 AI 助手提供统一的技能（Skill）管理规范。该项目定义了标准化的 SKILL.md 格式，使开发者能够创建一次技能，即可在多个支持该规范的 AI 代理上使用。\n\n该平台兼容的主流 AI 代理包括 **Claude**、**Codex**、**Copilot** 以及其他遵循 agentskills.io 规范的代理工具。资料来源：[website/index.html:1-10]()\n\n## 支持的AI代理列表\n\n### 主流支持的代理\n\n| 代理名称 | 平台类型 | 技能加载方式 | 官方文档 |\n|---------|---------|------------|---------|\n| Claude | Anthropic | /skills add 命令或粘贴 URL | Claude.ai / Claude Code |\n| Codex | OpenAI | npx skills add | OpenAI Codex 文档 |\n| Copilot | Microsoft | npx skills add | GitHub Copilot 文档 |\n| Claude Code | Anthropic CLI | /skills add | Claude Code 文档 |\n\n资料来源：[website/index.html:1-10]()\n\n### 代理兼容性说明\n\n所有支持的 AI 代理都需要遵循 agentskills.io 规范来实现技能加载功能。该规范定义了技能文件的结构、YAML 前端定义以及渐进式加载机制。\n\n```mermaid\ngraph TD\n A[AI 代理启动] --> B[扫描技能目录]\n B --> C{是否匹配用户任务}\n C -->|是| D[加载完整 SKILL.md]\n C -->|否| E[保持轻量模式]\n D --> F[执行技能指令]\n E --> G[等待匹配]\n F --> H[返回结果]\n```\n\n资料来源：[website/index.html:180-200]()\n\n## 技能加载机制\n\n### 渐进式披露设计\n\nAgent Skills 采用渐进式披露（Progressive Disclosure）设计理念，在不同阶段加载不同程度的信息：\n\n1. **启动时扫描**：仅加载每个技能的 `name` 和 `description` 字段，约 50-100 token/技能\n2. **按需激活**：当用户任务与技能描述匹配时，读取完整的 SKILL.md 内容\n3. **指令执行**：根据技能指令和可选脚本完成任务\n\n```mermaid\ngraph TD\n A[启动] --> B[扫描技能目录
~project/.agents/skills/
~/.agents/skills/
~/.claude/skills/]\n B --> C[加载 name + description]\n C --> D[等待用户任务]\n D --> E{任务匹配检测}\n E -->|匹配 skill description| F[加载完整 SKILL.md]\n E -->|不匹配| D\n F --> G[执行指令与脚本]\n G --> H[验证输出]\n H --> I[返回结果]\n```\n\n资料来源：[website/index.html:180-200]()\n\n### 技能目录结构\n\n支持的技能目录位置根据不同 AI 代理有所不同：\n\n| 目录路径 | 适用代理 | 说明 |\n|---------|---------|------|\n| `.claude/skills/` | Claude Code | 项目级技能目录 |\n| `.github/skills/` | GitHub 集成 | 企业级技能目录 |\n| `~/.agents/skills/` | 通用 | 用户级技能目录 |\n| `.agents/skills/` | 通用 | 本地技能目录 |\n\n资料来源：[website/index.html:180-200]()\n\n## 技能格式规范\n\n### SKILL.md 结构\n\n每个技能由 YAML 前端定义和 Markdown 正文组成：\n\n```yaml\n---\nname: pdf-processing\ndescription: >\n Extract text and tables from PDF files, fill PDF forms, and merge\n multiple PDFs. Use when working with PDF documents, forms, or when\n the user mentions PDFs, document extraction, or form filling.\nlicense: Apache-2.0\ncompatibility: Requires Python 3.11+ and uv\nmetadata:\n author: example-org\n version: \"1.0\"\nallowed-tools: Bash(uv:*) Read Write\n---\n```\n\n### 前端字段说明\n\n| 字段名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| name | string | 是 | 小写字母、数字、连字符，1-64字符 |\n| description | string | 是 | 技能描述，激活条件判断依据 |\n| license | string | 否 | 技能许可证类型 |\n| compatibility | string | 否 | 兼容性要求说明 |\n| metadata | object | 否 | 作者、版本等元数据 |\n| allowed-tools | string | 否 | 预批准的工具列表（实验性） |\n\n资料来源：[website/index.html:30-80]()\n\n### 推荐正文结构\n\n```markdown\n## When to use this skill\n触发条件、范围和限制说明。\n\n## Instructions\n逐步操作流程，需要明确具体。\n\n## Gotchas\n环境特定的事实，不符合预期的行为。\n\n## Examples\n具体的输入输出示例。\n\n## Validation\n如何验证输出正确性。\n```\n\n资料来源：[website/index.html:120-150]()\n\n## 工具与脚本支持\n\n### 脚本目录\n\n技能可包含可选的 `scripts/` 子目录存放可执行文件：\n\n```bash\nmy-skill/\n├── SKILL.md\n└── scripts/\n ├── extract.py\n └── ocr.py\n```\n\n### 代理友好脚本设计原则\n\n1. **非交互式**：避免交互式提示\n2. **结构化输出**：使用 JSON/CSV 而非自由文本\n3. **错误处理**：诊断信息输出到 stderr\n4. **退出码**：使用有意义的退出代码\n\n```python\n#!/usr/bin/env -S uv run\n# /// script\n# requires-python = \">= 3.11\"\n# dependencies = [\"requests\", \"rich\"]\n# ///\nimport sys, json\n\n# 正确示范\nprint(json.dumps({\"result\": \"ok\"})) # 数据到 stdout\nsys.exit(0) # 有意义的退出码\n```\n\n资料来源：[website/index.html:120-150]()\n\n## 质量标准\n\n### 技能质量要素\n\n| 要素 | 说明 |\n|-----|------|\n| 明确性 | 指令清晰、无歧义 |\n| 可验证性 | 内置验证流程 |\n| 隔离性 | 不依赖未声明的环境 |\n| 简洁性 | 避免不必要的复杂性 |\n\n### 好的示例 vs 坏的示例\n\n**好的模式**：\n```markdown\n1. First, verify the input is valid JSON.\n2. Then, run `scripts/validate.py` to check schema.\n3. If validation fails, stop and report the error.\n```\n\n**坏的模式**：\n```markdown\n1. Do something with the file.\n2. Maybe check if it's correct.\n3. Continue if it looks okay.\n```\n\n资料来源：[website/src/components/sections/QualityStandards.tsx:1-50]()\n\n## 官方规范资源\n\n完整的 SKILL.md 格式规范、目录结构要求、渐进式披露设计以及客户端实现指南可在官方规范页面获取：\n\n| 资源 | 地址 |\n|-----|------|\n| 官方规范 | agentskills.io/specification |\n| GitHub 仓库 | github.com/heilcheng/awesome-agent-skills |\n| 作者联系 | LinkedIn @haileyhmt / Email haileycheng@proton.me |\n\n资料来源：[website/index.html:200-250]()\n\n## 快速入门\n\n### 新手使用步骤\n\n1. **找到技能**：浏览技能目录，按类别（开发、数据、自动化、安全等）组织\n2. **加载到AI**：复制 GitHub URL，根据不同平台使用对应命令\n3. **用自然语言提问**：AI 自动读取技能指令并执行\n\n```bash\n# Claude Code\n/skills add \n\n# Claude.ai\n粘贴 raw SKILL.md URL 到聊天窗口\n```\n\n### 企业团队使用\n\n捕获组织知识——操作手册、风格指南、领域流程——以可移植的版本控制包形式存储，实现跨团队共享和复用。\n\n资料来源：[website/src/components/sections/WhatIsIt.tsx:1-30]()\n[website/src/components/sections/UsingSkills.tsx:1-50]()\n\n---\n\n\n\n## 技能质量标准\n\n### 相关页面\n\n相关主题：[创建技能](#page-creating-skills)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)\n
\n\n# 技能质量标准\n\n## 概述\n\n技能质量标准（Skill Quality Standards）是 awesome-agent-skills 项目为确保 AI Agent 技能（Skills）具备一致性、可复用性和高效性而制定的一系列规范与最佳实践。这些标准涵盖了技能的元数据定义、内容结构、编写原则以及验证方法，旨在帮助技能作者创建高质量、可维护的技能文件。\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 核心质量维度\n\n技能的 quality 由以下五个核心维度构成：\n\n| 维度 | 编号 | 核心原则 | 关键要求 |\n|------|------|----------|----------|\n| 作用域设计 | 01 | 设计内聚、适度规模的技能 | 避免过窄（浪费开销）或过宽（失去焦点） |\n| 指令编写 | 03 | 添加 Agent 缺乏的内容；跳过 Agent 已知的部分 | 聚焦项目约定、领域特定流程和边缘情况 |\n| 控制策略 | 04 | 仅在重要时刻做规定性要求 | 多种方案等效时给予自由；操作脆弱、不可逆或必须按特定顺序时明确严格 |\n| 脚本设计 | 05 | 使脚本对 Agent 友好 | 非交互式标志、结构化输出、有意义的退出码 |\n| 验证机制 | 06 | 将验证循环构建到指令中 | 检查表、输出模板匹配、计划-验证-执行模式 |\n\n资料来源：[website/index.html:1-150](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## SKILL.md 元数据标准\n\n### 必需字段\n\n每个技能必须包含以下 YAML 前端格式（Frontmatter）字段：\n\n```yaml\n---\nname: pdf-processing # 必需：技能名称\ndescription: >- # 必需：技能描述\n 1-1024 个字符的描述文本\n---\n```\n\n| 字段 | 类型 | 限制 | 说明 |\n|------|------|------|------|\n| `name` | 必需 | 1-64 字符 | 仅使用小写字母、数字和连字符；禁止连续连字符；禁止首尾连字符；必须与父目录名匹配 |\n| `description` | 必需 | 1-1024 字符 | Agent 启动时读取的关键字段，用于决定是否激活技能；应描述技能功能和使用场景 |\n\n**name 字段示例：**\n\n```\nname: pdf-processing\nname: code-review\nname: data-analysis\n```\n\n**description 字段质量标准：**\n\n| 质量等级 | 示例 |\n|----------|------|\n| 良好 | \"Extracts text and tables from PDF files. Use when working with PDFs, forms, or document extraction.\" |\n| 不佳 | \"Helps with PDFs.\" |\n\n资料来源：[website/index.html:1-100](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 可选字段\n\n| 字段 | 类型 | 限制 | 说明 |\n|------|------|------|------|\n| `license` | 可选 | 许可证名称或文件名 | 保持技能包自包含 |\n| `compatibility` | 可选 | 1-500 字符 | 仅在存在特定环境要求时使用 |\n| `metadata` | 可选 | 键值对 | 作者、版本等元数据 |\n| `allowed-tools` | 可选·实验性 | 空格分隔的工具列表 | 预批准可运行的工具，减少操作确认提示 |\n\n资料来源：[website/index.html:1-80](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 内容结构标准\n\n### 推荐章节结构\n\n技能的 Markdown 正文部分应包含以下五个核心章节：\n\n```markdown\n## When to use this skill\n触发条件、适用范围和限制说明。\n\n## Instructions\n逐步操作程序。保持明确具体。\n\n## Gotchas\n环境特定的事实。违反常规预期的事项。\n\n## Examples\n具体的输入→输出示例对。\n\n## Validation\n如何验证输出是否正确。\n```\n\n资料来源：[website/index.html:1-60](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 最小示例\n\n```yaml\n---\nname: roll-dice\ndescription: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.).\n---\n\nTo roll a die, run:\n```bash\necho $((RANDOM % + 1))\n```\n```\n\n## 规模限制标准\n\n| 指标 | 上限 | 拆分阈值 |\n|------|------|----------|\n| 代码行数 | 500 行以内 | 超过时拆分为引用文件 |\n| Token 数量 | 5,000 token 以内 | 超过时拆分为多个技能 |\n\n> **经验法则：** 超过 500 行或 5,000 token 的技能应拆分为引用文件。\n\n资料来源：[website/index.html:1-50](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 渐进式披露机制\n\n技能采用渐进式披露（Progressive Disclosure）设计，按需加载以保持性能：\n\n```mermaid\ngraph TD\n A[Agent 启动] --> B[轻量级扫描]\n B --> C[仅加载 name 和 description]\n C --> D{任务匹配?}\n D -->|是| E[加载完整 SKILL.md]\n D -->|否| F[不加载指令]\n E --> G[执行技能指令]\n F --> H[使用通用能力]\n```\n\n### 目录扫描位置\n\nAgent 在以下位置扫描技能目录：\n\n| 级别 | 路径 |\n|------|------|\n| 项目级（共享） | `.agents/skills/` |\n| 用户级（个人） | `~/.agents/skills/` |\n| Claude Code 专用 | `.claude/skills/` 或 `~/.claude/skills/` |\n\n资料来源：[website/index.html:1-80](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 脚本设计标准\n\n### PEP 723 内联依赖\n\n当技能需要脚本时，推荐使用 Python PEP 723 内联依赖格式：\n\n```python\n#!/usr/bin/env -S uv run\n# /// script\n# requires-python = \">= 3.11\"\n# dependencies = [\"requests\", \"rich\"]\n# ///\n```\n\n### Agent 友好脚本原则\n\n| 原则 | 具体要求 |\n|------|----------|\n| 避免交互提示 | Agent 无法响应交互式提示 |\n| 结构化输出 | 使用 JSON/CSV 而非自由文本 |\n| 错误处理 | 将错误写入 stderr |\n| 退出码 | 使用有意义的退出码 |\n\n**推荐模式：**\n\n```mermaid\ngraph LR\n A[数据] -->|stdout| B[结构化输出]\n C[诊断信息] -->|stderr| D[日志/错误]\n E[执行结果] -->|退出码| F[0=成功, 非0=失败]\n```\n\n资料来源：[website/index.html:1-90](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 验证机制标准\n\n### 验证模式\n\n高质量技能应包含内置验证循环：\n\n1. **检查表验证**：多步骤工作流的逐项确认\n2. **输出模板匹配**：验证返回结果符合预期格式\n3. **计划-验证-执行模式**：破坏性操作的三阶段确认\n\n### 验证示例\n\n> **示例：** \"提交前，运行测试并确认全部通过。如果测试失败，修复后重新运行。\"\n\n```markdown\n## Validation\n\n1. [ ] 步骤一完成\n2. [ ] 步骤二完成\n3. [ ] 输出格式验证通过\n4. [ ] 错误日志为空\n```\n\n资料来源：[website/index.html:1-70](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 兼容性标准\n\n### 支持的 Agent 平台\n\n技能作为开放标准，被以下 30+ 平台支持：\n\n| 平台 | 状态 |\n|------|------|\n| Claude Code | ✅ 官方支持 |\n| Claude.ai | ✅ 官方支持 |\n| GitHub Copilot | ✅ 官方支持 |\n| VS Code | ✅ 官方支持 |\n| OpenAI Codex | ✅ 官方支持 |\n| Google Antigravity | ✅ 官方支持 |\n| Gemini CLI | ✅ 官方支持 |\n| Cursor | ✅ 官方支持 |\n| Kiro | ✅ 官方支持 |\n\n资料来源：[website/index.html:1-50](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 技能目录结构\n\n```\nmy-skill/\n├── SKILL.md # 必需：技能定义文件\n├── scripts/ # 可选：可执行脚本目录\n│ ├── script1.py # Agent 可调用的脚本\n│ └── script2.sh\n└── README.md # 可选：额外文档\n```\n\n资料来源：[website/index.html:1-40](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 质量检查清单\n\n创建技能时的自检清单：\n\n- [ ] `name` 字段符合命名规范（小写字母、数字、连字符）\n- [ ] `description` 字段包含功能描述和使用场景（1-1024 字符）\n- [ ] 包含 `When to use this skill` 章节\n- [ ] 包含 `Instructions` 章节\n- [ ] 包含 `Gotchas` 章节（环境特定注意事项）\n- [ ] 包含 `Examples` 章节\n- [ ] 包含 `Validation` 章节\n- [ ] 代码行数 ≤ 500 行\n- [ ] Token 数量 ≤ 5,000 token\n- [ ] 脚本使用非交互式设计\n- [ ] 脚本输出结构化数据\n- [ ] 脚本使用有意义的退出码\n\n## 与其他技术的对比\n\n| 特性 | Agent Skills | MCP (Model Context Protocol) |\n|------|--------------|-------------------------------|\n| 核心功能 | 教授 AI **如何**执行任务 | 帮助 AI **访问**资源 |\n| 实现方式 | 工作流、最佳实践 | API、数据库、外部工具 |\n| 更新难度 | 简单（仅修改指令文件） | 复杂（需要代码修改） |\n| 成本 | 低（指令文件） | 高（服务部署） |\n| 组合使用 | 可与 MCP 协同 | 可与 Skills 协同 |\n\n资料来源：[website/index.html:1-30](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[使用技能](#page-using-skills), [什么是Agent Skills](#page-what-is-agent-skill)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)\n
\n\n# 快速开始\n\n本页面帮助用户快速上手使用 awesome-agent-skills 项目，掌握查找、加载和使用 AI Agent 技能的基础流程。\n\n## 什么是 Agent Skill\n\nAgent Skill 是一个纯文本指令文件（称为 `SKILL.md`），用于教 AI 助手如何完成特定任务。可以将其理解为一张配方卡片：AI 阅读它，按照步骤执行，即可完成任务。技能仅在需要时加载，因此 AI 保持快速响应。\n\n资料来源：[website/index.html:1-50]()\n\n## 三分钟快速上手\n\n以下流程演示了从发现技能到实际使用的完整路径：\n\n```mermaid\ngraph TD\n A[发现技能] --> B[获取 GitHub URL]\n B --> C[加载到 AI]\n C --> D[用自然语言描述需求]\n D --> E[AI 自动读取技能说明]\n E --> F[执行任务]\n```\n\n资料来源：[website/src/components/sections/UsingSkills.tsx:1-50]()\n\n### 步骤一：发现技能\n\n在页面下方的目录中浏览所有技能。技能按类别组织（开发、数据、自动化、安全等），每个卡片直接链接到 GitHub 上的技能。\n\n### 步骤二：加载到 AI\n\n复制技能的 GitHub URL 并添加到 AI 代理中。根据平台不同，命令略有差异：\n\n| 平台 | 命令 |\n|-----|------|\n| Claude Code | `/skills add ` |\n| Claude.ai | 在对话中粘贴原始 SKILL.md URL |\n| Codex (OpenAI) | 参考官方文档 |\n\n资料来源：[README.ko.md:30-45]()\n\n### 步骤三：用自然语言提问\n\n只需告诉 AI 你想要什么——它会自动读取技能说明并开始工作。无需记忆命令，无需配置。\n\n资料来源：[website/index.html:80-100]()\n\n## 使用 npx skills CLI 工具\n\n对于特定技能，可以使用 `npx skills` 命令行工具快速发现、添加和管理技能。\n\n| 命令 | 功能 |\n|------|------|\n| `npx skills find [query]` | 搜索相关技能 |\n| `npx skills add ` | 添加技能（支持 GitHub 简写、完整 URL、本地路径） |\n| `npx skills list` | 列出已安装的技能 |\n| `npx skills check` | 检查更新 |\n| `npx skills update` | 升级所有技能 |\n| `npx skills remove [skill-name]` | 移除技能 |\n\n资料来源：[README.ko.md:20-30]()\n\n## 兼容的 AI 代理\n\n| 代理 | 文档链接 |\n|-----|---------|\n| Claude Code | [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) |\n| Claude.ai | [support.claude.com](https://support.claude.com/en/articles/12512180-using-skills-in-claude) |\n| Codex (OpenAI) | [developers.openai.com](https://developers.openai.com/codex) |\n\n资料来源：[README.ko.md:48-55]()\n\n## 手动加载技能\n\n如果不想使用 CLI 工具，也可以手动放置技能文件夹：\n\n```bash\n# 下载技能后放置到指定目录\ncp -r my-downloaded-skill ~/.agents/skills/my-downloaded-skill\n\n# 验证结构：技能必须有 SKILL.md 文件\nls ~/.agents/skills/my-skill/SKILL.md\n```\n\n支持的放置路径：\n\n- `~/.claude/skills/`\n- `~/.agents/skills/`\n- `~/.project/.agents/skills/`\n- `.github/skills/`（用于项目级技能）\n\n资料来源：[website/index.html:120-140]()\n\n## 创建你的第一个技能\n\n如果现有技能无法满足需求，可以自行创建：\n\n### 技能目录结构\n\n```\nskill-name/\n├── SKILL.md # 必需：技能说明文件\n└── scripts/ # 可选：可执行脚本目录\n └── *.py # 支持 Python、Shell 等\n```\n\n### SKILL.md 基本格式\n\n```yaml\n---\nname: skill-name\ndescription: 技能的简短描述，1-512 字符\n---\n\n## When to use this skill\n触发条件和使用场景\n\n## Instructions\n逐步执行步骤\n\n## Gotchas\n特殊注意事项\n\n## Examples\n输入输出示例\n```\n\n资料来源：[website/src/components/sections/CreatingSkills.tsx:1-40]()\n\n### 创建步骤\n\n1. **创建文件夹**：以技能名称命名（仅限小写字母、数字和连字符）\n2. **编写 SKILL.md**：在文件顶部添加 YAML frontmatter，包含 `name` 和 `description`\n3. **编写说明**：使用纯英文描述步骤和示例\n4. **添加脚本（如需要）**：在 `scripts/` 子目录放置可执行文件\n\n资料来源：[website/index.html:50-70]()\n\n## 技能质量标准\n\n为确保技能有效运行，建议遵循以下结构：\n\n| 章节 | 用途 |\n|-----|------|\n| `## When to use this skill` | 触发条件、范围和限制 |\n| `## Instructions` | 逐步执行过程，明确具体 |\n| `## Gotchas` | 环境特定事实，意外情况说明 |\n| `## Examples` | 具体的输入输出示例 |\n| `## Validation` | 如何验证输出正确性 |\n\n### 良好的指令示例\n\n```markdown\n## When to use this skill\n当用户需要从 PDF 文件中提取文本和表格时激活\n\n## Instructions\n1. 验证输入是有效的 PDF 文件\n2. 运行 scripts/extract.py 脚本\n3. 验证输出后再返回结果\n```\n\n### 应避免的模式\n\n- 模糊的描述，如\"做得好一点\"\n- 缺少具体的执行步骤\n- 没有说明错误处理方式\n\n资料来源：[website/src/components/sections/QualityStandards.tsx:1-60]()\n\n## 进阶功能\n\n### allowed-tools 字段\n\n在 frontmatter 中使用 `allowed-tools` 字段预批准工具运行，减少每次操作时的确认提示：\n\n```yaml\n---\nname: pdf-processing\nallowed-tools: Bash(uv:*) Read Write\n---\n```\n\n资料来源：[website/index.html:150-160]()\n\n### PEP 723 脚本\n\nPython 脚本可使用 PEP 723 内联依赖声明：\n\n```python\n#!/usr/bin/env -S uv run\n# /// script\n# requires-python = \">= 3.11\"\n# dependencies = [\"requests\", \"rich\"]\n# ///\nimport sys, json\n```\n\n资料来源：[website/index.html:170-185]()\n\n## 后续步骤\n\n- 探索完整的 [技能目录](#) 找到适合你的技能\n- 阅读 [SKILL.md 格式规范](https://agentskills.io/specification) 了解完整规格\n- 参考 [贡献指南](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md) 提交你自己的技能\n\n---\n\n\n\n## 使用技能\n\n### 相关页面\n\n相关主题：[快速开始](#page-quick-start), [支持的AI代理](#page-compatible-agents)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)\n
\n\n# 使用技能\n\n本文档详细介绍如何在各类 AI Agent 产品中使用 Agent Skills，包括发现、加载、激活的完整流程，以及不同平台的集成方式。\n\n## 什么是 Agent Skills\n\nAgent Skills 是一种可移植的知识包，由包含 `SKILL.md` 文件的文件夹组成。该文件融合了元数据和指令，使 AI Agent 能够按需发现和加载特定技能。Agent Skills 最初由 Anthropic 开发，现已作为开放标准被 30+ Agent 产品采用，包括 Claude、Codex、Cursor、Copilot、Gemini CLI 等。\n\n资料来源：[website/index.html:1-20]()\n\n### 核心特性\n\n| 特性 | 说明 |\n|------|------|\n| 按需加载 | 仅在需要时加载技能，保持 Agent 响应速度 |\n| 零基础设施 | 无需复杂配置，共享在 GitHub 上即可使用 |\n| 平台无关 | 兼容所有支持 Skills 标准的 Agent 产品 |\n| 版本控制 | 作为 Git 仓库管理，便于追踪变更 |\n\n资料来源：[website/index.html:120-140]()\n\n## 工作原理\n\n### 渐进式披露机制\n\nAgent Skills 采用渐进式披露（Progressive Disclosure）机制，分三个阶段工作：\n\n```mermaid\ngraph TD\n A[启动 Agent] --> B[发现 Discovery]\n B --> C[激活 Activation]\n C --> D[加载 Loading]\n D --> E[执行任务]\n \n B --> B1[扫描 name + description
~50-100 tokens/技能]\n C --> C1[匹配用户任务]\n D --> D1[读取完整 SKILL.md]\n \n style B fill:#e1f5fe\n style C fill:#f3e5f5\n style D fill:#fff3e0\n```\n\n### 三个阶段详解\n\n| 阶段 | 触发时机 | 加载内容 | 位置 |\n|------|----------|----------|------|\n| **发现** | Agent 启动时 | 仅 `name` 和 `description` | `~/.claude/skills/` |\n| **激活** | 任务匹配描述时 | 完整 `SKILL.md` 内容 | 上下文注入 |\n| **加载** | 执行相关操作 | `scripts/` 目录中的脚本 | 按需执行 |\n\n资料来源：[website/index.html:280-310]()\n\n## 使用方式\n\n### 方式一：通过 CLI 添加\n\n使用官方命令行工具添加技能，这是最便捷的方式：\n\n```bash\nnpx skills add anthropics/skills/docx\n```\n\n该命令支持以下几种引用格式：\n\n| 格式类型 | 示例 |\n|----------|------|\n| GitHub 简写 | `anthropics/skills/docx` |\n| 完整 URL | `https://github.com/anthropics/skills/docx` |\n| 本地相对路径 | `./my-skills/pdf-processing` |\n\n资料来源：[website/src/components/sections/UsingSkills.tsx:1-40]()\n\n### 方式二：手动放置\n\n将技能文件夹直接放置到指定目录，Agent 会自动扫描：\n\n| 平台 | 路径 |\n|------|------|\n| Claude Code | `.claude/skills/` 或 `.github/skills/` |\n| Claude.ai | 粘贴原始 SKILL.md 的 URL |\n| 通用 | `~/.agents/skills/` 或 `~/.claude/skills/` |\n\n放置结构示例：\n\n```\n.github/skills/skill-name/\n├── SKILL.md # 必需：技能定义文件\n└── scripts/ # 可选：可执行脚本目录\n ├── script1.py\n └── script2.sh\n```\n\n资料来源：[website/src/components/sections/UsingSkills.tsx:45-60]()\n\n### 方式三：通过 URL 直接引用\n\n在 Claude.ai 等平台，可以直接粘贴原始 `SKILL.md` 文件的 GitHub URL，Agent 会自动读取并应用技能说明。\n\n## 使用流程\n\n### 三步上手指南\n\n```mermaid\ngraph LR\n A[1. 找到技能] --> B[2. 加载到 AI]\n B --> C[3. 用自然语言提问]\n C --> D[✨ 任务完成]\n \n A --> A1[浏览目录
选择技能]\n B --> B1[复制 GitHub URL
添加到 Agent]\n C --> C1[用自然语言描述需求
Agent 自动读取技能]\n \n style A fill:#e3f2fd\n style B fill:#f3e5f5\n style C fill:#e8f5e9\n```\n\n### 步骤详解\n\n#### 步骤一：找到技能\n\n浏览 awesome-agent-skills 目录中的技能列表。技能按类别组织，包括开发、数据、自动化、安全等类别。每个技能卡片都直接链接到 GitHub 上的技能仓库。\n\n#### 步骤二：加载到 AI\n\n根据使用的平台选择合适的加载方式：\n\n- **Claude Code**: 使用 `/skills add ` 命令\n- **Claude.ai**: 直接在聊天窗口粘贴原始 SKILL.md 的 URL\n- **其他平台**: 参考各自平台的技能管理文档\n\n#### 步骤三：用自然语言提问\n\n完成上述步骤后，只需用自然语言描述你的需求。Agent 会自动读取技能说明并执行相应操作。无需记忆任何命令或进行额外配置。\n\n资料来源：[website/src/components/sections/UsingSkills.tsx:10-35]()\n\n## 技能结构\n\n### 目录结构规范\n\n```\nskill-name/\n├── SKILL.md # 必需：包含 YAML frontmatter + 指令\n├── scripts/ # 可选：可执行脚本目录\n│ ├── script1.py # Python 脚本（推荐 PEP 723 格式）\n│ └── script2.sh # Shell 脚本\n└── README.md # 可选：人类可读的说明文档\n```\n\n### SKILL.md 文件格式\n\n每个技能的核心是 `SKILL.md` 文件，采用 YAML frontmatter + Markdown 正文的结构：\n\n```yaml\n---\nname: pdf-processing\ndescription: >\n 从 PDF 文件提取文本和表格，填充 PDF 表单，\n 合并多个 PDF。当处理 PDF 文档、表单或涉及\n 文档提取、表单填充时激活。\nlicense: Apache-2.0\ncompatibility: Requires Python 3.11+ and uv\nmetadata:\n author: example-org\n version: \"1.0\"\nallowed-tools: Bash(uv:*) Read Write\n---\n\n## 何时使用此技能\n\n激活条件、范围和限制说明。\n\n## 指令\n\n逐步操作步骤，保持清晰明确。\n\n## 注意事项\n\n环境特定的事实，不符合预期的情况。\n\n## 示例\n\n具体的输入 → 输出对。\n\n## 验证\n\n如何验证输出正确性。\n```\n\n### Frontmatter 字段说明\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| `name` | 是 | 小写字母 + 连字符，1-64 字符，与父目录名一致 |\n| `description` | 是 | 技能描述，说明何时使用此技能 |\n| `license` | 否 | 许可证类型 |\n| `compatibility` | 否 | 兼容性要求 |\n| `metadata` | 否 | 元数据（author、version 等） |\n| `allowed-tools` | 否 | 实验性字段，预批准可执行的工具列表 |\n\n资料来源：[website/index.html:30-80]()\n\n## 质量标准\n\n为确保技能的有效性，编写时需遵循以下质量标准：\n\n| 原则 | 说明 |\n|------|------|\n| **渐进式披露** | 先给概览，再逐步深入细节 |\n| **假设最小化** | 明确说明前提条件，减少歧义 |\n| **行动导向** | 使用祈使句和动词开头 |\n| **适度规定** | 仅在必要时严格规定，其他情况给予自由度 |\n| **脚本设计** | 非交互式、结构化输出、有意义的退出码 |\n| **验证机制** | 内置验证循环，Agent 自我检查 |\n\n### 好的模式 vs 不好的模式\n\n```mermaid\ngraph LR\n subgraph 好的模式\n A1[明确的步骤编号] --> A2[可验证的输出]\n A2 --> A3[具体示例]\n end\n \n subgraph 不好的模式\n B1[模糊的描述] --> B2[无验证机制]\n B2 --> B3[缺少上下文]\n end\n```\n\n资料来源：[website/src/components/sections/QualityStandards.tsx:1-50]()\n\n## 常见问题\n\n### Q: 什么是 Agent Skill？\n\nAgent Skill 是一个纯文本指令文件（称为 `SKILL.md`），用于教 AI 助手如何完成特定任务。可以将其理解为食谱卡片：AI 读取它，按照步骤执行，然后完成任务。技能仅在需要时加载，因此 AI 保持快速响应。\n\n### Q: 我不是开发者，能使用技能吗？\n\n可以。技能是纯英文指令文件，不是代码。你只需要一个 AI 助手（如 Claude.ai，免费版即可），不需要终端或 GitHub 账户。只需复制技能的 GitHub URL 并粘贴到 AI 聊天中即可。\n\n### Q: 技能免费吗？\n\n技能本身是免费的。但使用某些技能可能需要付费使用底层 API（如使用特定模型）。技能文件本身可以免费复制、使用和修改。\n\n### Q: 如何创建自己的技能？\n\n只需创建一个以技能命名的文件夹，在其中放置 `SKILL.md` 文件，顶部的 frontmatter 包含 `name` 和 `description`，然后在下面的 Markdown 中编写你的指令。将文件夹放在 `.claude/skills/` 或 `.github/skills/` 中即可。\n\n资料来源：[website/index.html:400-450]()\n\n## 获取帮助\n\n| 渠道 | 说明 |\n|------|------|\n| GitHub Issues | 报告 Bug 或请求新功能 |\n| GitHub Discussions | 提问和社区讨论 |\n| 官方网站 | [agent-skill.co](https://agent-skill.co) |\n| 邮件联系 | haileycheng@proton.me |\n\n资料来源：[website/src/components/Footer.tsx:1-30]()\n\n## 相关资源\n\n- [贡献指南](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md) - 学习如何为项目贡献技能\n- [创建技能](CreatingSkills.md) - 了解如何从头创建新技能\n- [质量标准](QualityStandards.md) - 掌握编写高质量技能的规范\n- [官方教程](https://modelcontextprotocol.io/docs/first-server) - MCP 入门教程\n\n---\n\n\n\n## 创建技能\n\n### 相关页面\n\n相关主题：[技能质量标准](#page-skill-quality-standards), [使用技能](#page-using-skills)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [CONTRIBUTING.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md)\n
\n\n# 创建技能\n\n## 概述\n\n「创建技能」是 awesome-agent-skills 项目中用于指导开发者构建可复用 AI Agent 技能的核心文档模块。该模块详细说明了如何从零开始创建一个符合规范要求的技能（Skill），包括目录结构、文件格式、编写规范以及最佳实践。\n\n技能是一种包含 `SKILL.md` 文件的文件夹，其中融合了元数据和指令，AI Agent 可以按需发现和加载。开发者只需创建一次，即可在支持 Agent Skills 标准的 30+ 个平台上使用，无需修改。\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## 技能目录结构\n\n每个技能本质上是一个独立的文件夹，必须遵循统一的目录结构规范。\n\n### 标准目录布局\n\n```\nskill-name/\n├── SKILL.md # 必需：技能定义文件\n└── scripts/ # 可选：可执行脚本目录\n ├── script1.py\n └── script2.sh\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 目录位置\n\n技能文件夹可放置于以下位置供 Agent 发现：\n\n| 位置 | 说明 |\n|------|------|\n| `.claude/skills/` | Claude Code 本地技能目录 |\n| `.github/skills/` | GitHub 集成技能目录 |\n| `~/.claude/skills/` | 用户级全局技能目录 |\n| `~/.agents/skills/` | 通用 Agent 技能目录 |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## SKILL.md 文件规范\n\n### 文件结构\n\n`SKILL.md` 采用 YAML 前置数据（Frontmatter）+ Markdown 正文的标准格式：\n\n```markdown\n---\nname: skill-name\ndescription: 技能描述（1-512字符）\nlicense: Apache-2.0 # 可选\ncompatibility: Python 3.11+ # 可选\nmetadata: # 可选\n author: example-org\n version: \"1.0\"\nallowed-tools: Bash(git:*) Read Write # 可选·实验性\n---\n\n## 技能正文内容\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 前置数据字段\n\n| 字段名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `name` | 字符串 | **是** | 小写字母、数字和连字符组成，1-64字符，不能有连续连字符，不能以连字符开头或结尾，必须与父目录名称一致 |\n| `description` | 字符串 | **是** | 技能用途描述，1-512字符，用于 Agent 在启动时识别是否需要加载该技能 |\n| `license` | 字符串 | 否 | 采用的开源许可证，如 Apache-2.0、MIT |\n| `compatibility` | 字符串 | 否 | 环境依赖说明，如 Python 3.11+、Node.js 18+ |\n| `metadata` | 对象 | 否 | 扩展元数据，包含 author、version 等信息 |\n| `allowed-tools` | 字符串 | 否 | 预批准的可执行工具列表（实验性功能） |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## 编写技能正文\n\n### 推荐正文结构\n\n为了确保 Agent 能清晰理解并执行任务，建议按以下结构组织 Markdown 正文：\n\n```markdown\n## When to use this skill\n触发条件、适用范围和限制说明。\n\n## Instructions\n逐步操作流程，请保持步骤明确且可执行。\n\n## Gotchas\n环境特定的事实，容易出错或违背预期的事项。\n\n## Examples\n具体的输入→输出示例对。\n\n## Validation\n如何验证输出结果是否正确。\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 编写原则\n\n1. **结构化步骤**：使用编号列表，将复杂任务分解为明确的子步骤\n2. **具体示例**：提供真实场景下的输入输出示例\n3. **错误处理**：说明常见错误及应对方法\n4. **验证方式**：定义输出质量的检验标准\n\n资料来源：[website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n\n---\n\n## 创建技能工作流\n\n### 四步创建流程\n\n```mermaid\ngraph TD\n A[1. 创建技能文件夹] --> B[2. 编写 SKILL.md]\n B --> C[3. 编写技能指令]\n C --> D[4. 添加脚本可选]\n D --> E[技能创建完成]\n```\n\n资料来源：[website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)\n\n### 步骤详解\n\n#### 第一步：创建技能文件夹\n\n在 `.claude/skills/` 或 `.github/skills/` 目录下创建以技能名称命名的文件夹。\n\n```bash\nmkdir -p .github/skills/pdf-processing\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n#### 第二步：编写 SKILL.md\n\n在文件夹内创建 `SKILL.md` 文件，添加 YAML 前置数据：\n\n```yaml\n---\nname: pdf-processing\ndescription: 从 PDF 文件中提取文本和表格，填充 PDF 表单，合并多个 PDF。\n---\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n#### 第三步：编写技能指令\n\n在 YAML 前置数据下方添加 Markdown 正文，用简洁的英文描述操作步骤：\n\n```markdown\n## When to use this skill\n\n当用户需要提取文本、填充表单或合并 PDF 时激活此技能。\n\n## Instructions\n\n1. 验证输入是有效的 PDF 文件\n2. 从 scripts/ 目录运行相应的脚本\n3. 返回结果前验证输出\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n#### 第四步：添加脚本（可选）\n\n在 `scripts/` 子目录中放置可执行文件。推荐使用 PEP 723 规范的 Python 脚本，包含内联依赖声明：\n\n```python\n#!/usr/bin/env -S uv run\n# /// script\n# requires-python = \">= 3.11\"\n# dependencies = [\"requests\", \"rich\"]\n# ///\nimport sys, json\n\n# 使用结构化输出\n# 将错误写入 stderr\nprint(json.dumps({\"result\": \"ok\"}))\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## 技能加载机制\n\n### 渐进式加载设计\n\nAgent Skills 采用「渐进式披露」（Progressive Disclosure）设计，在不同阶段加载不同信息：\n\n```mermaid\ngraph LR\n A[启动阶段] --> B[仅加载 name + description]\n B --> C[任务匹配时]\n C --> D[加载完整 SKILL.md]\n D --> E[必要时加载 scripts/]\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 加载阶段说明\n\n| 阶段 | 加载内容 | Token 消耗 |\n|------|----------|------------|\n| 启动扫描 | `name` + `description` | ~50-100 字符/技能 |\n| 任务激活 | 完整 `SKILL.md` 正文 | 完整内容 |\n| 脚本执行 | `scripts/` 目录文件 | 按需加载 |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## 技能质量标准\n\n### 优质技能特征\n\n| 维度 | 要求 |\n|------|------|\n| 名称规范 | 小写字母+连字符，与目录名一致 |\n| 描述准确 | 清晰说明触发场景和功能范围 |\n| 指令明确 | 步骤具体、无歧义、可执行 |\n| 示例完整 | 提供真实输入输出示例 |\n| 错误处理 | 说明常见错误及处理方式 |\n\n资料来源：[website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n\n### 完整示例\n\n以下是一个符合所有规范的完整技能示例：\n\n```yaml\n---\nname: pdf-processing\ndescription: >\n 从 PDF 文件中提取文本和表格，填充 PDF 表单，\n 合并多个 PDF。适用于处理 PDF 文档、表单或\n 涉及文档提取的场景。\nlicense: Apache-2.0\ncompatibility: Requires Python 3.11+ and uv\nmetadata:\n author: example-org\n version: \"1.0\"\nallowed-tools: Bash(uv:*) Read Write\n---\n\n## When to use this skill\n\n当用户需要提取文本、填充表单或合并 PDF 时激活此技能。\n\n## Instructions\n\n1. 验证输入是有效的 PDF\n2. 根据任务类型运行相应脚本\n3. 验证输出后返回结果\n\n## Gotchas\n\n- 扫描版 PDF 需要 OCR（使用 ocr.py 而非 extract.py）\n- 加密 PDF 需要先解密\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## 与现有系统集成\n\n### 安装技能到本地\n\n使用 `npx skills` CLI 工具可快速添加技能：\n\n```bash\n# 通过 GitHub 添加\nnpx skills add anthropics/skills/docx\n\n# 手动复制到本地\ncp -r my-downloaded-skill ~/.claude/skills/my-skill\n```\n\n资料来源：[website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n\n### 验证技能安装\n\n```bash\nls ~/.claude/skills/my-skill/SKILL.md\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## 参与贡献\n\n如果您希望将技能提交到 awesome-agent-skills 仓库，请参考贡献指南：\n\n- 查看 [CONTRIBUTING.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md) 了解提交流程\n- 确保技能符合质量标准\n- 通过 GitHub Pull Request 提交\n\n资料来源：[website/src/components/sections/Contributing.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Contributing.tsx)\n\n---\n\n## 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| 官方规范 | [agentskills.io/specification](https://agentskills.io/specification) |\n| skills CLI | [vercel-labs/skills](https://github.com/vercel-labs/skills) |\n| Claude 技能文档 | [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) |\n\n---\n\n\n\n## 官方技能目录分类\n\n### 相关页面\n\n相关主题：[什么是Agent Skills](#page-what-is-agent-skill), [快速开始](#page-quick-start)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.md)\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/SkillDirectory.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/SkillDirectory.tsx)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)\n
\n\n# 官方技能目录分类\n\n## 概述\n\n官方技能目录（Skill Directory）是 awesome-agent-skills 项目的核心功能模块，提供了 AI Agent Skills 的可发现性浏览界面。该目录将社区贡献的各类技能按照功能领域进行分类组织，使用户能够快速定位所需的技能集合。技能目录支持动态筛选、搜索过滤以及直接的 GitHub URL 链接访问，每个技能卡片都直接关联到 GitHub 仓库上的具体技能实现。资料来源：[website/index.html:1-50]()\n\n## 目录架构设计\n\n### 渐进式加载机制\n\n技能目录采用「渐进式披露」（Progressive Disclosure）设计模式，在不同阶段加载不同层级的技能信息，以优化性能并减少不必要的资源消耗。\n\n```mermaid\ngraph TD\n A[启动阶段] --> B[轻量级扫描]\n B --> C[仅加载 name 和 description]\n C --> D[约 50-100 tokens/技能]\n E[任务匹配时] --> F[完整加载]\n F --> G[加载完整 SKILL.md]\n G --> H[读取指令、示例和脚本]\n```\n\n技能目录的搜索路径包括以下标准位置：\n\n| 路径位置 | 说明 |\n|---------|------|\n| `~/.claude/skills/` | Claude Code 默认技能目录 |\n| `~/.agents/skills/` | 通用代理技能存储 |\n| `.github/skills/` | 项目级技能目录 |\n| `.agents/skills/` | 本地项目技能目录 |\n\n资料来源：[website/index.html:120-135]()\n\n### 目录扫描与发现机制\n\n目录组件通过静态分析技能元数据实现自动发现功能。在项目启动时，系统仅提取技能的 `name` 和 `description` 字段，这些信息用于构建技能索引和匹配算法。当用户任务与某个技能的描述相匹配时，才会触发完整 `SKILL.md` 文件的加载流程。\n\n## 分类体系结构\n\n### 主分类维度\n\n技能目录按照功能领域划分为多个主分类维度，每个维度对应特定的技能集合：\n\n| 分类名称 | 涵盖范围 | 典型技能示例 |\n|---------|---------|-------------|\n| **开发** | 代码编写、调试、重构相关技能 | 代码审查、测试生成、文档编写 |\n| **数据** | 数据处理、分析、转换相关技能 | PDF 处理、数据分析、表格提取 |\n| **自动化** | 工作流自动化、脚本执行相关技能 | CI/CD 集成、部署自动化 |\n| **安全** | 安全扫描、合规检查相关技能 | 漏洞扫描、依赖检查 |\n\n资料来源：[website/index.html:80-95]()\n\n### 技能卡片组件\n\n目录中的每个技能以卡片形式展示，卡片包含以下关键信息：\n\n```typescript\ninterface SkillCard {\n name: string; // 技能名称（小写字母+连字符）\n description: string; // 技能描述（触发条件和使用场景）\n category: string; // 所属分类\n githubUrl: string; // GitHub 仓库链接\n tags?: string[]; // 可选标签\n}\n```\n\n技能卡片的设计强调可访问性，每个卡片都包含直接指向 GitHub 仓库的链接，支持用户快速复制技能 URL 并加载到 AI 代理中。资料来源：[website/src/components/sections/SkillDirectory.tsx:1-30]()\n\n## 技能目录交互流程\n\n### 用户发现与加载流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Directory as 技能目录\n participant Agent as AI 代理\n participant GitHub as GitHub\n\n User->>Directory: 浏览技能目录\n Directory->>User: 显示分类技能列表\n User->>Directory: 选择目标技能\n Directory->>User: 返回 GitHub URL\n User->>Agent: 粘贴 GitHub URL\n Agent->>GitHub: 请求 SKILL.md 内容\n GitHub->>Agent: 返回技能定义\n Agent->>User: 执行任务\n```\n\n### 多平台加载方式\n\n根据不同的 AI 代理平台，技能加载方式存在差异：\n\n| 平台 | 加载命令 | 说明 |\n|-----|---------|------|\n| Claude Code | `/skills add ` | 使用斜杠命令添加技能 |\n| Claude.ai | 粘贴原始 SKILL.md URL | 直接在聊天窗口粘贴 |\n| Cursor | 放入 `.github/skills/` | IDE 自动识别 |\n| Claude.ai 免费版 | 支持完整功能 | 无需付费 |\n\n资料来源：[website/src/components/sections/UsingSkills.tsx:1-40]()\n\n## 技能筛选与搜索功能\n\n### 动态过滤机制\n\n目录提供实时搜索和分类筛选功能，用户可以通过关键词快速定位目标技能。搜索算法基于技能名称和描述进行匹配，支持模糊搜索和精确匹配两种模式。\n\n技能目录还实现了分类内搜索功能，允许用户在同一分类下进行二次筛选，进一步缩小搜索范围。\n\n### 筛选状态管理\n\n```mermaid\nstateDiagram-v2\n [*] --> 全部技能\n 全部技能 --> 按分类筛选\n 按分类筛选 --> 搜索关键词\n 搜索关键词 --> 精确结果\n 精确结果 --> 重置筛选\n 重置筛选 --> 全部技能\n```\n\n当用户输入搜索关键词时，系统会同时匹配技能名称、描述和标签字段，返回相关性排序的结果列表。资料来源：[website/index.html:95-110]()\n\n## 目录展示组件\n\n### 响应式网格布局\n\n技能目录采用响应式网格布局，根据视口宽度动态调整每行显示的技能卡片数量：\n\n| 视口宽度 | 每行卡片数 | 布局模式 |\n|---------|----------|---------|\n| ≥1280px | 4 列 | 四列网格 |\n| ≥768px | 2-3 列 | 双列/三列网格 |\n| <768px | 1 列 | 单列堆叠 |\n\n### 分类标签系统\n\n每个技能可附加多个分类标签，标签系统支持以下功能：\n\n- **多分类归属**：单个技能可属于多个分类\n- **标签过滤**：支持按标签快速筛选\n- **视觉标识**：不同分类使用不同颜色区分\n\n资料来源：[website/src/components/sections/SkillDirectory.tsx:40-60]()\n\n## 技能目录数据源\n\n### GitHub 仓库集成\n\n技能目录通过集成 GitHub API 获取技能列表和元数据。每个技能对应一个独立的 GitHub 仓库或仓库内的子目录，目录结构要求包含 `SKILL.md` 文件作为技能定义入口。\n\n```\nrepository/\n├── SKILL.md # 必需：技能定义文件\n├── scripts/ # 可选：可执行脚本目录\n│ ├── extract.py\n│ └── transform.sh\n├── assets/ # 可选：资源文件目录\n└── README.md # 可选：技能说明文档\n```\n\n### 元数据提取\n\n目录从 GitHub 仓库的 `SKILL.md` 文件中提取以下元数据：\n\n- `name`：技能唯一标识符\n- `description`：技能功能描述\n- `license`：开源许可证类型\n- `compatibility`：兼容性要求\n- `allowed-tools`：预批准工具列表\n- `metadata`：作者、版本等信息\n\n资料来源：[website/index.html:150-180]()\n\n## 质量标准与分类规范\n\n### 技能描述质量要求\n\n技能目录对收录的技能有明确的质量标准要求：\n\n| 标准项 | 要求 | 说明 |\n|-------|------|------|\n| 描述完整性 | 必须包含触发条件 | 说明何时应激活该技能 |\n| 语言风格 | 使用祈使语气 | \"Use this skill when...\" |\n| 关键词覆盖 | 包含用户可能输入的关键词 | 提高匹配准确度 |\n| 示例提供 | 建议包含输入输出示例 | 帮助理解技能用途 |\n\n### 优秀与不良示例对比\n\n资料来源：[website/src/components/sections/QualityStandards.tsx:1-30]()\n\n**优秀描述示例：**\n```\nExtracts text and tables from PDF files. Use when working with \nPDFs, forms, or document extraction.\n```\n\n**不良描述示例：**\n```\nHelps with PDFs.\n```\n\n## 兼容性与扩展性\n\n### 多代理平台兼容\n\n技能目录设计为跨平台兼容，确保同一技能可在多个 AI 代理产品中使用：\n\n```mermaid\ngraph LR\n A[SKILL.md 标准格式] --> B[Claude Code]\n A --> C[Claude.ai]\n A --> D[OpenAI Codex]\n A --> E[GitHub Copilot]\n A --> F[Cursor]\n A --> G[Gemini CLI]\n \n B --> H[30+ 代理产品]\n C --> H\n D --> H\n E --> H\n F --> H\n G --> H\n```\n\n### npx skills CLI 工具支持\n\n技能目录与 `npx skills` 命令行工具深度集成，提供便捷的技能发现和管理能力：\n\n```bash\nnpx skills find [query] # 搜索相关技能\nnpx skills add # 添加技能（支持 GitHub 简写）\nnpx skills list # 列出已安装技能\nnpx skills check # 检查更新\nnpx skills update # 更新所有技能\nnpx skills remove [skill-name] # 移除指定技能\n```\n\n资料来源：[README.ko.md:60-75]()\n\n## 总结\n\n官方技能目录分类模块是 awesome-agent-skills 项目的核心功能，通过清晰的分类体系、渐进式加载机制和跨平台兼容设计，为用户提供了高效的技能发现和管理体验。目录采用模块化架构，支持多种 AI 代理平台的技能共享，是构建可复用 AI 代理能力的标准化解决方案。\n\n---\n\n\n\n## 网站架构\n\n### 相关页面\n\n相关主题：[项目结构](#page-project-structure)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/src/app/layout.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/app/layout.tsx)\n- [website/src/app/page.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/app/page.tsx)\n- [website/src/components/LayoutShell.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/LayoutShell.tsx)\n- [website/src/components/Navbar.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Navbar.tsx)\n- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)\n- [website/src/components/sections/WhatIsIt.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/WhatIsIt.tsx)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n\n
\n\n# 网站架构\n\n## 概述\n\nawesome-agent-skills 网站是一个基于 Next.js 构建的现代化文档展示平台，用于展示 AI Agent 技能（Agent Skills）的目录和教程。该网站采用 React + TypeScript + Tailwind CSS 技术栈构建，具有响应式设计，支持明暗主题切换，并提供多语言内容展示能力。\n\n## 技术栈\n\n| 技术 | 用途 | 版本要求 |\n|------|------|----------|\n| Next.js | React 框架与 SSR/SSG 支持 | - |\n| React 18 | UI 组件库 | 18.x |\n| TypeScript | 类型安全开发 | 5.x |\n| Tailwind CSS | 原子化 CSS 样式框架 | 3.x |\n| Lucide React | 图标库 | - |\n\n## 整体架构\n\n网站采用标准的 Next.js App Router 架构模式，组件化设计贯穿整个项目。\n\n```mermaid\ngraph TB\n subgraph \"App Router Layer\"\n A[\"app/layout.tsx\"] --> B[\"app/page.tsx\"]\n end\n \n subgraph \"Layout Shell\"\n C[\"LayoutShell.tsx\"] --> D[\"Navbar.tsx\"]\n C --> E[\"Footer.tsx\"]\n end\n \n subgraph \"Page Sections\"\n F[\"WhatIsIt.tsx\"]\n G[\"QualityStandards.tsx\"]\n H[\"UsingSkills.tsx\"]\n I[\"CreatingSkills.tsx\"]\n J[\"FindingSkills.tsx\"]\n K[\"Tutorials.tsx\"]\n end\n \n B --> C\n C --> F\n C --> G\n C --> H\n C --> I\n C --> J\n C --> K\n```\n\n## 核心组件结构\n\n### 布局层组件\n\n#### LayoutShell.tsx\n\n布局容器组件，负责整体页面结构的组织。该组件是页面内容与导航栏、页脚之间的桥梁，协调各部分组件的渲染顺序和布局关系。\n\n#### Navbar.tsx\n\n顶部导航栏组件，提供网站主导航功能，包含 Logo、页面链接和外部社交媒体入口。导航栏组件实现了响应式设计，支持移动端菜单折叠。\n\n#### Footer.tsx\n\n页脚组件，包含以下关键信息：\n\n- 网站版权声明（2026年）\n- 出版方信息（GitHub）\n- 主要链接入口：\n - agent-skill.co 官方网站\n - GitHub 仓库地址\n - X (Twitter) 社交链接\n - 电子邮件联系方式\n\n```typescript\n\n agent-skill.co\n\n\n GitHub\n\n\n Twitter\n\n\n Mail\n\n```\n\n资料来源：[website/src/components/Footer.tsx]()\n\n### 页面区块组件 (Sections)\n\n网站内容由多个独立的 Section 组件构成，每个组件负责一个特定的展示区域：\n\n| 组件 | 功能描述 |\n|------|----------|\n| WhatIsIt.tsx | 介绍 Agent Skills 的核心概念和价值主张 |\n| QualityStandards.tsx | 展示技能的质量标准和最佳实践示例 |\n| UsingSkills.tsx | 指导用户如何使用现有技能 |\n| CreatingSkills.tsx | 提供创建新技能的指南 |\n| FindingSkills.tsx | 介绍如何发现和获取技能资源 |\n| Tutorials.tsx | 展示教程和高级使用案例 |\n\n#### WhatIsIt.tsx 组件结构\n\n该组件通过 Icon + Title + Description 的标准化卡片布局展示信息：\n\n```typescript\n{features.map(({ Icon, title, desc }) => (\n
\n
\n \n
\n
\n

{title}

\n

{desc}

\n
\n
\n))}\n```\n\n资料来源：[website/src/components/sections/WhatIsIt.tsx]()\n\n#### QualityStandards.tsx 组件结构\n\n该组件展示了技能的优劣对比示例，采用双栏布局：\n\n```mermaid\ngraph LR\n A[QualityStandards] --> B[质量标准卡片列表]\n A --> C[Good Example 面板]\n A --> D[Bad Example 面板]\n \n C --> E[\"✅ 良好模式示例\"]\n D --> F[\"❌ 错误模式示例\"]\n```\n\n组件使用 `CheckCircle2` 和 `XCircle` 图标区分良好和不良示例，并通过透明度设置（opacity-70）视觉降级错误示例的显示效果。\n\n资料来源：[website/src/components/sections/QualityStandards.tsx]()\n\n#### UsingSkills.tsx 组件结构\n\n该组件专注于展示技能加载和使用的操作流程，包含以下功能模块：\n\n1. **三步骤说明卡片** - 展示使用技能的标准流程\n2. **代码面板** - 提供 CLI 命令示例和手动配置路径\n3. **复制功能** - 支持一键复制代码片段\n\n```typescript\n
\n  npx skills add anthropics/skills/docx\n
\n```\n\n支持多种添加方式：GitHub 简写格式、完整 URL、本地相对路径。\n\n资料来源：[website/src/components/sections/UsingSkills.tsx]()\n\n## 主题系统\n\n网站实现了完整的明暗主题切换功能，采用 CSS 自定义属性（CSS Variables）实现：\n\n```css\n:root{\n --bg:#000;\n --bg1:rgba(255,255,255,0.03);\n --bg2:rgba(255,255,255,0.05);\n --bg3:rgba(255,255,255,0.08);\n --border:rgba(255,255,255,0.08);\n --border2:rgba(255,255,255,0.12);\n --text:rgba(255,255,255,0.95);\n}\n```\n\nTailwind CSS 暗黑模式类名映射：\n\n| 亮色类 | 暗黑模式类 | 用途 |\n|--------|------------|------|\n| text-neutral-900 | dark:text-white | 主文本颜色 |\n| text-neutral-500 | dark:text-neutral-400 | 次要文本 |\n| bg-white | dark:bg-neutral-900 | 卡片背景 |\n| border-neutral-200 | dark:border-neutral-800 | 边框颜色 |\n\n## 页面路由结构\n\n```\nwebsite/src/app/\n├── layout.tsx # 根布局，包含全局样式和主题配置\n└── page.tsx # 首页主路由\n```\n\nNext.js App Router 模式下，`layout.tsx` 定义的布局会被所有页面共享，确保导航栏和页脚在整个网站中保持一致。\n\n## 组件通信模式\n\n组件间主要通过以下方式进行数据和状态传递：\n\n```mermaid\ngraph TD\n A[layout.tsx] -->|props| B[LayoutShell]\n B -->|props| C[Navbar]\n B -->|props| D[Footer]\n B -->|children| E[Page Sections]\n \n F[Feature Data] -->|map| E\n G[i18n] -->|translations| E\n```\n\n## 响应式设计策略\n\n网站采用移动优先的响应式设计原则，关键断点如下：\n\n| 断点前缀 | 屏幕宽度 | 典型设备 |\n|----------|----------|----------|\n| 无前缀 | < 768px | 手机 |\n| md: | ≥ 768px | 平板 |\n| lg: | ≥ 1024px | 桌面 |\n\n常用响应式布局类：\n\n- `md:grid-cols-2` - 中等屏幕双栏布局\n- `gap-4` → `md:gap-6` - 间距随屏幕放大\n- `px-4` → `md:px-8` - 水平内边距递增\n\n## 开发规范\n\n### 组件文件组织\n\n```\nwebsite/src/components/\n├── LayoutShell.tsx # 布局容器\n├── Navbar.tsx # 导航栏\n├── Footer.tsx # 页脚\n└── sections/ # 页面区块\n ├── WhatIsIt.tsx\n ├── QualityStandards.tsx\n ├── UsingSkills.tsx\n ├── CreatingSkills.tsx\n ├── FindingSkills.tsx\n └── Tutorials.tsx\n```\n\n### 样式编写规范\n\n1. **优先使用 Tailwind 原子类** - 减少自定义 CSS 文件\n2. **使用 CSS 变量管理主题色** - 便于暗黑模式切换\n3. **组件内样式隔离** - 避免样式冲突\n4. **统一使用 neutral 色系** - 配合暗色主题\n\n### 国际化考虑\n\n网站内容通过翻译对象结构组织，便于扩展多语言支持。现有包含韩语版本（README.ko.md），说明项目有多语言文档需求。\n\n## 总结\n\nawesome-agent-skills 网站采用了现代化的前端架构设计，通过 Next.js App Router 实现服务端渲染和客户端导航的平衡。组件化的设计使得各功能模块高度解耦，便于维护和扩展。明暗主题支持、响应式布局和多语言文档能力共同构成了这个文档网站的技术基础。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：heilcheng/awesome-agent-skills\n\n摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `awesome-agent-skills` 与安装入口 `skills` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx skills`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | repo=awesome-agent-skills; install=skills\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | host_targets=claude\n\n## 3. 能力坑 · 能力判断依赖假设\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:1124920990 | https://github.com/heilcheng/awesome-agent-skills | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 来源证据：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dc99192b4a9b4b8089f4f6696f332a7d | https://github.com/heilcheng/awesome-agent-skills/issues/218 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 8. 安全/权限坑 · 来源证据：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0703404b82014fe3baddd3eaab1100bd | https://github.com/heilcheng/awesome-agent-skills/issues/226 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 9. 维护坑 · 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:1124920990 | https://github.com/heilcheng/awesome-agent-skills | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | release_recency=unknown\n\n\n", "markdown_key": "awesome-agent-skills", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:1124920990", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/heilcheng/awesome-agent-skills" }, { "evidence_id": "art_9e33d67875b5417db07acced1ca8e9a6", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/heilcheng/awesome-agent-skills#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "awesome-agent-skills 说明书", "toc": [ "https://github.com/heilcheng/awesome-agent-skills 项目说明书", "目录", "项目介绍", "项目概述", "核心价值主张", "技术架构", "技能加载机制", "功能特性", "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": "de9056857eb0e96da833469d2ee3ac392058225d", "repo_inspection_error": null, "repo_inspection_files": [ "README.md" ], "repo_inspection_verified": true, "review_reasons": [ "community_discussion_evidence_below_public_threshold" ], "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": "# website - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 website 编译的 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_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npx skills find [query] # Search for related skills` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `npx skills add # Install skills (supports GitHub shorthand, full URL, local path)` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `npx skills list # List installed skills` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npx skills check # Check for available updates` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx skills update # Upgrade all skills` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npx skills remove [skill-name] # Uninstall skills` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `pip install fastmcp` 证据：`README.md` Claim：`clm_0009` 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_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` 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 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\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_0010` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0011` supported 0.86\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- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：53\n- 重要文件覆盖：19/53\n- 证据索引条目：19\n- 角色 / Skill 条目：8\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请基于 website 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 website 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 website 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 8 个角色 / Skill / 项目文档条目。\n\n- **Agent Skill Index**（project_doc）：English README.md 繁體中文 README.zh-TW.md 简体中文 README.zh-CN.md 日本語 README.ja.md 한국어 README.ko.md Español README.es.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Getting Started**（project_doc）：This is a Next.js https://nextjs.org project bootstrapped with create-next-app https://nextjs.org/docs/app/api-reference/cli/create-next-app . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`website/README.md`\n- **Contributing to Agent Skill Index 🐍🍎**（project_doc）：Contributing to Agent Skill Index 🐍🍎 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Agent Skill Index**（project_doc）：English README.md 繁體中文 README.zh-TW.md 简体中文 README.zh-CN.md 日本語 README.ja.md 한국어 README.ko.md Español README.es.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.es.md`\n- **Agent Skill Index**（project_doc）：English README.md 繁體中文 README.zh-TW.md 简体中文 README.zh-CN.md 日本語 README.ja.md 한국어 README.ko.md Español README.es.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.ja.md`\n- **Agent Skill Index**（project_doc）：English README.md 繁體中文 README.zh-TW.md 简体中文 README.zh-CN.md 日本語 README.ja.md 한국어 README.ko.md Español README.es.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.ko.md`\n- **Agent Skill Index**（project_doc）：English README.md 繁体中文 README.zh-TW.md 简体中文 README.zh-CN.md 日本語 README.ja.md 한국어 README.ko.md Español README.es.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.zh-CN.md`\n- **Agent Skill Index**（project_doc）：English README.md 繁體中文 README.zh-TW.md 簡體中文 README.zh-CN.md 日本語 README.ja.md 한국어 README.ko.md Español README.es.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.zh-TW.md`\n\n## 证据索引\n\n- 共索引 19 条证据。\n\n- **Agent Skill Index**（documentation）：English README.md 繁體中文 README.zh-TW.md 简体中文 README.zh-CN.md 日本語 README.ja.md 한국어 README.ko.md Español README.es.md 证据：`README.md`\n- **Getting Started**（documentation）：This is a Next.js https://nextjs.org project bootstrapped with create-next-app https://nextjs.org/docs/app/api-reference/cli/create-next-app . 证据：`website/README.md`\n- **Package**（package_manifest）：{ \"name\": \"website\", \"version\": \"0.1.0\", \"private\": true, \"scripts\": { \"dev\": \"next dev\", \"build\": \"next build\", \"start\": \"next start\", \"lint\": \"eslint\" }, \"dependencies\": { \"@react-three/drei\": \"^10.7.7\", \"@react-three/fiber\": \"^9.5.0\", \"@vercel/analytics\": \"^2.0.1\", \"@vercel/speed-insights\": \"^2.0.0\", \"clsx\": \"^2.1.1\", \"d3\": \"^7.9.0\", \"framer-motion\": \"^12.38.0\", \"lucide-react\": \"^1.7.0\", \"next\": \"16.2.2\", \"next-themes\": \"^0.4.6\", \"react\": \"19.2.4\", \"react-dom\": \"19.2.4\", \"tailwind-merge\": \"^3.5.0\", \"three\": \"^0.183.2\" }, \"devDependencies\": { \"@tailwindcss/postcss\": \"^4\", \"@types/d3\": \"^7.4.3\", \"@types/node\": \"^20\", \"@types/react\": \"^19\", \"@types/react-dom\": \"^19\", \"@types/three\": \"^0.183… 证据：`website/package.json`\n- **Contributing to Agent Skill Index 🐍🍎**（documentation）：Contributing to Agent Skill Index 🐍🍎 证据：`CONTRIBUTING.md`\n- **License**（source_file）：Copyright c 2026 Hailey Cheng Cheng Hei Lam 证据：`LICENSE`\n- **Agent Skill Index**（documentation）：English README.md 繁體中文 README.zh-TW.md 简体中文 README.zh-CN.md 日本語 README.ja.md 한국어 README.ko.md Español README.es.md 证据：`README.es.md`\n- **Agent Skill Index**（documentation）：English README.md 繁體中文 README.zh-TW.md 简体中文 README.zh-CN.md 日本語 README.ja.md 한국어 README.ko.md Español README.es.md 证据：`README.ja.md`\n- **Agent Skill Index**（documentation）：English README.md 繁體中文 README.zh-TW.md 简体中文 README.zh-CN.md 日本語 README.ja.md 한국어 README.ko.md Español README.es.md 证据：`README.ko.md`\n- **Agent Skill Index**（documentation）：English README.md 繁体中文 README.zh-TW.md 简体中文 README.zh-CN.md 日本語 README.ja.md 한국어 README.ko.md Español README.es.md 证据：`README.zh-CN.md`\n- **Agent Skill Index**（documentation）：English README.md 繁體中文 README.zh-TW.md 簡體中文 README.zh-CN.md 日本語 README.ja.md 한국어 README.ko.md Español README.es.md 证据：`README.zh-TW.md`\n- **Vercel**（structured_config）：{ \"outputDirectory\": \"website\" } 证据：`vercel.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2017\", \"lib\": \"dom\", \"dom.iterable\", \"esnext\" , \"allowJs\": true, \"skipLibCheck\": true, \"strict\": true, \"noEmit\": true, \"esModuleInterop\": true, \"module\": \"esnext\", \"moduleResolution\": \"bundler\", \"resolveJsonModule\": true, \"isolatedModules\": true, \"jsx\": \"react-jsx\", \"incremental\": true, \"plugins\": { \"name\": \"next\" } , \"paths\": { \"@/ \": \"./src/ \" } }, \"include\": \"next-env.d.ts\", \" / .ts\", \" / .tsx\", \".next/types/ / .ts\", \".next/dev/types/ / .ts\", \" / .mts\" , \"exclude\": \"node modules\" } 证据：`website/tsconfig.json`\n- **Vercel**（structured_config）：{ \"framework\": \"nextjs\", \"outputDirectory\": \".next\" } 证据：`website/vercel.json`\n- **.gitignore**（source_file）：.DS Store 证据：`.gitignore`\n- **See https://help.github.com/articles/ignoring-files/ for more about ignoring files.**（source_file）：See https://help.github.com/articles/ignoring-files/ for more about ignoring files. 证据：`website/.gitignore`\n- **Eslint.Config**（source_file）：import { defineConfig, globalIgnores } from \"eslint/config\"; import nextVitals from \"eslint-config-next/core-web-vitals\"; import nextTs from \"eslint-config-next/typescript\"; 证据：`website/eslint.config.mjs`\n- **theme-toggle{**（source_file）：Agent Skill Index — The Ultimate AI Agent Skills List & Tutorials 🐍🍎 \"/ , ::before, ::after{box-sizing:border-box;margin:0;padding:0} 证据：`website/index.html`\n- **Next.Config**（source_file）：import type { NextConfig } from \"next\"; 证据：`website/next.config.ts`\n- **Postcss.Config**（source_file）：const config = { plugins: { \"@tailwindcss/postcss\": {}, }, }; 证据：`website/postcss.config.mjs`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `website/README.md`, `website/package.json`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `website/README.md`, `website/package.json`\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, README.zh-CN.md, website/package.json\n- **项目结构**：importance `high`\n - source_paths: .gitignore, vercel.json, website/next.config.ts, website/tsconfig.json\n- **什么是Agent Skills**：importance `high`\n - source_paths: README.md\n- **支持的AI代理**：importance `high`\n - source_paths: README.md\n- **技能质量标准**：importance `medium`\n - source_paths: README.md, CONTRIBUTING.md\n- **快速开始**：importance `high`\n - source_paths: README.md, website/src/components/sections/Hero.tsx\n- **使用技能**：importance `high`\n - source_paths: README.md, website/src/components/sections/UsingSkills.tsx\n- **创建技能**：importance `high`\n - source_paths: CONTRIBUTING.md, website/src/components/sections/CreatingSkills.tsx\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `de9056857eb0e96da833469d2ee3ac392058225d`\n- inspected_files: `README.md`\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: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `awesome-agent-skills` 与安装入口 `skills` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | repo=awesome-agent-skills; install=skills\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | host_targets=claude\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 能力判断依赖假设\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:1124920990 | https://github.com/heilcheng/awesome-agent-skills | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_dc99192b4a9b4b8089f4f6696f332a7d | https://github.com/heilcheng/awesome-agent-skills/issues/218 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402)\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_0703404b82014fe3baddd3eaab1100bd | https://github.com/heilcheng/awesome-agent-skills/issues/226 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | release_recency=unknown\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项目：heilcheng/awesome-agent-skills\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 是否匹配：claude\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\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/heilcheng/awesome-agent-skills 项目说明书\n\n生成时间：2026-05-11 16:27:26 UTC\n\n## 目录\n\n- [项目介绍](#page-project-intro)\n- [项目结构](#page-project-structure)\n- [什么是Agent Skills](#page-what-is-agent-skill)\n- [支持的AI代理](#page-compatible-agents)\n- [技能质量标准](#page-skill-quality-standards)\n- [快速开始](#page-quick-start)\n- [使用技能](#page-using-skills)\n- [创建技能](#page-creating-skills)\n- [官方技能目录分类](#page-official-skill-categories)\n- [网站架构](#page-website-architecture)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[项目结构](#page-project-structure), [什么是Agent Skills](#page-what-is-agent-skill)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.md)\n- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)\n- [README.zh-CN.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.zh-CN.md)\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/package.json](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/package.json)\n- [website/src/components/WikiSidebar.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/WikiSidebar.tsx)\n- [website/src/components/sections/Tutorials.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Tutorials.tsx)\n\n
\n\n# 项目介绍\n\n## 项目概述\n\nawesome-agent-skills 是一个专注于 AI Agent Skills（智能体技能）的开源精选列表项目，旨在成为 AI Agent 技能领域最全面的资源集合 资料来源：[README.md:1]()[README.ko.md:1]()。\n\n该项目由 @heilcheng 创建并维护，聚合了来自 Anthropic、OpenAI、GitHub 等主要 AI 平台的技能资源，为开发者提供一站式的技能发现、学习和应用平台 资料来源：[website/src/components/WikiSidebar.tsx:45-50]()。\n\n## 核心价值主张\n\n本项目围绕三大核心用户群体设计其价值主张：\n\n| 用户群体 | 价值主张 | 使用场景 |\n|---------|---------|---------|\n| 初学者 | 零门槛使用技能 | 直接复制 GitHub URL 粘贴到 AI 对话即可 |\n| 团队与企业 | 组织知识封装 | 将操作手册、风格指南、领域流程版本化管理 |\n| 技能开发者 | 一次构建，多端部署 | 一个文件，零基础设施，GitHub 即分享平台 |\n\n资料来源：[website/index.html:85-100]()\n\n## 技术架构\n\n### 项目结构\n\n```\nawesome-agent-skills/\n├── README.md # 项目主文档\n├── README.zh-CN.md # 中文文档\n├── README.ko.md # 韩文文档\n├── skills/ # 技能列表目录\n│ ├── development/ # 开发类技能\n│ ├── data/ # 数据处理类技能\n│ ├── automation/ # 自动化类技能\n│ └── security/ # 安全类技能\n└── website/ # 文档网站\n ├── src/\n │ ├── components/ # React 组件\n │ │ ├── sections/ # 页面区块\n │ │ └── WikiSidebar.tsx # 维基导航侧边栏\n │ └── pages/ # 页面文件\n └── public/ # 静态资源\n```\n\n资料来源：[website/package.json]() [website/src/components/WikiSidebar.tsx:1-60]()\n\n### 前端技术栈\n\n网站采用现代前端技术栈构建：\n\n| 技术 | 版本/用途 | 说明 |\n|-----|----------|------|\n| Next.js | 14+ | React 框架，提供 SSR 和路由 |\n| TypeScript | 类型安全 | 主要开发语言 |\n| Tailwind CSS | 样式框架 | 响应式样式系统 |\n| Lucide React | 图标库 | UI 图标组件 |\n| Framer Motion | 动画库 | 页面过渡和交互动画 |\n\n资料来源：[website/package.json]() [website/src/components/sections/Tutorials.tsx:1-30]()\n\n### Agent Skills 协议\n\nAgent Skills 是一种开放标准协议，最初由 Anthropic 开发，现已被 30+ 款 Agent 产品采用：\n\n```mermaid\ngraph LR\n A[SKILL.md 文件] --> B[元数据 Frontmatter]\n A --> C[指令内容 Markdown]\n B --> D[name 必填]\n B --> E[description 必填]\n B --> F[license 可选]\n B --> G[compatibility 可选]\n B --> H[metadata 可选]\n B --> I[allowed-tools 可选]\n C --> J[When to use]\n C --> K[Instructions]\n C --> L[Gotchas]\n C --> M[Examples]\n C --> N[Validation]\n```\n\n资料来源：[website/index.html:150-180]()\n\n## 技能加载机制\n\n### 渐进式加载流程\n\nAgent Skills 采用\"渐进式披露\"（Progressive Disclosure）设计理念，遵循四阶段加载模型：\n\n```mermaid\ngraph TD\n A[启动时] --> B[阶段1: 发现 Discovery]\n A --> A1[仅加载 name 和 description
~50-100 tokens/skill]\n \n B --> C{用户任务匹配?}\n C -->|是| D[阶段2: 激活 Activation]\n C -->|否| E[保持轻量]\n \n D --> F[加载完整 SKILL.md]\n F --> G[指令、示例、脚本]\n \n D --> H{需要脚本?}\n H -->|是| I[阶段3: 脚本执行]\n H -->|否| J[直接执行指令]\n \n I --> K[阶段4: 验证 Validation]\n J --> K\n```\n\n资料来源：[website/index.html:220-250]()\n\n### 技能存储位置\n\n技能文件支持多种存储路径，兼容不同 Agent 客户端：\n\n| 路径 | 用途 | 典型应用 |\n|-----|------|---------|\n| `~/.claude/skills/` | 用户级技能 | Claude Code / Claude.ai |\n| `~/.agents/skills/` | 全局技能 | 通用 Agent 客户端 |\n| `.claude/skills/` | 项目级技能 | 项目专属配置 |\n| `.github/skills/` | GitHub 存储 | GitHub 原生集成 |\n\n资料来源：[website/index.html:30-35]() [website/src/components/sections/UsingSkills.tsx:40-50]()\n\n## 功能特性\n\n### 技能分类体系\n\n项目按照技能功能进行系统化分类：\n\n- **development** — 开发类技能（代码审查、重构、测试生成等）\n- **data** — 数据处理类技能（数据分析、转换、ETL 等）\n- **automation** — 自动化类技能（CI/CD、部署、监控等）\n- **security** — 安全类技能（代码扫描、依赖审计等）\n\n资料来源：[website/src/components/sections/FindingSkills.tsx:1-20]()\n\n### 技能质量标准\n\n每个技能遵循统一的质量规范：\n\n| 维度 | 要求 | 说明 |\n|-----|------|------|\n| **结构化指令** | 清晰的步骤分解 | 避免模糊描述，精确指导 |\n| **触发条件** | 明确的激活条件 | 让 Agent 准确判断何时使用 |\n| **示例覆盖** | 丰富的输入输出示例 | 减少理解歧义 |\n| **验证机制** | 内置检查流程 | 自我验证输出正确性 |\n| **错误处理** | 预判常见问题 | Gotchas 章节记录坑点 |\n\n资料来源：[website/src/components/sections/QualityStandards.tsx:1-30]()\n\n### 命令行工具支持\n\n通过 `npx skills` CLI 可快速管理技能：\n\n| 命令 | 功能 |\n|-----|------|\n| `npx skills find [query]` | 搜索相关技能 |\n| `npx skills add ` | 添加技能（支持 GitHub 简写/完整 URL/本地路径） |\n| `npx skills list` | 列出已安装技能 |\n| `npx skills check` | 检查更新 |\n| `npx skills update` | 升级所有技能 |\n| `npx skills remove [skill-name]` | 移除技能 |\n\n资料来源：[README.ko.md:15-25]()\n\n## 兼容的 Agent 平台\n\n项目支持的 Agent 产品矩阵：\n\n| Agent | 文档链接 |\n|-------|---------|\n| Claude Code | code.claude.com/docs/en/skills |\n| Claude.ai | support.claude.com/articles/12512180 |\n| Codex (OpenAI) | developers.openai.com/codex |\n| Cursor | cursor.com/docs |\n| Copilot | github.com/features/copilot |\n| Gemini CLI | developers.google.com/gemini-code-assistant |\n\n资料来源：[README.ko.md:30-40]()\n\n## 快速入门\n\n### 使用现有技能\n\n```mermaid\ngraph LR\n A[浏览 awesome-agent-skills] --> B[找到目标技能]\n B --> C[复制 GitHub URL]\n C --> D{客户端类型}\n D -->|Claude Code| E[/skills add ]\n D -->|Claude.ai| F[粘贴原始 URL]\n D -->|其他 CLI| G[npx skills add]\n E --> H[用自然语言请求任务]\n F --> H\n G --> H\n```\n\n### 开发新技能\n\n创建新技能的推荐步骤：\n\n1. 创建以技能命名的文件夹\n2. 在文件夹内创建 `SKILL.md` 文件\n3. 编写 YAML frontmatter（name 和 description 必填）\n4. 在 Markdown 正文编写结构化指令\n5. （可选）在 `scripts/` 子目录添加可执行脚本\n\n资料来源：[website/index.html:40-70]()\n\n## 国际化支持\n\n项目文档支持多语言版本：\n\n| 语言 | 文件 | 路径 |\n|-----|------|------|\n| 英语 | README.md | 根目录 |\n| 中文 | README.zh-CN.md | 根目录 |\n| 韩语 | README.ko.md | 根目录 |\n\n资料来源：[README.zh-CN.md:1]() [README.ko.md:1]()\n\n## 相关资源\n\n| 资源 | 链接 |\n|-----|------|\n| 官方规范 | agentskills.io/specification |\n| CLI 工具 | vercel-labs/skills |\n| 项目网站 | agent-skill.co |\n| GitHub 仓库 | github.com/heilcheng/awesome-agent-skills |\n\n资料来源：[website/index.html:280-300]() [website/src/components/WikiSidebar.tsx:40-45]()\n\n---\n\n\n\n## 项目结构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-project-intro), [网站架构](#page-website-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/SkillDirectory.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/SkillDirectory.tsx)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/FindingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/FindingSkills.tsx)\n- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)\n- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)\n
\n\n# 项目结构\n\n## 概述\n\nawesome-agent-skills 是一个用于收录和管理 AI Agent 技能（Agent Skills）的开源项目仓库。该项目采用现代化的 Web 技术栈构建，为 AI Agent 提供可复用的技能库和文档站点。\n\n## 技术栈概览\n\n| 技术类别 | 具体技术 |\n|---------|---------|\n| 前端框架 | Next.js (TypeScript) |\n| 样式方案 | Tailwind CSS + 自定义 CSS 变量 |\n| 动画效果 | Framer Motion |\n| 图标库 | Lucide React |\n| 部署平台 | Vercel |\n| 包管理 | npm/pnpm |\n\n资料来源：[README.ko.md:1-20]()\n\n## 目录结构\n\n```text\nawesome-agent-skills/\n├── .gitignore # Git 忽略配置\n├── README.md # 项目主文档\n├── README.ko.md # 韩语文档\n├── README.zh.md # 中文文档\n├── vercel.json # Vercel 部署配置\n└── website/ # 主站点目录\n ├── next.config.ts # Next.js 配置文件\n ├── tsconfig.json # TypeScript 配置\n ├── package.json # 依赖管理\n ├── public/ # 静态资源目录\n └── src/\n ├── app/ # Next.js App Router\n │ ├── layout.tsx # 根布局组件\n │ ├── page.tsx # 首页组件\n │ └── globals.css # 全局样式\n ├── components/ # React 组件库\n │ ├── sections/ # 页面区块组件\n │ └── Footer.tsx # 页脚组件\n └── lib/ # 工具函数库\n```\n\n资料来源：[website/src/components/sections/SkillDirectory.tsx:1-50]()\n\n## Website 模块架构\n\n### 组件层级结构\n\n```mermaid\ngraph TD\n A[App Router] --> B[Root Layout]\n B --> C[Page Component]\n C --> D[Section Components]\n \n D --> E[SkillDirectory]\n D --> F[QualityStandards]\n D --> G[UsingSkills]\n D --> H[FindingSkills]\n D --> I[Footer]\n \n E --> J[Framer Motion Animations]\n F --> K[Good/Bad Pattern Cards]\n G --> L[CLI Code Panels]\n H --> M[External Resource Links]\n```\n\n### 核心组件说明\n\n#### SkillDirectory 组件\n\n负责技能目录的展示和搜索过滤功能。该组件使用 Framer Motion 实现布局动画，支持按名称和描述进行技能搜索。\n\n```typescript\n// 核心数据结构\n{ filtered: skill[] }\n```\n\n资料来源：[website/src/components/sections/SkillDirectory.tsx:1-80]()\n\n#### QualityStandards 组件\n\n展示技能的 Quality Standards（质量标准），包含好/坏代码模式对比卡片，帮助开发者理解最佳实践。\n\n| 组件元素 | 功能描述 |\n|---------|---------|\n| Good Pattern | 展示推荐代码模式 |\n| Bad Pattern | 展示应避免的代码模式 |\n| Pattern Description | 模式说明文字 |\n\n资料来源：[website/src/components/sections/QualityStandards.tsx:1-60]()\n\n#### UsingSkills 组件\n\n提供技能使用指南，包含 CLI 命令示例和复制功能。该组件实现了代码复制交互逻辑。\n\n| 功能模块 | 说明 |\n|---------|------|\n| CLI 代码面板 | 展示 `npx skills add` 等命令 |\n| 复制按钮 | 支持一键复制到剪贴板 |\n| 视觉反馈 | 复制成功后显示 Check 图标 |\n\n资料来源：[website/src/components/sections/UsingSkills.tsx:1-70]()\n\n#### FindingSkills 组件\n\n展示如何发现和获取技能的外部资源链接，支持 Marketplace 和 CLI 工具类资源的展示。\n\n```typescript\n// 资源类型\ntype ResourceType = 'marketplace' | 'leaderboard' | 'cli' | 'general'\n```\n\n资料来源：[website/src/components/sections/FindingSkills.tsx:1-60]()\n\n#### Footer 组件\n\n页面底部组件，包含版权信息、社交链接和联系方式。\n\n| 链接类型 | URL/功能 |\n|---------|---------|\n| 官方网站 | agent-skill.co |\n| GitHub | 项目仓库 |\n| Twitter/X | 开发者账号 |\n| 邮箱 | haileycheng@proton.me |\n\n资料来源：[website/src/components/Footer.tsx:1-50]()\n\n## 主题与样式系统\n\n### 暗色模式支持\n\n项目使用 CSS 变量实现暗色/亮色主题切换：\n\n```css\n:root {\n --bg: #000;\n --text: rgba(255, 255, 255, 0.95);\n --border: rgba(255, 255, 255, 0.08);\n}\n\n[data-theme=\"light\"] {\n /* 亮色模式变量覆盖 */\n}\n```\n\n### 色彩系统\n\n| 用途 | 颜色变量 |\n|-----|---------|\n| 主色（蓝色） | `#0a84ff` |\n| 辅助色（紫色） | `#bf5af2` |\n| 成功色（绿色） | `#30d158` |\n| 警告色（橙色） | `#ff9f0a` |\n\n资料来源：[website/index.html:1-100]()\n\n## 技能目录组织\n\n### 目录结构规范\n\n技能按照分类组织，每个技能包含：\n\n```\nskill-name/\n├── SKILL.md # 必选：技能定义文件\n└── scripts/ # 可选：辅助脚本目录\n ├── script.py # Python 脚本（PEP 723 格式）\n └── script.sh # Shell 脚本\n```\n\n### SKILL.md 格式规范\n\n每个技能必须包含 YAML frontmatter：\n\n```yaml\n---\nname: skill-name # 必选：技能名称（小写 + 连字符）\ndescription: >- # 必选：功能描述\n 1-512 字符，用于 Agent 发现和激活\nlicense: Apache-2.0 # 可选：开源许可证\ncompatibility: Python 3.11+ # 可选：环境要求\nmetadata: # 可选：元数据\n author: example-org\n version: \"1.0\"\nallowed-tools: Bash Read Write # 可选：预批准工具列表\n---\n```\n\n资料来源：[website/index.html:200-300]()\n\n## 构建与部署\n\n### Vercel 部署配置\n\n项目通过 `vercel.json` 配置自动化部署流程：\n\n```json\n{\n \"buildCommand\": \"npm run build\",\n \"outputDirectory\": \".next\",\n \"installCommand\": \"npm install\"\n}\n```\n\n### Next.js 配置要点\n\n| 配置项 | 说明 |\n|-------|------|\n| `reactStrictMode` | 启用 React 严格模式 |\n| `images` | 图片优化配置 |\n| `env` | 环境变量管理 |\n\n资料来源：[website/next.config.ts]()\n\n## 开发工作流\n\n```mermaid\ngraph LR\n A[代码编写] --> B[TypeScript 检查]\n B --> C[ESLint 检查]\n C --> D[Next.js Build]\n D --> E[Vercel Preview]\n E --> F[合并到 Main]\n F --> G[自动部署生产环境]\n```\n\n## 资源链接\n\n| 资源类型 | 链接 |\n|---------|------|\n| 项目官网 | agent-skill.co |\n| GitHub 仓库 | github.com/heilcheng/awesome-agent-skills |\n| 官方规范 | agentskills.io/specification |\n| CLI 工具 | vercel-labs/skills |\n\n资料来源：[website/src/components/Footer.tsx:1-40]()\n\n## 总结\n\nawesome-agent-skills 项目采用现代化的 Next.js + TypeScript 技术栈，构建了一个用于管理和展示 AI Agent 技能的文档站点。项目的组件化设计使其具有良好的可维护性和扩展性，同时通过 Vercel 平台实现了自动化的 CI/CD 流程。\n\n---\n\n\n\n## 什么是Agent Skills\n\n### 相关页面\n\n相关主题：[支持的AI代理](#page-compatible-agents), [快速开始](#page-quick-start)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/WhatIsIt.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/WhatIsIt.tsx)\n- [website/src/components/sections/Contributing.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Contributing.tsx)\n- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)\n\n
\n\n# 什么是Agent Skills\n\n## 概述\n\nAgent Skills 是一个开放的 AI Agent 技能标准，旨在让 AI 助手能够学习和掌握特定任务的执行能力。简单来说，Agent Skill 就是一个纯文本指令文件（称为 `SKILL.md`），它教会 AI 如何完成特定任务。把它想象成一张食谱卡：AI 阅读它，按照步骤执行，就能完成任务。资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 核心特点\n\nAgent Skills 具有以下核心特点，使其区别于传统的提示工程方法：\n\n| 特点 | 描述 |\n|------|------|\n| **按需加载** | 技能只在需要时加载，AI 保持快速响应 |\n| **零基础设施** | 不需要复杂的部署环境，一个文件即可 |\n| **版本控制** | 可以像普通项目一样在 GitHub 上共享和管理 |\n| **跨平台兼容** | 兼容 30+ 个 AI 开发平台，无需修改即可通用 |\n| **纯文本格式** | 使用 Markdown 编写，无需编程基础 |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## SKILL.md 文件格式规范\n\n### 文件结构\n\n每个 Agent Skill 存放在一个独立的文件夹中，文件夹内必须包含 `SKILL.md` 文件。推荐的标准目录结构如下：\n\n```\nskill-name/\n├── SKILL.md # 必需：主要指令文件\n└── scripts/ # 可选：辅助脚本目录\n └── example.py\n```\n\n### Frontmatter 元数据\n\n每个 `SKILL.md` 文件以 YAML frontmatter 开头，其中 `name` 和 `description` 是必填字段：\n\n```yaml\n---\nname: pdf-processing\ndescription: Extract and summarize text from PDF documents\n---\n```\n\n#### name 字段规范\n\n| 规则 | 要求 |\n|------|------|\n| 字符集 | 仅小写字母、数字和连字符 |\n| 长度 | 1-64 个字符 |\n| 匹配 | 必须与父目录名称一致 |\n| 禁止 | 连续连字符、首尾连字符 |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 推荐的正文章节结构\n\n`SKILL.md` 的 Markdown 正文部分没有格式限制，但推荐使用以下标准结构，以便 Agent 更好地理解和执行：\n\n```markdown\n## 何时使用此技能\n触发条件、适用范围和局限性。\n\n## 指令\n逐步操作步骤，要明确具体。\n\n## 注意事项\n特定于环境的事实，容易出错的地方。\n\n## 示例\n具体的输入 → 输出对。\n\n## 验证\n如何验证输出是否正确。\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 工作原理\n\nAgent Skills 采用渐进式披露（Progressive Disclosure）设计模式，在不同阶段加载不同深度的信息：\n\n```mermaid\ngraph TD\n A[启动 Agent] --> B[轻量级扫描]\n B --> C[加载 name 和 description]\n C --> D{任务匹配?}\n D -->|否| E[不使用技能]\n D -->|是| F[按需加载完整 SKILL.md]\n F --> G[执行技能指令]\n G --> H[运行 scripts/ 中的脚本]\n H --> I[任务完成]\n \n style B fill:#e1f5fe\n style F fill:#fff3e0\n```\n\n### 阶段一：发现（Discovery）\n\n在启动时，Agent 仅加载每个可用技能的 `name` 和 `description`，每个技能约 50-100 个 token。此阶段不会加载任何实际指令内容。资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 阶段二：激活（Activation）\n\n当用户的任务与某个技能的描述匹配时，Agent 将完整的 `SKILL.md` 读入上下文。此时加载的内容包括详细的指令、示例和脚本。\n\n### 阶段三：执行（Execution）\n\nAgent 根据技能指令执行任务，必要时可运行 `scripts/` 子目录中的可执行文件。\n\n## 安装与使用\n\n### 三种使用视角\n\n```mermaid\ngraph LR\n A[新手用户] --> |复制 GitHub URL| B[粘贴到 AI 对话]\n C[团队/企业] --> |捕获组织知识| D[版本控制的技能包]\n E[技能作者] --> |一次构建| F[跨平台部署]\n \n style A fill:#c8e6c9\n style C fill:#bbdefb\n style E fill:#ffe0b2\n```\n\n#### 新手用户\n\n1. 浏览技能目录\n2. 复制技能的 GitHub URL\n3. 将 URL 粘贴到 AI 对话中\n\n#### 团队和企业\n\n将组织知识（如操作手册、风格指南、领域流程）捕获为可移植的版本控制技能包。资料来源：[website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n\n### CLI 安装方式\n\n```bash\n# Claude Code\nnpx skills add anthropics/skills/docx\n\n# 或使用 GitHub 简写格式\nnpx skills add //\n```\n\n### 手动安装路径\n\n对于某些平台，可以直接将技能文件夹放置到指定目录：\n\n| 平台 | 安装路径 |\n|------|----------|\n| Claude Code | `~/.claude/skills/` |\n| 通用 Agent | `.agents/skills/` |\n| GitHub Actions | `.github/skills/` |\n\n资料来源：[website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n\n## 兼容平台\n\nAgent Skills 是一个被主要 AI 开发工具采用的开放标准。创建的技能无需修改即可在以下平台使用：\n\n| 平台类别 | 工具列表 |\n|----------|----------|\n| Anthropic | Claude Code, Claude.ai |\n| OpenAI | Codex |\n| Microsoft | GitHub Copilot |\n| IDE 插件 | Cursor |\n| 其他 | 30+ 兼容平台 |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 脚本支持\n\nAgent 可以运行 `scripts/` 子目录中的可执行文件。设计脚本时应考虑 Agent 的特性：\n\n```python\n#!/usr/bin/env -S uv run\n# /// script\n# requires-python = \">= 3.11\"\n# dependencies = [\"requests\", \"rich\"]\n# ///\n\nimport sys, json\n\n# 避免交互式提示\n# 使用结构化输出 (JSON/CSV)\n# 将错误写入 stderr\n# 使用有意义的退出码\nprint(json.dumps({\"result\": \"ok\"}))\n```\n\n### 脚本设计原则\n\n| 原则 | 说明 |\n|------|------|\n| 避免交互 | 不要使用 input() 或交互式提示 |\n| 结构化输出 | 使用 JSON 或 CSV 格式 |\n| 错误处理 | 将错误信息写入 stderr |\n| 明确退出码 | 使用有意义的退出码 |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 技能质量标准\n\n### 好的技能 vs 差的技能\n\n#### 优秀技能的编写模式\n\n- 使用清晰的步骤编号\n- 提供具体的触发条件\n- 包含实际的输入输出示例\n- 明确说明验证方法\n\n#### 需要避免的模式\n\n- 模糊不清的指令\n- 缺少上下文说明\n- 没有错误处理指引\n- 缺乏实际案例\n\n资料来源：[website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n\n## 创建你的第一个技能\n\n创建步骤非常简单：\n\n```mermaid\ngraph LR\n A[创建文件夹] --> B[命名技能]\n B --> C[创建 SKILL.md]\n C --> D[添加 name 和 description]\n D --> E[编写指令正文]\n E --> F[放置到 skills 目录]\n```\n\n1. 创建一个以技能名称命名的文件夹\n2. 在文件夹内创建 `SKILL.md` 文件\n3. 在文件顶部添加 YAML frontmatter（name 和 description）\n4. 在下方用纯英文编写你的指令\n5. 将文件夹放置到 `.claude/skills/` 或 `.github/skills/` 目录\n\n资料来源：[website/src/components/sections/Contributing.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Contributing.tsx)\n\n## 总结\n\nAgent Skills 提供了一种轻量级、标准化的方式来扩展 AI Agent 的能力。通过将任务指令封装为可移植的 `SKILL.md` 文件，用户可以：\n\n- **快速分享**：通过 GitHub URL 一键分享技能\n- **版本控制**：像代码一样管理技能版本\n- **跨平台使用**：一次创建，多平台通用\n- **零门槛创作**：纯文本格式，无需编程基础\n\n这种设计让 AI 助手能够\"学会\"执行特定任务，同时保持核心的快速响应特性。资料来源：[website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)\n\n---\n\n\n\n## 支持的AI代理\n\n### 相关页面\n\n相关主题：[使用技能](#page-using-skills), [什么是Agent Skills](#page-what-is-agent-skill)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)\n- [website/src/components/sections/WhatIsIt.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/WhatIsIt.tsx)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)\n
\n\n# 支持的AI代理\n\n## 概述\n\nAgent Skill Index 是一个兼容多种 AI 代理系统的技能索引平台，旨在为不同 AI 助手提供统一的技能（Skill）管理规范。该项目定义了标准化的 SKILL.md 格式，使开发者能够创建一次技能，即可在多个支持该规范的 AI 代理上使用。\n\n该平台兼容的主流 AI 代理包括 **Claude**、**Codex**、**Copilot** 以及其他遵循 agentskills.io 规范的代理工具。资料来源：[website/index.html:1-10]()\n\n## 支持的AI代理列表\n\n### 主流支持的代理\n\n| 代理名称 | 平台类型 | 技能加载方式 | 官方文档 |\n|---------|---------|------------|---------|\n| Claude | Anthropic | /skills add 命令或粘贴 URL | Claude.ai / Claude Code |\n| Codex | OpenAI | npx skills add | OpenAI Codex 文档 |\n| Copilot | Microsoft | npx skills add | GitHub Copilot 文档 |\n| Claude Code | Anthropic CLI | /skills add | Claude Code 文档 |\n\n资料来源：[website/index.html:1-10]()\n\n### 代理兼容性说明\n\n所有支持的 AI 代理都需要遵循 agentskills.io 规范来实现技能加载功能。该规范定义了技能文件的结构、YAML 前端定义以及渐进式加载机制。\n\n```mermaid\ngraph TD\n A[AI 代理启动] --> B[扫描技能目录]\n B --> C{是否匹配用户任务}\n C -->|是| D[加载完整 SKILL.md]\n C -->|否| E[保持轻量模式]\n D --> F[执行技能指令]\n E --> G[等待匹配]\n F --> H[返回结果]\n```\n\n资料来源：[website/index.html:180-200]()\n\n## 技能加载机制\n\n### 渐进式披露设计\n\nAgent Skills 采用渐进式披露（Progressive Disclosure）设计理念，在不同阶段加载不同程度的信息：\n\n1. **启动时扫描**：仅加载每个技能的 `name` 和 `description` 字段，约 50-100 token/技能\n2. **按需激活**：当用户任务与技能描述匹配时，读取完整的 SKILL.md 内容\n3. **指令执行**：根据技能指令和可选脚本完成任务\n\n```mermaid\ngraph TD\n A[启动] --> B[扫描技能目录
~project/.agents/skills/
~/.agents/skills/
~/.claude/skills/]\n B --> C[加载 name + description]\n C --> D[等待用户任务]\n D --> E{任务匹配检测}\n E -->|匹配 skill description| F[加载完整 SKILL.md]\n E -->|不匹配| D\n F --> G[执行指令与脚本]\n G --> H[验证输出]\n H --> I[返回结果]\n```\n\n资料来源：[website/index.html:180-200]()\n\n### 技能目录结构\n\n支持的技能目录位置根据不同 AI 代理有所不同：\n\n| 目录路径 | 适用代理 | 说明 |\n|---------|---------|------|\n| `.claude/skills/` | Claude Code | 项目级技能目录 |\n| `.github/skills/` | GitHub 集成 | 企业级技能目录 |\n| `~/.agents/skills/` | 通用 | 用户级技能目录 |\n| `.agents/skills/` | 通用 | 本地技能目录 |\n\n资料来源：[website/index.html:180-200]()\n\n## 技能格式规范\n\n### SKILL.md 结构\n\n每个技能由 YAML 前端定义和 Markdown 正文组成：\n\n```yaml\n---\nname: pdf-processing\ndescription: >\n Extract text and tables from PDF files, fill PDF forms, and merge\n multiple PDFs. Use when working with PDF documents, forms, or when\n the user mentions PDFs, document extraction, or form filling.\nlicense: Apache-2.0\ncompatibility: Requires Python 3.11+ and uv\nmetadata:\n author: example-org\n version: \"1.0\"\nallowed-tools: Bash(uv:*) Read Write\n---\n```\n\n### 前端字段说明\n\n| 字段名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| name | string | 是 | 小写字母、数字、连字符，1-64字符 |\n| description | string | 是 | 技能描述，激活条件判断依据 |\n| license | string | 否 | 技能许可证类型 |\n| compatibility | string | 否 | 兼容性要求说明 |\n| metadata | object | 否 | 作者、版本等元数据 |\n| allowed-tools | string | 否 | 预批准的工具列表（实验性） |\n\n资料来源：[website/index.html:30-80]()\n\n### 推荐正文结构\n\n```markdown\n## When to use this skill\n触发条件、范围和限制说明。\n\n## Instructions\n逐步操作流程，需要明确具体。\n\n## Gotchas\n环境特定的事实，不符合预期的行为。\n\n## Examples\n具体的输入输出示例。\n\n## Validation\n如何验证输出正确性。\n```\n\n资料来源：[website/index.html:120-150]()\n\n## 工具与脚本支持\n\n### 脚本目录\n\n技能可包含可选的 `scripts/` 子目录存放可执行文件：\n\n```bash\nmy-skill/\n├── SKILL.md\n└── scripts/\n ├── extract.py\n └── ocr.py\n```\n\n### 代理友好脚本设计原则\n\n1. **非交互式**：避免交互式提示\n2. **结构化输出**：使用 JSON/CSV 而非自由文本\n3. **错误处理**：诊断信息输出到 stderr\n4. **退出码**：使用有意义的退出代码\n\n```python\n#!/usr/bin/env -S uv run\n# /// script\n# requires-python = \">= 3.11\"\n# dependencies = [\"requests\", \"rich\"]\n# ///\nimport sys, json\n\n# 正确示范\nprint(json.dumps({\"result\": \"ok\"})) # 数据到 stdout\nsys.exit(0) # 有意义的退出码\n```\n\n资料来源：[website/index.html:120-150]()\n\n## 质量标准\n\n### 技能质量要素\n\n| 要素 | 说明 |\n|-----|------|\n| 明确性 | 指令清晰、无歧义 |\n| 可验证性 | 内置验证流程 |\n| 隔离性 | 不依赖未声明的环境 |\n| 简洁性 | 避免不必要的复杂性 |\n\n### 好的示例 vs 坏的示例\n\n**好的模式**：\n```markdown\n1. First, verify the input is valid JSON.\n2. Then, run `scripts/validate.py` to check schema.\n3. If validation fails, stop and report the error.\n```\n\n**坏的模式**：\n```markdown\n1. Do something with the file.\n2. Maybe check if it's correct.\n3. Continue if it looks okay.\n```\n\n资料来源：[website/src/components/sections/QualityStandards.tsx:1-50]()\n\n## 官方规范资源\n\n完整的 SKILL.md 格式规范、目录结构要求、渐进式披露设计以及客户端实现指南可在官方规范页面获取：\n\n| 资源 | 地址 |\n|-----|------|\n| 官方规范 | agentskills.io/specification |\n| GitHub 仓库 | github.com/heilcheng/awesome-agent-skills |\n| 作者联系 | LinkedIn @haileyhmt / Email haileycheng@proton.me |\n\n资料来源：[website/index.html:200-250]()\n\n## 快速入门\n\n### 新手使用步骤\n\n1. **找到技能**：浏览技能目录，按类别（开发、数据、自动化、安全等）组织\n2. **加载到AI**：复制 GitHub URL，根据不同平台使用对应命令\n3. **用自然语言提问**：AI 自动读取技能指令并执行\n\n```bash\n# Claude Code\n/skills add \n\n# Claude.ai\n粘贴 raw SKILL.md URL 到聊天窗口\n```\n\n### 企业团队使用\n\n捕获组织知识——操作手册、风格指南、领域流程——以可移植的版本控制包形式存储，实现跨团队共享和复用。\n\n资料来源：[website/src/components/sections/WhatIsIt.tsx:1-30]()\n[website/src/components/sections/UsingSkills.tsx:1-50]()\n\n---\n\n\n\n## 技能质量标准\n\n### 相关页面\n\n相关主题：[创建技能](#page-creating-skills)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)\n
\n\n# 技能质量标准\n\n## 概述\n\n技能质量标准（Skill Quality Standards）是 awesome-agent-skills 项目为确保 AI Agent 技能（Skills）具备一致性、可复用性和高效性而制定的一系列规范与最佳实践。这些标准涵盖了技能的元数据定义、内容结构、编写原则以及验证方法，旨在帮助技能作者创建高质量、可维护的技能文件。\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 核心质量维度\n\n技能的 quality 由以下五个核心维度构成：\n\n| 维度 | 编号 | 核心原则 | 关键要求 |\n|------|------|----------|----------|\n| 作用域设计 | 01 | 设计内聚、适度规模的技能 | 避免过窄（浪费开销）或过宽（失去焦点） |\n| 指令编写 | 03 | 添加 Agent 缺乏的内容；跳过 Agent 已知的部分 | 聚焦项目约定、领域特定流程和边缘情况 |\n| 控制策略 | 04 | 仅在重要时刻做规定性要求 | 多种方案等效时给予自由；操作脆弱、不可逆或必须按特定顺序时明确严格 |\n| 脚本设计 | 05 | 使脚本对 Agent 友好 | 非交互式标志、结构化输出、有意义的退出码 |\n| 验证机制 | 06 | 将验证循环构建到指令中 | 检查表、输出模板匹配、计划-验证-执行模式 |\n\n资料来源：[website/index.html:1-150](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## SKILL.md 元数据标准\n\n### 必需字段\n\n每个技能必须包含以下 YAML 前端格式（Frontmatter）字段：\n\n```yaml\n---\nname: pdf-processing # 必需：技能名称\ndescription: >- # 必需：技能描述\n 1-1024 个字符的描述文本\n---\n```\n\n| 字段 | 类型 | 限制 | 说明 |\n|------|------|------|------|\n| `name` | 必需 | 1-64 字符 | 仅使用小写字母、数字和连字符；禁止连续连字符；禁止首尾连字符；必须与父目录名匹配 |\n| `description` | 必需 | 1-1024 字符 | Agent 启动时读取的关键字段，用于决定是否激活技能；应描述技能功能和使用场景 |\n\n**name 字段示例：**\n\n```\nname: pdf-processing\nname: code-review\nname: data-analysis\n```\n\n**description 字段质量标准：**\n\n| 质量等级 | 示例 |\n|----------|------|\n| 良好 | \"Extracts text and tables from PDF files. Use when working with PDFs, forms, or document extraction.\" |\n| 不佳 | \"Helps with PDFs.\" |\n\n资料来源：[website/index.html:1-100](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 可选字段\n\n| 字段 | 类型 | 限制 | 说明 |\n|------|------|------|------|\n| `license` | 可选 | 许可证名称或文件名 | 保持技能包自包含 |\n| `compatibility` | 可选 | 1-500 字符 | 仅在存在特定环境要求时使用 |\n| `metadata` | 可选 | 键值对 | 作者、版本等元数据 |\n| `allowed-tools` | 可选·实验性 | 空格分隔的工具列表 | 预批准可运行的工具，减少操作确认提示 |\n\n资料来源：[website/index.html:1-80](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 内容结构标准\n\n### 推荐章节结构\n\n技能的 Markdown 正文部分应包含以下五个核心章节：\n\n```markdown\n## When to use this skill\n触发条件、适用范围和限制说明。\n\n## Instructions\n逐步操作程序。保持明确具体。\n\n## Gotchas\n环境特定的事实。违反常规预期的事项。\n\n## Examples\n具体的输入→输出示例对。\n\n## Validation\n如何验证输出是否正确。\n```\n\n资料来源：[website/index.html:1-60](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 最小示例\n\n```yaml\n---\nname: roll-dice\ndescription: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.).\n---\n\nTo roll a die, run:\n```bash\necho $((RANDOM % + 1))\n```\n```\n\n## 规模限制标准\n\n| 指标 | 上限 | 拆分阈值 |\n|------|------|----------|\n| 代码行数 | 500 行以内 | 超过时拆分为引用文件 |\n| Token 数量 | 5,000 token 以内 | 超过时拆分为多个技能 |\n\n> **经验法则：** 超过 500 行或 5,000 token 的技能应拆分为引用文件。\n\n资料来源：[website/index.html:1-50](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 渐进式披露机制\n\n技能采用渐进式披露（Progressive Disclosure）设计，按需加载以保持性能：\n\n```mermaid\ngraph TD\n A[Agent 启动] --> B[轻量级扫描]\n B --> C[仅加载 name 和 description]\n C --> D{任务匹配?}\n D -->|是| E[加载完整 SKILL.md]\n D -->|否| F[不加载指令]\n E --> G[执行技能指令]\n F --> H[使用通用能力]\n```\n\n### 目录扫描位置\n\nAgent 在以下位置扫描技能目录：\n\n| 级别 | 路径 |\n|------|------|\n| 项目级（共享） | `.agents/skills/` |\n| 用户级（个人） | `~/.agents/skills/` |\n| Claude Code 专用 | `.claude/skills/` 或 `~/.claude/skills/` |\n\n资料来源：[website/index.html:1-80](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 脚本设计标准\n\n### PEP 723 内联依赖\n\n当技能需要脚本时，推荐使用 Python PEP 723 内联依赖格式：\n\n```python\n#!/usr/bin/env -S uv run\n# /// script\n# requires-python = \">= 3.11\"\n# dependencies = [\"requests\", \"rich\"]\n# ///\n```\n\n### Agent 友好脚本原则\n\n| 原则 | 具体要求 |\n|------|----------|\n| 避免交互提示 | Agent 无法响应交互式提示 |\n| 结构化输出 | 使用 JSON/CSV 而非自由文本 |\n| 错误处理 | 将错误写入 stderr |\n| 退出码 | 使用有意义的退出码 |\n\n**推荐模式：**\n\n```mermaid\ngraph LR\n A[数据] -->|stdout| B[结构化输出]\n C[诊断信息] -->|stderr| D[日志/错误]\n E[执行结果] -->|退出码| F[0=成功, 非0=失败]\n```\n\n资料来源：[website/index.html:1-90](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 验证机制标准\n\n### 验证模式\n\n高质量技能应包含内置验证循环：\n\n1. **检查表验证**：多步骤工作流的逐项确认\n2. **输出模板匹配**：验证返回结果符合预期格式\n3. **计划-验证-执行模式**：破坏性操作的三阶段确认\n\n### 验证示例\n\n> **示例：** \"提交前，运行测试并确认全部通过。如果测试失败，修复后重新运行。\"\n\n```markdown\n## Validation\n\n1. [ ] 步骤一完成\n2. [ ] 步骤二完成\n3. [ ] 输出格式验证通过\n4. [ ] 错误日志为空\n```\n\n资料来源：[website/index.html:1-70](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 兼容性标准\n\n### 支持的 Agent 平台\n\n技能作为开放标准，被以下 30+ 平台支持：\n\n| 平台 | 状态 |\n|------|------|\n| Claude Code | ✅ 官方支持 |\n| Claude.ai | ✅ 官方支持 |\n| GitHub Copilot | ✅ 官方支持 |\n| VS Code | ✅ 官方支持 |\n| OpenAI Codex | ✅ 官方支持 |\n| Google Antigravity | ✅ 官方支持 |\n| Gemini CLI | ✅ 官方支持 |\n| Cursor | ✅ 官方支持 |\n| Kiro | ✅ 官方支持 |\n\n资料来源：[website/index.html:1-50](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 技能目录结构\n\n```\nmy-skill/\n├── SKILL.md # 必需：技能定义文件\n├── scripts/ # 可选：可执行脚本目录\n│ ├── script1.py # Agent 可调用的脚本\n│ └── script2.sh\n└── README.md # 可选：额外文档\n```\n\n资料来源：[website/index.html:1-40](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n## 质量检查清单\n\n创建技能时的自检清单：\n\n- [ ] `name` 字段符合命名规范（小写字母、数字、连字符）\n- [ ] `description` 字段包含功能描述和使用场景（1-1024 字符）\n- [ ] 包含 `When to use this skill` 章节\n- [ ] 包含 `Instructions` 章节\n- [ ] 包含 `Gotchas` 章节（环境特定注意事项）\n- [ ] 包含 `Examples` 章节\n- [ ] 包含 `Validation` 章节\n- [ ] 代码行数 ≤ 500 行\n- [ ] Token 数量 ≤ 5,000 token\n- [ ] 脚本使用非交互式设计\n- [ ] 脚本输出结构化数据\n- [ ] 脚本使用有意义的退出码\n\n## 与其他技术的对比\n\n| 特性 | Agent Skills | MCP (Model Context Protocol) |\n|------|--------------|-------------------------------|\n| 核心功能 | 教授 AI **如何**执行任务 | 帮助 AI **访问**资源 |\n| 实现方式 | 工作流、最佳实践 | API、数据库、外部工具 |\n| 更新难度 | 简单（仅修改指令文件） | 复杂（需要代码修改） |\n| 成本 | 低（指令文件） | 高（服务部署） |\n| 组合使用 | 可与 MCP 协同 | 可与 Skills 协同 |\n\n资料来源：[website/index.html:1-30](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[使用技能](#page-using-skills), [什么是Agent Skills](#page-what-is-agent-skill)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)\n
\n\n# 快速开始\n\n本页面帮助用户快速上手使用 awesome-agent-skills 项目，掌握查找、加载和使用 AI Agent 技能的基础流程。\n\n## 什么是 Agent Skill\n\nAgent Skill 是一个纯文本指令文件（称为 `SKILL.md`），用于教 AI 助手如何完成特定任务。可以将其理解为一张配方卡片：AI 阅读它，按照步骤执行，即可完成任务。技能仅在需要时加载，因此 AI 保持快速响应。\n\n资料来源：[website/index.html:1-50]()\n\n## 三分钟快速上手\n\n以下流程演示了从发现技能到实际使用的完整路径：\n\n```mermaid\ngraph TD\n A[发现技能] --> B[获取 GitHub URL]\n B --> C[加载到 AI]\n C --> D[用自然语言描述需求]\n D --> E[AI 自动读取技能说明]\n E --> F[执行任务]\n```\n\n资料来源：[website/src/components/sections/UsingSkills.tsx:1-50]()\n\n### 步骤一：发现技能\n\n在页面下方的目录中浏览所有技能。技能按类别组织（开发、数据、自动化、安全等），每个卡片直接链接到 GitHub 上的技能。\n\n### 步骤二：加载到 AI\n\n复制技能的 GitHub URL 并添加到 AI 代理中。根据平台不同，命令略有差异：\n\n| 平台 | 命令 |\n|-----|------|\n| Claude Code | `/skills add ` |\n| Claude.ai | 在对话中粘贴原始 SKILL.md URL |\n| Codex (OpenAI) | 参考官方文档 |\n\n资料来源：[README.ko.md:30-45]()\n\n### 步骤三：用自然语言提问\n\n只需告诉 AI 你想要什么——它会自动读取技能说明并开始工作。无需记忆命令，无需配置。\n\n资料来源：[website/index.html:80-100]()\n\n## 使用 npx skills CLI 工具\n\n对于特定技能，可以使用 `npx skills` 命令行工具快速发现、添加和管理技能。\n\n| 命令 | 功能 |\n|------|------|\n| `npx skills find [query]` | 搜索相关技能 |\n| `npx skills add ` | 添加技能（支持 GitHub 简写、完整 URL、本地路径） |\n| `npx skills list` | 列出已安装的技能 |\n| `npx skills check` | 检查更新 |\n| `npx skills update` | 升级所有技能 |\n| `npx skills remove [skill-name]` | 移除技能 |\n\n资料来源：[README.ko.md:20-30]()\n\n## 兼容的 AI 代理\n\n| 代理 | 文档链接 |\n|-----|---------|\n| Claude Code | [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) |\n| Claude.ai | [support.claude.com](https://support.claude.com/en/articles/12512180-using-skills-in-claude) |\n| Codex (OpenAI) | [developers.openai.com](https://developers.openai.com/codex) |\n\n资料来源：[README.ko.md:48-55]()\n\n## 手动加载技能\n\n如果不想使用 CLI 工具，也可以手动放置技能文件夹：\n\n```bash\n# 下载技能后放置到指定目录\ncp -r my-downloaded-skill ~/.agents/skills/my-downloaded-skill\n\n# 验证结构：技能必须有 SKILL.md 文件\nls ~/.agents/skills/my-skill/SKILL.md\n```\n\n支持的放置路径：\n\n- `~/.claude/skills/`\n- `~/.agents/skills/`\n- `~/.project/.agents/skills/`\n- `.github/skills/`（用于项目级技能）\n\n资料来源：[website/index.html:120-140]()\n\n## 创建你的第一个技能\n\n如果现有技能无法满足需求，可以自行创建：\n\n### 技能目录结构\n\n```\nskill-name/\n├── SKILL.md # 必需：技能说明文件\n└── scripts/ # 可选：可执行脚本目录\n └── *.py # 支持 Python、Shell 等\n```\n\n### SKILL.md 基本格式\n\n```yaml\n---\nname: skill-name\ndescription: 技能的简短描述，1-512 字符\n---\n\n## When to use this skill\n触发条件和使用场景\n\n## Instructions\n逐步执行步骤\n\n## Gotchas\n特殊注意事项\n\n## Examples\n输入输出示例\n```\n\n资料来源：[website/src/components/sections/CreatingSkills.tsx:1-40]()\n\n### 创建步骤\n\n1. **创建文件夹**：以技能名称命名（仅限小写字母、数字和连字符）\n2. **编写 SKILL.md**：在文件顶部添加 YAML frontmatter，包含 `name` 和 `description`\n3. **编写说明**：使用纯英文描述步骤和示例\n4. **添加脚本（如需要）**：在 `scripts/` 子目录放置可执行文件\n\n资料来源：[website/index.html:50-70]()\n\n## 技能质量标准\n\n为确保技能有效运行，建议遵循以下结构：\n\n| 章节 | 用途 |\n|-----|------|\n| `## When to use this skill` | 触发条件、范围和限制 |\n| `## Instructions` | 逐步执行过程，明确具体 |\n| `## Gotchas` | 环境特定事实，意外情况说明 |\n| `## Examples` | 具体的输入输出示例 |\n| `## Validation` | 如何验证输出正确性 |\n\n### 良好的指令示例\n\n```markdown\n## When to use this skill\n当用户需要从 PDF 文件中提取文本和表格时激活\n\n## Instructions\n1. 验证输入是有效的 PDF 文件\n2. 运行 scripts/extract.py 脚本\n3. 验证输出后再返回结果\n```\n\n### 应避免的模式\n\n- 模糊的描述，如\"做得好一点\"\n- 缺少具体的执行步骤\n- 没有说明错误处理方式\n\n资料来源：[website/src/components/sections/QualityStandards.tsx:1-60]()\n\n## 进阶功能\n\n### allowed-tools 字段\n\n在 frontmatter 中使用 `allowed-tools` 字段预批准工具运行，减少每次操作时的确认提示：\n\n```yaml\n---\nname: pdf-processing\nallowed-tools: Bash(uv:*) Read Write\n---\n```\n\n资料来源：[website/index.html:150-160]()\n\n### PEP 723 脚本\n\nPython 脚本可使用 PEP 723 内联依赖声明：\n\n```python\n#!/usr/bin/env -S uv run\n# /// script\n# requires-python = \">= 3.11\"\n# dependencies = [\"requests\", \"rich\"]\n# ///\nimport sys, json\n```\n\n资料来源：[website/index.html:170-185]()\n\n## 后续步骤\n\n- 探索完整的 [技能目录](#) 找到适合你的技能\n- 阅读 [SKILL.md 格式规范](https://agentskills.io/specification) 了解完整规格\n- 参考 [贡献指南](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md) 提交你自己的技能\n\n---\n\n\n\n## 使用技能\n\n### 相关页面\n\n相关主题：[快速开始](#page-quick-start), [支持的AI代理](#page-compatible-agents)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)\n
\n\n# 使用技能\n\n本文档详细介绍如何在各类 AI Agent 产品中使用 Agent Skills，包括发现、加载、激活的完整流程，以及不同平台的集成方式。\n\n## 什么是 Agent Skills\n\nAgent Skills 是一种可移植的知识包，由包含 `SKILL.md` 文件的文件夹组成。该文件融合了元数据和指令，使 AI Agent 能够按需发现和加载特定技能。Agent Skills 最初由 Anthropic 开发，现已作为开放标准被 30+ Agent 产品采用，包括 Claude、Codex、Cursor、Copilot、Gemini CLI 等。\n\n资料来源：[website/index.html:1-20]()\n\n### 核心特性\n\n| 特性 | 说明 |\n|------|------|\n| 按需加载 | 仅在需要时加载技能，保持 Agent 响应速度 |\n| 零基础设施 | 无需复杂配置，共享在 GitHub 上即可使用 |\n| 平台无关 | 兼容所有支持 Skills 标准的 Agent 产品 |\n| 版本控制 | 作为 Git 仓库管理，便于追踪变更 |\n\n资料来源：[website/index.html:120-140]()\n\n## 工作原理\n\n### 渐进式披露机制\n\nAgent Skills 采用渐进式披露（Progressive Disclosure）机制，分三个阶段工作：\n\n```mermaid\ngraph TD\n A[启动 Agent] --> B[发现 Discovery]\n B --> C[激活 Activation]\n C --> D[加载 Loading]\n D --> E[执行任务]\n \n B --> B1[扫描 name + description
~50-100 tokens/技能]\n C --> C1[匹配用户任务]\n D --> D1[读取完整 SKILL.md]\n \n style B fill:#e1f5fe\n style C fill:#f3e5f5\n style D fill:#fff3e0\n```\n\n### 三个阶段详解\n\n| 阶段 | 触发时机 | 加载内容 | 位置 |\n|------|----------|----------|------|\n| **发现** | Agent 启动时 | 仅 `name` 和 `description` | `~/.claude/skills/` |\n| **激活** | 任务匹配描述时 | 完整 `SKILL.md` 内容 | 上下文注入 |\n| **加载** | 执行相关操作 | `scripts/` 目录中的脚本 | 按需执行 |\n\n资料来源：[website/index.html:280-310]()\n\n## 使用方式\n\n### 方式一：通过 CLI 添加\n\n使用官方命令行工具添加技能，这是最便捷的方式：\n\n```bash\nnpx skills add anthropics/skills/docx\n```\n\n该命令支持以下几种引用格式：\n\n| 格式类型 | 示例 |\n|----------|------|\n| GitHub 简写 | `anthropics/skills/docx` |\n| 完整 URL | `https://github.com/anthropics/skills/docx` |\n| 本地相对路径 | `./my-skills/pdf-processing` |\n\n资料来源：[website/src/components/sections/UsingSkills.tsx:1-40]()\n\n### 方式二：手动放置\n\n将技能文件夹直接放置到指定目录，Agent 会自动扫描：\n\n| 平台 | 路径 |\n|------|------|\n| Claude Code | `.claude/skills/` 或 `.github/skills/` |\n| Claude.ai | 粘贴原始 SKILL.md 的 URL |\n| 通用 | `~/.agents/skills/` 或 `~/.claude/skills/` |\n\n放置结构示例：\n\n```\n.github/skills/skill-name/\n├── SKILL.md # 必需：技能定义文件\n└── scripts/ # 可选：可执行脚本目录\n ├── script1.py\n └── script2.sh\n```\n\n资料来源：[website/src/components/sections/UsingSkills.tsx:45-60]()\n\n### 方式三：通过 URL 直接引用\n\n在 Claude.ai 等平台，可以直接粘贴原始 `SKILL.md` 文件的 GitHub URL，Agent 会自动读取并应用技能说明。\n\n## 使用流程\n\n### 三步上手指南\n\n```mermaid\ngraph LR\n A[1. 找到技能] --> B[2. 加载到 AI]\n B --> C[3. 用自然语言提问]\n C --> D[✨ 任务完成]\n \n A --> A1[浏览目录
选择技能]\n B --> B1[复制 GitHub URL
添加到 Agent]\n C --> C1[用自然语言描述需求
Agent 自动读取技能]\n \n style A fill:#e3f2fd\n style B fill:#f3e5f5\n style C fill:#e8f5e9\n```\n\n### 步骤详解\n\n#### 步骤一：找到技能\n\n浏览 awesome-agent-skills 目录中的技能列表。技能按类别组织，包括开发、数据、自动化、安全等类别。每个技能卡片都直接链接到 GitHub 上的技能仓库。\n\n#### 步骤二：加载到 AI\n\n根据使用的平台选择合适的加载方式：\n\n- **Claude Code**: 使用 `/skills add ` 命令\n- **Claude.ai**: 直接在聊天窗口粘贴原始 SKILL.md 的 URL\n- **其他平台**: 参考各自平台的技能管理文档\n\n#### 步骤三：用自然语言提问\n\n完成上述步骤后，只需用自然语言描述你的需求。Agent 会自动读取技能说明并执行相应操作。无需记忆任何命令或进行额外配置。\n\n资料来源：[website/src/components/sections/UsingSkills.tsx:10-35]()\n\n## 技能结构\n\n### 目录结构规范\n\n```\nskill-name/\n├── SKILL.md # 必需：包含 YAML frontmatter + 指令\n├── scripts/ # 可选：可执行脚本目录\n│ ├── script1.py # Python 脚本（推荐 PEP 723 格式）\n│ └── script2.sh # Shell 脚本\n└── README.md # 可选：人类可读的说明文档\n```\n\n### SKILL.md 文件格式\n\n每个技能的核心是 `SKILL.md` 文件，采用 YAML frontmatter + Markdown 正文的结构：\n\n```yaml\n---\nname: pdf-processing\ndescription: >\n 从 PDF 文件提取文本和表格，填充 PDF 表单，\n 合并多个 PDF。当处理 PDF 文档、表单或涉及\n 文档提取、表单填充时激活。\nlicense: Apache-2.0\ncompatibility: Requires Python 3.11+ and uv\nmetadata:\n author: example-org\n version: \"1.0\"\nallowed-tools: Bash(uv:*) Read Write\n---\n\n## 何时使用此技能\n\n激活条件、范围和限制说明。\n\n## 指令\n\n逐步操作步骤，保持清晰明确。\n\n## 注意事项\n\n环境特定的事实，不符合预期的情况。\n\n## 示例\n\n具体的输入 → 输出对。\n\n## 验证\n\n如何验证输出正确性。\n```\n\n### Frontmatter 字段说明\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| `name` | 是 | 小写字母 + 连字符，1-64 字符，与父目录名一致 |\n| `description` | 是 | 技能描述，说明何时使用此技能 |\n| `license` | 否 | 许可证类型 |\n| `compatibility` | 否 | 兼容性要求 |\n| `metadata` | 否 | 元数据（author、version 等） |\n| `allowed-tools` | 否 | 实验性字段，预批准可执行的工具列表 |\n\n资料来源：[website/index.html:30-80]()\n\n## 质量标准\n\n为确保技能的有效性，编写时需遵循以下质量标准：\n\n| 原则 | 说明 |\n|------|------|\n| **渐进式披露** | 先给概览，再逐步深入细节 |\n| **假设最小化** | 明确说明前提条件，减少歧义 |\n| **行动导向** | 使用祈使句和动词开头 |\n| **适度规定** | 仅在必要时严格规定，其他情况给予自由度 |\n| **脚本设计** | 非交互式、结构化输出、有意义的退出码 |\n| **验证机制** | 内置验证循环，Agent 自我检查 |\n\n### 好的模式 vs 不好的模式\n\n```mermaid\ngraph LR\n subgraph 好的模式\n A1[明确的步骤编号] --> A2[可验证的输出]\n A2 --> A3[具体示例]\n end\n \n subgraph 不好的模式\n B1[模糊的描述] --> B2[无验证机制]\n B2 --> B3[缺少上下文]\n end\n```\n\n资料来源：[website/src/components/sections/QualityStandards.tsx:1-50]()\n\n## 常见问题\n\n### Q: 什么是 Agent Skill？\n\nAgent Skill 是一个纯文本指令文件（称为 `SKILL.md`），用于教 AI 助手如何完成特定任务。可以将其理解为食谱卡片：AI 读取它，按照步骤执行，然后完成任务。技能仅在需要时加载，因此 AI 保持快速响应。\n\n### Q: 我不是开发者，能使用技能吗？\n\n可以。技能是纯英文指令文件，不是代码。你只需要一个 AI 助手（如 Claude.ai，免费版即可），不需要终端或 GitHub 账户。只需复制技能的 GitHub URL 并粘贴到 AI 聊天中即可。\n\n### Q: 技能免费吗？\n\n技能本身是免费的。但使用某些技能可能需要付费使用底层 API（如使用特定模型）。技能文件本身可以免费复制、使用和修改。\n\n### Q: 如何创建自己的技能？\n\n只需创建一个以技能命名的文件夹，在其中放置 `SKILL.md` 文件，顶部的 frontmatter 包含 `name` 和 `description`，然后在下面的 Markdown 中编写你的指令。将文件夹放在 `.claude/skills/` 或 `.github/skills/` 中即可。\n\n资料来源：[website/index.html:400-450]()\n\n## 获取帮助\n\n| 渠道 | 说明 |\n|------|------|\n| GitHub Issues | 报告 Bug 或请求新功能 |\n| GitHub Discussions | 提问和社区讨论 |\n| 官方网站 | [agent-skill.co](https://agent-skill.co) |\n| 邮件联系 | haileycheng@proton.me |\n\n资料来源：[website/src/components/Footer.tsx:1-30]()\n\n## 相关资源\n\n- [贡献指南](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md) - 学习如何为项目贡献技能\n- [创建技能](CreatingSkills.md) - 了解如何从头创建新技能\n- [质量标准](QualityStandards.md) - 掌握编写高质量技能的规范\n- [官方教程](https://modelcontextprotocol.io/docs/first-server) - MCP 入门教程\n\n---\n\n\n\n## 创建技能\n\n### 相关页面\n\n相关主题：[技能质量标准](#page-skill-quality-standards), [使用技能](#page-using-skills)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [CONTRIBUTING.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md)\n
\n\n# 创建技能\n\n## 概述\n\n「创建技能」是 awesome-agent-skills 项目中用于指导开发者构建可复用 AI Agent 技能的核心文档模块。该模块详细说明了如何从零开始创建一个符合规范要求的技能（Skill），包括目录结构、文件格式、编写规范以及最佳实践。\n\n技能是一种包含 `SKILL.md` 文件的文件夹，其中融合了元数据和指令，AI Agent 可以按需发现和加载。开发者只需创建一次，即可在支持 Agent Skills 标准的 30+ 个平台上使用，无需修改。\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## 技能目录结构\n\n每个技能本质上是一个独立的文件夹，必须遵循统一的目录结构规范。\n\n### 标准目录布局\n\n```\nskill-name/\n├── SKILL.md # 必需：技能定义文件\n└── scripts/ # 可选：可执行脚本目录\n ├── script1.py\n └── script2.sh\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 目录位置\n\n技能文件夹可放置于以下位置供 Agent 发现：\n\n| 位置 | 说明 |\n|------|------|\n| `.claude/skills/` | Claude Code 本地技能目录 |\n| `.github/skills/` | GitHub 集成技能目录 |\n| `~/.claude/skills/` | 用户级全局技能目录 |\n| `~/.agents/skills/` | 通用 Agent 技能目录 |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## SKILL.md 文件规范\n\n### 文件结构\n\n`SKILL.md` 采用 YAML 前置数据（Frontmatter）+ Markdown 正文的标准格式：\n\n```markdown\n---\nname: skill-name\ndescription: 技能描述（1-512字符）\nlicense: Apache-2.0 # 可选\ncompatibility: Python 3.11+ # 可选\nmetadata: # 可选\n author: example-org\n version: \"1.0\"\nallowed-tools: Bash(git:*) Read Write # 可选·实验性\n---\n\n## 技能正文内容\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 前置数据字段\n\n| 字段名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `name` | 字符串 | **是** | 小写字母、数字和连字符组成，1-64字符，不能有连续连字符，不能以连字符开头或结尾，必须与父目录名称一致 |\n| `description` | 字符串 | **是** | 技能用途描述，1-512字符，用于 Agent 在启动时识别是否需要加载该技能 |\n| `license` | 字符串 | 否 | 采用的开源许可证，如 Apache-2.0、MIT |\n| `compatibility` | 字符串 | 否 | 环境依赖说明，如 Python 3.11+、Node.js 18+ |\n| `metadata` | 对象 | 否 | 扩展元数据，包含 author、version 等信息 |\n| `allowed-tools` | 字符串 | 否 | 预批准的可执行工具列表（实验性功能） |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## 编写技能正文\n\n### 推荐正文结构\n\n为了确保 Agent 能清晰理解并执行任务，建议按以下结构组织 Markdown 正文：\n\n```markdown\n## When to use this skill\n触发条件、适用范围和限制说明。\n\n## Instructions\n逐步操作流程，请保持步骤明确且可执行。\n\n## Gotchas\n环境特定的事实，容易出错或违背预期的事项。\n\n## Examples\n具体的输入→输出示例对。\n\n## Validation\n如何验证输出结果是否正确。\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 编写原则\n\n1. **结构化步骤**：使用编号列表，将复杂任务分解为明确的子步骤\n2. **具体示例**：提供真实场景下的输入输出示例\n3. **错误处理**：说明常见错误及应对方法\n4. **验证方式**：定义输出质量的检验标准\n\n资料来源：[website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n\n---\n\n## 创建技能工作流\n\n### 四步创建流程\n\n```mermaid\ngraph TD\n A[1. 创建技能文件夹] --> B[2. 编写 SKILL.md]\n B --> C[3. 编写技能指令]\n C --> D[4. 添加脚本可选]\n D --> E[技能创建完成]\n```\n\n资料来源：[website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)\n\n### 步骤详解\n\n#### 第一步：创建技能文件夹\n\n在 `.claude/skills/` 或 `.github/skills/` 目录下创建以技能名称命名的文件夹。\n\n```bash\nmkdir -p .github/skills/pdf-processing\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n#### 第二步：编写 SKILL.md\n\n在文件夹内创建 `SKILL.md` 文件，添加 YAML 前置数据：\n\n```yaml\n---\nname: pdf-processing\ndescription: 从 PDF 文件中提取文本和表格，填充 PDF 表单，合并多个 PDF。\n---\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n#### 第三步：编写技能指令\n\n在 YAML 前置数据下方添加 Markdown 正文，用简洁的英文描述操作步骤：\n\n```markdown\n## When to use this skill\n\n当用户需要提取文本、填充表单或合并 PDF 时激活此技能。\n\n## Instructions\n\n1. 验证输入是有效的 PDF 文件\n2. 从 scripts/ 目录运行相应的脚本\n3. 返回结果前验证输出\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n#### 第四步：添加脚本（可选）\n\n在 `scripts/` 子目录中放置可执行文件。推荐使用 PEP 723 规范的 Python 脚本，包含内联依赖声明：\n\n```python\n#!/usr/bin/env -S uv run\n# /// script\n# requires-python = \">= 3.11\"\n# dependencies = [\"requests\", \"rich\"]\n# ///\nimport sys, json\n\n# 使用结构化输出\n# 将错误写入 stderr\nprint(json.dumps({\"result\": \"ok\"}))\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## 技能加载机制\n\n### 渐进式加载设计\n\nAgent Skills 采用「渐进式披露」（Progressive Disclosure）设计，在不同阶段加载不同信息：\n\n```mermaid\ngraph LR\n A[启动阶段] --> B[仅加载 name + description]\n B --> C[任务匹配时]\n C --> D[加载完整 SKILL.md]\n D --> E[必要时加载 scripts/]\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n### 加载阶段说明\n\n| 阶段 | 加载内容 | Token 消耗 |\n|------|----------|------------|\n| 启动扫描 | `name` + `description` | ~50-100 字符/技能 |\n| 任务激活 | 完整 `SKILL.md` 正文 | 完整内容 |\n| 脚本执行 | `scripts/` 目录文件 | 按需加载 |\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## 技能质量标准\n\n### 优质技能特征\n\n| 维度 | 要求 |\n|------|------|\n| 名称规范 | 小写字母+连字符，与目录名一致 |\n| 描述准确 | 清晰说明触发场景和功能范围 |\n| 指令明确 | 步骤具体、无歧义、可执行 |\n| 示例完整 | 提供真实输入输出示例 |\n| 错误处理 | 说明常见错误及处理方式 |\n\n资料来源：[website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n\n### 完整示例\n\n以下是一个符合所有规范的完整技能示例：\n\n```yaml\n---\nname: pdf-processing\ndescription: >\n 从 PDF 文件中提取文本和表格，填充 PDF 表单，\n 合并多个 PDF。适用于处理 PDF 文档、表单或\n 涉及文档提取的场景。\nlicense: Apache-2.0\ncompatibility: Requires Python 3.11+ and uv\nmetadata:\n author: example-org\n version: \"1.0\"\nallowed-tools: Bash(uv:*) Read Write\n---\n\n## When to use this skill\n\n当用户需要提取文本、填充表单或合并 PDF 时激活此技能。\n\n## Instructions\n\n1. 验证输入是有效的 PDF\n2. 根据任务类型运行相应脚本\n3. 验证输出后返回结果\n\n## Gotchas\n\n- 扫描版 PDF 需要 OCR（使用 ocr.py 而非 extract.py）\n- 加密 PDF 需要先解密\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## 与现有系统集成\n\n### 安装技能到本地\n\n使用 `npx skills` CLI 工具可快速添加技能：\n\n```bash\n# 通过 GitHub 添加\nnpx skills add anthropics/skills/docx\n\n# 手动复制到本地\ncp -r my-downloaded-skill ~/.claude/skills/my-skill\n```\n\n资料来源：[website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n\n### 验证技能安装\n\n```bash\nls ~/.claude/skills/my-skill/SKILL.md\n```\n\n资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n\n---\n\n## 参与贡献\n\n如果您希望将技能提交到 awesome-agent-skills 仓库，请参考贡献指南：\n\n- 查看 [CONTRIBUTING.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md) 了解提交流程\n- 确保技能符合质量标准\n- 通过 GitHub Pull Request 提交\n\n资料来源：[website/src/components/sections/Contributing.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Contributing.tsx)\n\n---\n\n## 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| 官方规范 | [agentskills.io/specification](https://agentskills.io/specification) |\n| skills CLI | [vercel-labs/skills](https://github.com/vercel-labs/skills) |\n| Claude 技能文档 | [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) |\n\n---\n\n\n\n## 官方技能目录分类\n\n### 相关页面\n\n相关主题：[什么是Agent Skills](#page-what-is-agent-skill), [快速开始](#page-quick-start)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.md)\n- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)\n- [website/src/components/sections/SkillDirectory.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/SkillDirectory.tsx)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)\n
\n\n# 官方技能目录分类\n\n## 概述\n\n官方技能目录（Skill Directory）是 awesome-agent-skills 项目的核心功能模块，提供了 AI Agent Skills 的可发现性浏览界面。该目录将社区贡献的各类技能按照功能领域进行分类组织，使用户能够快速定位所需的技能集合。技能目录支持动态筛选、搜索过滤以及直接的 GitHub URL 链接访问，每个技能卡片都直接关联到 GitHub 仓库上的具体技能实现。资料来源：[website/index.html:1-50]()\n\n## 目录架构设计\n\n### 渐进式加载机制\n\n技能目录采用「渐进式披露」（Progressive Disclosure）设计模式，在不同阶段加载不同层级的技能信息，以优化性能并减少不必要的资源消耗。\n\n```mermaid\ngraph TD\n A[启动阶段] --> B[轻量级扫描]\n B --> C[仅加载 name 和 description]\n C --> D[约 50-100 tokens/技能]\n E[任务匹配时] --> F[完整加载]\n F --> G[加载完整 SKILL.md]\n G --> H[读取指令、示例和脚本]\n```\n\n技能目录的搜索路径包括以下标准位置：\n\n| 路径位置 | 说明 |\n|---------|------|\n| `~/.claude/skills/` | Claude Code 默认技能目录 |\n| `~/.agents/skills/` | 通用代理技能存储 |\n| `.github/skills/` | 项目级技能目录 |\n| `.agents/skills/` | 本地项目技能目录 |\n\n资料来源：[website/index.html:120-135]()\n\n### 目录扫描与发现机制\n\n目录组件通过静态分析技能元数据实现自动发现功能。在项目启动时，系统仅提取技能的 `name` 和 `description` 字段，这些信息用于构建技能索引和匹配算法。当用户任务与某个技能的描述相匹配时，才会触发完整 `SKILL.md` 文件的加载流程。\n\n## 分类体系结构\n\n### 主分类维度\n\n技能目录按照功能领域划分为多个主分类维度，每个维度对应特定的技能集合：\n\n| 分类名称 | 涵盖范围 | 典型技能示例 |\n|---------|---------|-------------|\n| **开发** | 代码编写、调试、重构相关技能 | 代码审查、测试生成、文档编写 |\n| **数据** | 数据处理、分析、转换相关技能 | PDF 处理、数据分析、表格提取 |\n| **自动化** | 工作流自动化、脚本执行相关技能 | CI/CD 集成、部署自动化 |\n| **安全** | 安全扫描、合规检查相关技能 | 漏洞扫描、依赖检查 |\n\n资料来源：[website/index.html:80-95]()\n\n### 技能卡片组件\n\n目录中的每个技能以卡片形式展示，卡片包含以下关键信息：\n\n```typescript\ninterface SkillCard {\n name: string; // 技能名称（小写字母+连字符）\n description: string; // 技能描述（触发条件和使用场景）\n category: string; // 所属分类\n githubUrl: string; // GitHub 仓库链接\n tags?: string[]; // 可选标签\n}\n```\n\n技能卡片的设计强调可访问性，每个卡片都包含直接指向 GitHub 仓库的链接，支持用户快速复制技能 URL 并加载到 AI 代理中。资料来源：[website/src/components/sections/SkillDirectory.tsx:1-30]()\n\n## 技能目录交互流程\n\n### 用户发现与加载流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Directory as 技能目录\n participant Agent as AI 代理\n participant GitHub as GitHub\n\n User->>Directory: 浏览技能目录\n Directory->>User: 显示分类技能列表\n User->>Directory: 选择目标技能\n Directory->>User: 返回 GitHub URL\n User->>Agent: 粘贴 GitHub URL\n Agent->>GitHub: 请求 SKILL.md 内容\n GitHub->>Agent: 返回技能定义\n Agent->>User: 执行任务\n```\n\n### 多平台加载方式\n\n根据不同的 AI 代理平台，技能加载方式存在差异：\n\n| 平台 | 加载命令 | 说明 |\n|-----|---------|------|\n| Claude Code | `/skills add ` | 使用斜杠命令添加技能 |\n| Claude.ai | 粘贴原始 SKILL.md URL | 直接在聊天窗口粘贴 |\n| Cursor | 放入 `.github/skills/` | IDE 自动识别 |\n| Claude.ai 免费版 | 支持完整功能 | 无需付费 |\n\n资料来源：[website/src/components/sections/UsingSkills.tsx:1-40]()\n\n## 技能筛选与搜索功能\n\n### 动态过滤机制\n\n目录提供实时搜索和分类筛选功能，用户可以通过关键词快速定位目标技能。搜索算法基于技能名称和描述进行匹配，支持模糊搜索和精确匹配两种模式。\n\n技能目录还实现了分类内搜索功能，允许用户在同一分类下进行二次筛选，进一步缩小搜索范围。\n\n### 筛选状态管理\n\n```mermaid\nstateDiagram-v2\n [*] --> 全部技能\n 全部技能 --> 按分类筛选\n 按分类筛选 --> 搜索关键词\n 搜索关键词 --> 精确结果\n 精确结果 --> 重置筛选\n 重置筛选 --> 全部技能\n```\n\n当用户输入搜索关键词时，系统会同时匹配技能名称、描述和标签字段，返回相关性排序的结果列表。资料来源：[website/index.html:95-110]()\n\n## 目录展示组件\n\n### 响应式网格布局\n\n技能目录采用响应式网格布局，根据视口宽度动态调整每行显示的技能卡片数量：\n\n| 视口宽度 | 每行卡片数 | 布局模式 |\n|---------|----------|---------|\n| ≥1280px | 4 列 | 四列网格 |\n| ≥768px | 2-3 列 | 双列/三列网格 |\n| <768px | 1 列 | 单列堆叠 |\n\n### 分类标签系统\n\n每个技能可附加多个分类标签，标签系统支持以下功能：\n\n- **多分类归属**：单个技能可属于多个分类\n- **标签过滤**：支持按标签快速筛选\n- **视觉标识**：不同分类使用不同颜色区分\n\n资料来源：[website/src/components/sections/SkillDirectory.tsx:40-60]()\n\n## 技能目录数据源\n\n### GitHub 仓库集成\n\n技能目录通过集成 GitHub API 获取技能列表和元数据。每个技能对应一个独立的 GitHub 仓库或仓库内的子目录，目录结构要求包含 `SKILL.md` 文件作为技能定义入口。\n\n```\nrepository/\n├── SKILL.md # 必需：技能定义文件\n├── scripts/ # 可选：可执行脚本目录\n│ ├── extract.py\n│ └── transform.sh\n├── assets/ # 可选：资源文件目录\n└── README.md # 可选：技能说明文档\n```\n\n### 元数据提取\n\n目录从 GitHub 仓库的 `SKILL.md` 文件中提取以下元数据：\n\n- `name`：技能唯一标识符\n- `description`：技能功能描述\n- `license`：开源许可证类型\n- `compatibility`：兼容性要求\n- `allowed-tools`：预批准工具列表\n- `metadata`：作者、版本等信息\n\n资料来源：[website/index.html:150-180]()\n\n## 质量标准与分类规范\n\n### 技能描述质量要求\n\n技能目录对收录的技能有明确的质量标准要求：\n\n| 标准项 | 要求 | 说明 |\n|-------|------|------|\n| 描述完整性 | 必须包含触发条件 | 说明何时应激活该技能 |\n| 语言风格 | 使用祈使语气 | \"Use this skill when...\" |\n| 关键词覆盖 | 包含用户可能输入的关键词 | 提高匹配准确度 |\n| 示例提供 | 建议包含输入输出示例 | 帮助理解技能用途 |\n\n### 优秀与不良示例对比\n\n资料来源：[website/src/components/sections/QualityStandards.tsx:1-30]()\n\n**优秀描述示例：**\n```\nExtracts text and tables from PDF files. Use when working with \nPDFs, forms, or document extraction.\n```\n\n**不良描述示例：**\n```\nHelps with PDFs.\n```\n\n## 兼容性与扩展性\n\n### 多代理平台兼容\n\n技能目录设计为跨平台兼容，确保同一技能可在多个 AI 代理产品中使用：\n\n```mermaid\ngraph LR\n A[SKILL.md 标准格式] --> B[Claude Code]\n A --> C[Claude.ai]\n A --> D[OpenAI Codex]\n A --> E[GitHub Copilot]\n A --> F[Cursor]\n A --> G[Gemini CLI]\n \n B --> H[30+ 代理产品]\n C --> H\n D --> H\n E --> H\n F --> H\n G --> H\n```\n\n### npx skills CLI 工具支持\n\n技能目录与 `npx skills` 命令行工具深度集成，提供便捷的技能发现和管理能力：\n\n```bash\nnpx skills find [query] # 搜索相关技能\nnpx skills add # 添加技能（支持 GitHub 简写）\nnpx skills list # 列出已安装技能\nnpx skills check # 检查更新\nnpx skills update # 更新所有技能\nnpx skills remove [skill-name] # 移除指定技能\n```\n\n资料来源：[README.ko.md:60-75]()\n\n## 总结\n\n官方技能目录分类模块是 awesome-agent-skills 项目的核心功能，通过清晰的分类体系、渐进式加载机制和跨平台兼容设计，为用户提供了高效的技能发现和管理体验。目录采用模块化架构，支持多种 AI 代理平台的技能共享，是构建可复用 AI 代理能力的标准化解决方案。\n\n---\n\n\n\n## 网站架构\n\n### 相关页面\n\n相关主题：[项目结构](#page-project-structure)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/src/app/layout.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/app/layout.tsx)\n- [website/src/app/page.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/app/page.tsx)\n- [website/src/components/LayoutShell.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/LayoutShell.tsx)\n- [website/src/components/Navbar.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Navbar.tsx)\n- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)\n- [website/src/components/sections/WhatIsIt.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/WhatIsIt.tsx)\n- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)\n- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)\n\n
\n\n# 网站架构\n\n## 概述\n\nawesome-agent-skills 网站是一个基于 Next.js 构建的现代化文档展示平台，用于展示 AI Agent 技能（Agent Skills）的目录和教程。该网站采用 React + TypeScript + Tailwind CSS 技术栈构建，具有响应式设计，支持明暗主题切换，并提供多语言内容展示能力。\n\n## 技术栈\n\n| 技术 | 用途 | 版本要求 |\n|------|------|----------|\n| Next.js | React 框架与 SSR/SSG 支持 | - |\n| React 18 | UI 组件库 | 18.x |\n| TypeScript | 类型安全开发 | 5.x |\n| Tailwind CSS | 原子化 CSS 样式框架 | 3.x |\n| Lucide React | 图标库 | - |\n\n## 整体架构\n\n网站采用标准的 Next.js App Router 架构模式，组件化设计贯穿整个项目。\n\n```mermaid\ngraph TB\n subgraph \"App Router Layer\"\n A[\"app/layout.tsx\"] --> B[\"app/page.tsx\"]\n end\n \n subgraph \"Layout Shell\"\n C[\"LayoutShell.tsx\"] --> D[\"Navbar.tsx\"]\n C --> E[\"Footer.tsx\"]\n end\n \n subgraph \"Page Sections\"\n F[\"WhatIsIt.tsx\"]\n G[\"QualityStandards.tsx\"]\n H[\"UsingSkills.tsx\"]\n I[\"CreatingSkills.tsx\"]\n J[\"FindingSkills.tsx\"]\n K[\"Tutorials.tsx\"]\n end\n \n B --> C\n C --> F\n C --> G\n C --> H\n C --> I\n C --> J\n C --> K\n```\n\n## 核心组件结构\n\n### 布局层组件\n\n#### LayoutShell.tsx\n\n布局容器组件，负责整体页面结构的组织。该组件是页面内容与导航栏、页脚之间的桥梁，协调各部分组件的渲染顺序和布局关系。\n\n#### Navbar.tsx\n\n顶部导航栏组件，提供网站主导航功能，包含 Logo、页面链接和外部社交媒体入口。导航栏组件实现了响应式设计，支持移动端菜单折叠。\n\n#### Footer.tsx\n\n页脚组件，包含以下关键信息：\n\n- 网站版权声明（2026年）\n- 出版方信息（GitHub）\n- 主要链接入口：\n - agent-skill.co 官方网站\n - GitHub 仓库地址\n - X (Twitter) 社交链接\n - 电子邮件联系方式\n\n```typescript\n\n agent-skill.co\n\n\n GitHub\n\n\n Twitter\n\n\n Mail\n\n```\n\n资料来源：[website/src/components/Footer.tsx]()\n\n### 页面区块组件 (Sections)\n\n网站内容由多个独立的 Section 组件构成，每个组件负责一个特定的展示区域：\n\n| 组件 | 功能描述 |\n|------|----------|\n| WhatIsIt.tsx | 介绍 Agent Skills 的核心概念和价值主张 |\n| QualityStandards.tsx | 展示技能的质量标准和最佳实践示例 |\n| UsingSkills.tsx | 指导用户如何使用现有技能 |\n| CreatingSkills.tsx | 提供创建新技能的指南 |\n| FindingSkills.tsx | 介绍如何发现和获取技能资源 |\n| Tutorials.tsx | 展示教程和高级使用案例 |\n\n#### WhatIsIt.tsx 组件结构\n\n该组件通过 Icon + Title + Description 的标准化卡片布局展示信息：\n\n```typescript\n{features.map(({ Icon, title, desc }) => (\n
\n
\n \n
\n
\n

{title}

\n

{desc}

\n
\n
\n))}\n```\n\n资料来源：[website/src/components/sections/WhatIsIt.tsx]()\n\n#### QualityStandards.tsx 组件结构\n\n该组件展示了技能的优劣对比示例，采用双栏布局：\n\n```mermaid\ngraph LR\n A[QualityStandards] --> B[质量标准卡片列表]\n A --> C[Good Example 面板]\n A --> D[Bad Example 面板]\n \n C --> E[\"✅ 良好模式示例\"]\n D --> F[\"❌ 错误模式示例\"]\n```\n\n组件使用 `CheckCircle2` 和 `XCircle` 图标区分良好和不良示例，并通过透明度设置（opacity-70）视觉降级错误示例的显示效果。\n\n资料来源：[website/src/components/sections/QualityStandards.tsx]()\n\n#### UsingSkills.tsx 组件结构\n\n该组件专注于展示技能加载和使用的操作流程，包含以下功能模块：\n\n1. **三步骤说明卡片** - 展示使用技能的标准流程\n2. **代码面板** - 提供 CLI 命令示例和手动配置路径\n3. **复制功能** - 支持一键复制代码片段\n\n```typescript\n
\n  npx skills add anthropics/skills/docx\n
\n```\n\n支持多种添加方式：GitHub 简写格式、完整 URL、本地相对路径。\n\n资料来源：[website/src/components/sections/UsingSkills.tsx]()\n\n## 主题系统\n\n网站实现了完整的明暗主题切换功能，采用 CSS 自定义属性（CSS Variables）实现：\n\n```css\n:root{\n --bg:#000;\n --bg1:rgba(255,255,255,0.03);\n --bg2:rgba(255,255,255,0.05);\n --bg3:rgba(255,255,255,0.08);\n --border:rgba(255,255,255,0.08);\n --border2:rgba(255,255,255,0.12);\n --text:rgba(255,255,255,0.95);\n}\n```\n\nTailwind CSS 暗黑模式类名映射：\n\n| 亮色类 | 暗黑模式类 | 用途 |\n|--------|------------|------|\n| text-neutral-900 | dark:text-white | 主文本颜色 |\n| text-neutral-500 | dark:text-neutral-400 | 次要文本 |\n| bg-white | dark:bg-neutral-900 | 卡片背景 |\n| border-neutral-200 | dark:border-neutral-800 | 边框颜色 |\n\n## 页面路由结构\n\n```\nwebsite/src/app/\n├── layout.tsx # 根布局，包含全局样式和主题配置\n└── page.tsx # 首页主路由\n```\n\nNext.js App Router 模式下，`layout.tsx` 定义的布局会被所有页面共享，确保导航栏和页脚在整个网站中保持一致。\n\n## 组件通信模式\n\n组件间主要通过以下方式进行数据和状态传递：\n\n```mermaid\ngraph TD\n A[layout.tsx] -->|props| B[LayoutShell]\n B -->|props| C[Navbar]\n B -->|props| D[Footer]\n B -->|children| E[Page Sections]\n \n F[Feature Data] -->|map| E\n G[i18n] -->|translations| E\n```\n\n## 响应式设计策略\n\n网站采用移动优先的响应式设计原则，关键断点如下：\n\n| 断点前缀 | 屏幕宽度 | 典型设备 |\n|----------|----------|----------|\n| 无前缀 | < 768px | 手机 |\n| md: | ≥ 768px | 平板 |\n| lg: | ≥ 1024px | 桌面 |\n\n常用响应式布局类：\n\n- `md:grid-cols-2` - 中等屏幕双栏布局\n- `gap-4` → `md:gap-6` - 间距随屏幕放大\n- `px-4` → `md:px-8` - 水平内边距递增\n\n## 开发规范\n\n### 组件文件组织\n\n```\nwebsite/src/components/\n├── LayoutShell.tsx # 布局容器\n├── Navbar.tsx # 导航栏\n├── Footer.tsx # 页脚\n└── sections/ # 页面区块\n ├── WhatIsIt.tsx\n ├── QualityStandards.tsx\n ├── UsingSkills.tsx\n ├── CreatingSkills.tsx\n ├── FindingSkills.tsx\n └── Tutorials.tsx\n```\n\n### 样式编写规范\n\n1. **优先使用 Tailwind 原子类** - 减少自定义 CSS 文件\n2. **使用 CSS 变量管理主题色** - 便于暗黑模式切换\n3. **组件内样式隔离** - 避免样式冲突\n4. **统一使用 neutral 色系** - 配合暗色主题\n\n### 国际化考虑\n\n网站内容通过翻译对象结构组织，便于扩展多语言支持。现有包含韩语版本（README.ko.md），说明项目有多语言文档需求。\n\n## 总结\n\nawesome-agent-skills 网站采用了现代化的前端架构设计，通过 Next.js App Router 实现服务端渲染和客户端导航的平衡。组件化的设计使得各功能模块高度解耦，便于维护和扩展。明暗主题支持、响应式布局和多语言文档能力共同构成了这个文档网站的技术基础。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：heilcheng/awesome-agent-skills\n\n摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `awesome-agent-skills` 与安装入口 `skills` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx skills`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | repo=awesome-agent-skills; install=skills\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | host_targets=claude\n\n## 3. 能力坑 · 能力判断依赖假设\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:1124920990 | https://github.com/heilcheng/awesome-agent-skills | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 来源证据：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dc99192b4a9b4b8089f4f6696f332a7d | https://github.com/heilcheng/awesome-agent-skills/issues/218 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 8. 安全/权限坑 · 来源证据：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0703404b82014fe3baddd3eaab1100bd | https://github.com/heilcheng/awesome-agent-skills/issues/226 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 9. 维护坑 · 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:1124920990 | https://github.com/heilcheng/awesome-agent-skills | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | 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项目：heilcheng/awesome-agent-skills\n\n摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `awesome-agent-skills` 与安装入口 `skills` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx skills`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | repo=awesome-agent-skills; install=skills\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | host_targets=claude\n\n## 3. 能力坑 · 能力判断依赖假设\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:1124920990 | https://github.com/heilcheng/awesome-agent-skills | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 来源证据：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dc99192b4a9b4b8089f4f6696f332a7d | https://github.com/heilcheng/awesome-agent-skills/issues/218 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 8. 安全/权限坑 · 来源证据：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0703404b82014fe3baddd3eaab1100bd | https://github.com/heilcheng/awesome-agent-skills/issues/226 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 9. 维护坑 · 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:1124920990 | https://github.com/heilcheng/awesome-agent-skills | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# awesome-agent-skills - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 awesome-agent-skills 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Tutorials, Guides and Agent Skills Directories 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-intro：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-project-structure：项目结构。围绕“项目结构”模拟一次用户任务，不展示安装或运行结果。\n3. page-what-is-agent-skill：什么是Agent Skills。围绕“什么是Agent Skills”模拟一次用户任务，不展示安装或运行结果。\n4. page-compatible-agents：支持的AI代理。围绕“支持的AI代理”模拟一次用户任务，不展示安装或运行结果。\n5. page-quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-intro\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-project-structure\n输入：用户提供的“项目结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-what-is-agent-skill\n输入：用户提供的“什么是Agent Skills”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-compatible-agents\n输入：用户提供的“支持的AI代理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-intro：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-project-structure：Step 2 必须围绕“项目结构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-what-is-agent-skill：Step 3 必须围绕“什么是Agent Skills”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-compatible-agents：Step 4 必须围绕“支持的AI代理”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-quick-start：Step 5 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/heilcheng/awesome-agent-skills\n- https://github.com/heilcheng/awesome-agent-skills#readme\n- README.md\n- README.zh-CN.md\n- website/package.json\n- .gitignore\n- vercel.json\n- website/next.config.ts\n- website/tsconfig.json\n- website/src/components/sections/Hero.tsx\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 awesome-agent-skills 的核心服务。\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项目：heilcheng/awesome-agent-skills\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx skills\n```\n\n来源：https://github.com/heilcheng/awesome-agent-skills#readme\n\n## 来源\n\n- repo: https://github.com/heilcheng/awesome-agent-skills\n- docs: https://github.com/heilcheng/awesome-agent-skills#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_e7849b22030c458ea2d2e6c83b3bd1f6" }