1. 项目概述AGNXI - 一个为AI编码助手打造的技能目录如果你和我一样日常开发已经离不开像 Claude Code、Cursor 这类 AI 编码助手那你肯定也遇到过这样的场景面对一个特定的开发任务比如“如何用 Next.js 配置一个高效的图片优化管道”或者“怎么给项目快速集成一个完整的监控告警系统”你希望助手能给出最精准、最专业的指导而不是泛泛而谈。这时候一个专门为这些 AI 助手编写的、结构化的技能文件SKILL.md就显得至关重要。它就像给 AI 装上了一本专业的“工具手册”让它能调用特定领域的知识来帮你解决问题。AGNXI 这个项目就是这样一个“技能目录”的集散中心。它的核心目标很简单自动发现、索引并归类 GitHub 上所有公开的 SKILL.md 文件为开发者提供一个可以浏览、搜索、收藏这些技能的中央仓库。想象一下你不再需要去各个仓库里翻找或者凭记忆回想某个好用的技能打开 AGNXI就像打开一个为 AI 助手量身定做的“应用商店”你可以按类别前端、后端、DevOps、测试等浏览按热度GitHub 星标数排序找到心仪的技能后一键复制安装命令立刻就能在你的 Cursor 或 Windsurf 里用上。这个项目本身也是一个非常值得学习的现代全栈应用范例。它采用了 Next.js 16App Router、TypeScript、Tailwind CSS、PostgreSQL 等一整套前沿且务实的技术栈。更特别的是它深度集成了 AI用于技能自动分类和后台任务调度用于定期同步技能库是一个典型的“AI 增强型”应用。接下来我会带你深入拆解这个项目的设计思路、技术实现细节并分享我在复现和探索过程中的一些实操心得与避坑指南。2. 核心架构与设计思路拆解2.1 为什么需要“技能目录”解决什么痛点在深入代码之前我们先聊聊“为什么”。AI 编码助手的“技能”本质上是一种上下文增强文件。当你把一个SKILL.md文件加载到助手的上下文中它就获得了执行某一类任务所需的特定知识、最佳实践和代码模板。痛点随之而来发现困难优质的技能散落在 GitHub 的各个角落没有统一的索引。开发者要么靠社区口口相传要么自己大海捞针。质量参差找到的技能文件其完整性、准确性和实用性无法保证。管理不便即使收藏了几个技能时间一长也容易忘记更别提在不同项目、不同助手间同步使用了。AGNXI 的定位就是解决这三个核心痛点。它通过 GitHub 的 Code Search API 主动爬取SKILL.md文件利用 AI 模型自动解析和分类并提供一个带搜索、筛选、排序功能的 Web 界面进行集中展示。这形成了一个从“生产”开发者编写技能到“消费”其他开发者使用技能的良性循环生态。2.2 技术栈选型背后的逻辑项目 README 里给出了清晰的技术栈表格每一个选择都很有讲究Next.js 16 (App Router): 这是当前构建全栈 React 应用的事实标准。App Router 提供了基于文件系统的路由、服务端组件、流式渲染等现代特性非常适合 AGNXI 这种兼具动态内容技能列表和静态页面营销页的应用。服务端组件能直接访问数据库简化了数据获取逻辑。Bun: 替代 Node.js 作为运行时和包管理器。Bun 的启动速度和执行效率更高内置了测试运行器、打包工具等能简化开发工具链。对于需要频繁执行脚本如数据库迁移、后台任务的项目来说提升明显。TypeScript: 对于涉及复杂数据模型技能元数据、分类和多个服务数据库、AI、缓存交互的项目TypeScript 提供的类型安全是必不可少的能极大减少运行时错误。Tailwind CSS 4: 快速构建一致、响应式 UI 的利器。AGNXI 的界面看起来干净专业Tailwind 功不可没它让开发者能专注于组件逻辑而非 CSS 细节。PostgreSQL Drizzle ORM: PostgreSQL 是功能强大的关系型数据库适合存储结构化的技能、分类、用户收藏等数据。Drizzle 是一个新兴的、类型安全的 ORM它的 API 设计更接近 SQL避免了传统 ORM 的“魔法”学习曲线平缓且性能可观与 TypeScript 搭配是天作之合。Clerk: 身份认证服务。自己实现一套完整、安全的用户系统注册、登录、管理费时费力且容易出错。Clerk 提供了开箱即用的解决方案集成简单专注于核心业务逻辑。Vercel AI SDK Google Gemini: AI SDK 统一了与不同 AI 模型交互的接口。选择 Google Gemini 可能是出于成本、速率限制或对特定任务如文本分类效果的考量。这里 AI 的核心作用是对爬取到的技能进行自动分类。Upstash Redis: 托管式 Redis 服务。用于缓存高频访问的数据如热门技能列表、分类信息减轻数据库压力提升响应速度。Inngest: 后台任务调度服务。技能库的同步、AI 分类、数据清理等耗时操作不适合在用户请求中同步执行。Inngest 允许你定义函数由特定事件如定时器、API 调用触发在后台异步运行保证了 Web 服务的响应性。实操心得技术选型的平衡这个技术栈体现了“现代、高效、托管服务优先”的思路。对于个人项目或初创项目优先使用像 Clerk、Upstash、Inngest 这样的托管服务能让你用最少的基础设施运维成本快速获得生产级的可靠功能。虽然会产生一些费用但相比自己搭建和维护在项目早期性价比极高。3. 核心模块解析与实操要点3.1 技能发现与索引引擎这是 AGNXI 最核心的“发动机”位于lib/features/skills/目录下。它的工作流程可以拆解为以下几个关键步骤步骤一基于 GitHub Code Search 的爬取它并非漫无目的地爬取整个 GitHub而是精准地搜索包含SKILL.md文件路径的仓库。通常会使用 GitHub 的 REST API 或 GraphQL API 的 code search 功能。查询语句可能类似于filename:SKILL.md path:/。为了提高效率和遵守 GitHub API 的速率限制爬取策略需要精心设计增量爬取记录上次爬取的时间戳或仓库的pushed_at时间只获取新增或更新的文件。分页处理妥善处理 API 返回的大量结果。错误处理与重试网络请求难免失败需要有健壮的重试机制和日志记录。步骤二技能元数据解析爬取到SKILL.md的原始内容后需要从中提取结构化信息。一个规范的SKILL.md通常在文件头部用 YAML Front Matter 定义元数据例如--- name: ‘Next.js Image Optimization Skill’ description: ‘Best practices for optimizing images in Next.js projects’ author: ‘someuser’ tools: [‘cursor’, ‘claude’] tags: [‘nextjs’, ‘performance’, ‘images’] ---解析器需要读取这部分内容并可能解析正文来补充描述。这里需要处理各种边缘情况比如格式不标准、缺少必要字段等。步骤三AI 驱动的自动分类这是项目的亮点。解析出的技能描述description和标签tags会被发送给 Gemini 这样的 LLM要求其根据预定义的分类体系如“前端开发”、“后端开发”、“测试”、“DevOps”、“文档”等为技能打上最合适的一个或多个分类标签。Prompt 设计是关键你需要给 AI 清晰的指令例如“你是一个技术分类专家。请根据以下技能描述从 [‘前端’, ‘后端’, ‘DevOps’, ‘测试’, ‘文档’, ‘工具’] 中选择最相关的1-3个分类。只返回分类名称用逗号分隔。”处理不确定性AI 的输出可能不稳定可能需要设置置信度阈值或者提供“未分类”作为兜底选项。步骤四数据存储将解析和分类后的结构化数据通过 Drizzle ORM 存入 PostgreSQL 数据库。主要的数据表可能包括skills: 存储技能的核心信息名称、描述、GitHub 链接、原始内容哈希等。categories: 存储分类。skill_categories: 技能与分类的多对多关联表。repositories: 存储仓库信息与技能关联。注意事项遵守平台规则与伦理API 速率限制严格遵守 GitHub API 的速率限制。对于未认证的请求限制非常严格使用GITHUB_TOKEN进行认证可以大幅提升限额。在代码中必须实现间隔throttling和退避backoff逻辑。仓库许可证只索引公开仓库并尊重仓库所采用的许可证如 MIT, GPL。AGNXI 本身是目录不存储技能的完整代码但索引其元数据和描述通常被认为是合理使用fair use不过最好在网站页脚添加相关声明。用户隐私如果技能文件包含个人信息应避免索引或进行脱敏处理。不过SKILL.md通常是技术文档这个问题不常见。3.2 后台任务与同步机制技能库需要保持更新。新技能被创建旧技能可能被修改或删除。同步任务通过 Inngest 来管理。Inngest 函数示例 在lib/inngest/目录下你可能会看到类似sync-skills.ts的函数。import { inngest } from /lib/inngest/client; export const syncSkills inngest.createFunction( { id: sync-skills, name: Sync Skills from GitHub }, { cron: 0 */6 * * * }, // 每6小时运行一次 async ({ step }) { // 1. 调用发现引擎获取新增/更新的技能 const newSkills await step.run(discover-skills, async () { return discoverNewSkills(); }); // 2. 对每个新技能运行AI分类 for (const skill of newSkills) { await step.run(classify-skill-${skill.id}, async () { return classifySkillWithAI(skill); }); } // 3. 清理已删除或失效的技能 await step.run(cleanup-skills, async () { return cleanupDeletedSkills(); }); return { message: Synced ${newSkills.length} skills }; } );Inngest 的优势在于它提供了强大的工作流控制step.run、重试机制和可视化仪表板让复杂的异步任务变得可管理。3.3 前端界面与用户体验前端部分app/,components/,features/负责将数据呈现给用户。技能列表页 (app/skills/page.tsx)这是核心页面。通常会使用服务端组件获取数据结合搜索参数来自 URL searchParams进行过滤和排序。排序逻辑按星标、按分叉数、按更新时间需要在数据库查询层面实现以确保效率。技能详情页 (app/[owner]/[skillName]/page.tsx)动态路由页面展示单个技能的详细信息、原始SKILL.md内容以及最重要的——一键复制安装命令。这个命令会根据技能兼容的工具Cursor, Claude等生成不同的格式例如对于 Cursor/skill install https://github.com/username/repo/blob/main/SKILL.md。收藏功能用户登录通过 Clerk后可以收藏技能。这涉及在数据库中添加一个user_favorites表并在 UI 上提供收藏/取消收藏的交互。管理后台 (app/admin/)提供手动触发同步、查看同步日志、管理分类等功能的界面通常需要设置管理员权限。4. 本地开发环境搭建与核心配置让我们动手从零开始让 AGNXI 在本地跑起来。这是理解项目依赖和配置的最佳方式。4.1 环境准备与依赖安装首先确保你的系统已经安装了 Bun。如果没有去 Bun 官网按照指引安装速度很快。# 1. 克隆仓库 git clone https://github.com/doanbactam/agent-skills-directory.git cd agent-skills-directory # 2. 安装项目依赖 # 使用 Bun 安装速度比 npm/yarn 快很多 bun install如果bun install过程中遇到问题通常是网络或某些原生模块编译的问题。可以尝试设置镜像或检查系统是否安装了必要的构建工具如 Python、C编译器等。4.2 关键环境变量配置项目根目录下有一个.env.example文件这是配置模板。复制它并创建你自己的.env.local文件Next.js 默认读取此文件。cp .env.example .env.local现在打开.env.local你需要逐一填写以下关键配置。这是项目能否运行起来的重中之重。数据库 (PostgreSQL):DATABASE_URLpostgresql://username:passwordlocalhost:5432/agnxi_db你需要本地安装并运行 PostgreSQL或者使用云服务如 Neon, Supabase提供的连接字符串。创建一个名为agnxi_db的数据库。身份认证 (Clerk):NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYpk_test_... CLERK_SECRET_KEYsk_test_...前往 Clerk 官网 注册并创建一个新应用。在 Dashboard 中找到 API Keys将NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY和CLERK_SECRET_KEY填入。GitHub API:GITHUB_TOKENghp_...在 GitHub 设置中生成一个 Personal Access Token (Classic)。需要勾选repo和read:packages等权限以便 Code Search API 能正常工作。没有这个 Token技能发现功能将无法使用或受到严格限制。AI 模型 (Google Gemini):GOOGLE_GENERATIVE_AI_API_KEYAIza...前往 Google AI Studio 创建一个 API 密钥。启用 Gemini API 服务。注意此服务可能非免费需留意用量。缓存 (Upstash Redis):UPSTASH_REDIS_REST_URLhttps://xxx.upstash.io UPSTASH_REDIS_REST_TOKENxxx在 Upstash 创建一个 Redis 数据库免费 tier 足够开发使用。将提供的 REST URL 和 Token 填入。后台任务 (Inngest):INNGEST_EVENT_KEYxxx INNGEST_SIGNING_KEYxxx在 Inngest 创建一个账户和项目。在项目设置中找到 Keys填入对应值。开发环境下你也可以暂时不配置但后台同步功能将无法工作。踩坑实录环境变量与类型安全我第一次配置时在.env.local里填好了所有值但运行时还是报错说缺少某个变量。原因是 Next.js 只在启动时读取.env.local而我在运行bun db:push这个脚本时脚本可能直接读取了process.env。解决方案确保你的脚本在package.json的scripts里也通过dotenv或类似方式加载了环境变量。另一个常见问题是变量名拼写错误务必与.env.example和代码中process.env.XXX的引用完全一致。4.3 数据库初始化与数据迁移配置好环境变量后就可以初始化数据库了。# 运行 Drizzle 的 push 命令根据你的 schema 文件在数据库中创建所有表 bun db:push # 可选如果项目提供了种子数据脚本可以运行它来预置一些分类数据 bun db:seed:categoriesbun db:push这个命令非常方便它直接同步你的 TypeScript schema 定义到数据库适合开发阶段。在生产环境更推荐使用生成迁移文件并执行的方式 (bun db:generate-bun db:migrate)以便对变更进行版本控制。4.4 启动开发服务器如果以上步骤都没报错那么恭喜你最艰难的部分已经过去了。bun dev打开浏览器访问http://localhost:3000。你应该能看到 AGNXI 的首页。由于数据库是空的技能列表可能为空。此时你可以尝试触发一次手动的技能同步如果管理后台已搭建或者直接通过前端界面提交一个已知的SKILL.md文件 URL 进行测试。5. 深入代码技能分类的 AI 集成实现让我们深入一个具体的技术点AI 如何给技能分类。这是项目智能化的核心。代码位置猜想逻辑很可能在lib/ai/classify-skill.ts或lib/actions/classify-skill.action.ts中。实现解析import { GoogleGenerativeAI } from google/generative-ai; // 初始化 Gemini const genAI new GoogleGenerativeAI(process.env.GOOGLE_GENERATIVE_AI_API_KEY!); const model genAI.getGenerativeModel({ model: gemini-1.5-flash }); // 使用轻量快速的模型 export async function classifySkill(skillDescription: string, skillTags: string[] []) { // 1. 构建Prompt。清晰的指令是获得稳定结果的关键。 const prompt 你是一个资深的软件开发技术分类专家。 请根据以下技能描述和标签从以下分类列表中选择最相关的1到3个分类。 请只返回分类名称用英文逗号分隔。如果都不相关返回“Uncategorized”。 【分类列表】 - Frontend Development - Backend Development - DevOps Infrastructure - Testing QA - Documentation Writing - Tooling Utilities - AI Machine Learning - Security - Mobile Development - Data Science Analytics 【技能描述】 ${skillDescription} 【技能标签】 ${skillTags.join(, )} 请直接给出分类结果 ; // 2. 调用AI模型 try { const result await model.generateContent(prompt); const response await result.response; const text response.text().trim(); // 3. 解析结果 const categories text.split(,).map(cat cat.trim()).filter(Boolean); // 4. 验证分类是否在预定义列表中 const validCategories [...predefinedCategoryList]; // 从数据库或配置中读取 const filteredCategories categories.filter(cat validCategories.includes(cat)); return filteredCategories.length 0 ? filteredCategories : [Uncategorized]; } catch (error) { console.error(AI classification failed:, error); // 降级策略如果AI调用失败尝试从标签中匹配或者返回默认分类 return fallbackClassification(skillTags); } } // 降级策略函数示例 function fallbackClassification(tags: string[]): string[] { const tagToCategoryMap: Recordstring, string { react: Frontend Development, nextjs: Frontend Development, node: Backend Development, docker: DevOps Infrastructure, jest: Testing QA, // ... 更多映射 }; const mapped tags.map(tag tagToCategoryMap[tag.toLowerCase()]).filter(Boolean); return [...new Set(mapped)]; // 去重 }关键要点与优化建议Prompt 工程上面的 Prompt 包含了角色设定、清晰的任务说明、分类列表、输入数据和输出格式要求。这是获得高质量、结构化结果的基础。在实际项目中可能需要反复调试 Prompt。错误处理与降级AI 服务可能不稳定或超时。必须有健壮的错误处理。降级策略如基于标签的关键词匹配能保证系统在 AI 服务不可用时依然能运行尽管准确性会下降。成本与延迟考虑gemini-1.5-flash是性价比高的选择。对于大量技能的分类可以考虑批量处理或者将分类结果缓存起来避免对同一技能的重复分类。结果验证AI 可能返回不在列表中的分类名。代码中增加了验证步骤确保只返回系统认可的分类。6. 部署与生产环境考量让项目在本地运行只是第一步。要真正提供服务你需要部署它。6.1 部署平台选择AGNXI 的技术栈天然适合部署在Vercel上。无缝集成Next.js 是 Vercel 的亲儿子部署体验最好支持 Serverless Functions、Edge Functions 等。环境变量管理Vercel 项目设置中可以方便地配置所有环境变量。数据库连接需要确保你的 PostgreSQL 数据库如 Neon允许从 Vercel 的 IP 连接。通常云数据库服务都提供了连接串和 IP 白名单功能。后台任务Inngest 服务是独立的部署后需要将你的 Inngest 函数服务器通常是一个单独的 Node.js 服务也部署出去并配置好INNGEST_EVENT_KEY等。Vercel 的 Serverless Functions 可以运行 Inngest 函数。6.2 生产环境配置差异数据库迁移生产环境绝对不要使用db:push。应该使用迁移bun db:generate # 在修改 schema 后生成迁移文件 bun db:migrate # 在生产环境运行此命令来应用迁移环境变量在 Vercel 等平台严格区分开发和生产环境变量。像CLERK_SECRET_KEY、DATABASE_URL这些敏感信息绝不能提交到代码仓库。Clerk 配置在 Clerk Dashboard 中为你的生产域名如https://agnxi.vercel.app配置正确的回调 URLCallback URL和重定向 URL。缓存策略生产环境下合理配置 Upstash Redis 的持久化策略和内存大小。为高频访问的接口如技能列表 API设置缓存并注意缓存失效策略。监控与日志配置错误监控如 Sentry和日志收集服务以便及时发现和排查问题。6.3 自定义域名与 SEOAGNXI 作为一个目录网站SEO 很重要。自定义域名在 Vercel 项目中绑定你自己的域名。SEO 组件项目中的components/seo/目录应该包含了用于管理页面标题、描述的组件。确保每个技能详情页都有独特的、包含关键词的title和description。站点地图项目提供了bun ping:indexnow脚本用于向搜索引擎提交站点地图。你需要确保app/sitemap.ts或robots.ts文件正确生成并包含了所有技能页面的链接。性能优化使用 Next.js 的Image组件优化图片对技能列表页使用generateStaticParams进行部分静态生成或增量静态再生ISR以提升加载速度和 SEO 表现。7. 常见问题排查与扩展思路在复现和使用 AGNXI 的过程中你可能会遇到以下问题7.1 问题排查速查表问题现象可能原因解决方案bun install失败网络问题或原生模块编译失败1. 检查网络尝试使用镜像。2. 确保已安装 Python、C编译环境如 windows-build-tools。3. 删除node_modules和bun.lockb后重试。启动后访问localhost:3000报数据库连接错误DATABASE_URL配置错误或数据库未启动1. 检查.env.local文件中的DATABASE_URL格式是否正确。2. 确认 PostgreSQL 服务已运行 (pg_isready或sudo systemctl status postgresql)。3. 检查用户名、密码、数据库名是否正确。技能列表为空控制台报 GitHub API 错误GITHUB_TOKEN未设置或权限不足/失效1. 确认.env.local中已配置有效的 Token。2. 在 GitHub 上检查 Token 的权限是否包含repo和read:packages。3. Token 可能已过期重新生成一个。AI 分类功能不工作返回“Uncategorized”GOOGLE_GENERATIVE_AI_API_KEY错误或未启用 API1. 检查 API 密钥是否正确且对应项目已启用 Gemini API。2. 查看浏览器控制台或服务器日志确认是否有 AI 调用的错误信息。3. 可能是 Prompt 设计问题尝试简化 Prompt 进行测试。用户登录Clerk后页面刷新又变回未登录Clerk 前端密钥与后端密钥不匹配或回调 URL 配置错误1. 检查NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY和CLERK_SECRET_KEY是否来自同一个 Clerk 应用。2. 在 Clerk Dashboard 中检查应用的回调 URL 是否包含http://localhost:3000。后台同步任务未执行Inngest 配置错误或函数未正确注册1. 检查INNGEST_EVENT_KEY和INNGEST_SIGNING_KEY是否正确。2. 确认 Inngest 函数服务器已成功启动并与 Inngest Cloud 连接。3. 查看 Inngest Cloud 仪表板是否有对应的事件被触发。7.2 项目扩展与二次开发思路AGNXI 提供了一个优秀的起点你可以在此基础上添加更多功能技能评分与评论系统让用户可以对技能进行评分和评论形成社区反馈帮助其他人判断技能质量。技能依赖分析解析SKILL.md自动识别该技能可能依赖的其他技能或工具并建立关联图谱。个性化推荐根据用户收藏、浏览历史利用协同过滤等算法推荐可能感兴趣的技能。技能版本管理跟踪SKILL.md文件的更新历史允许用户查看差异并选择使用特定版本。离线模式或浏览器扩展开发一个浏览器扩展让用户能在 GitHub 仓库页面直接看到该技能的 AGNXI 评分和信息并一键安装。支持更多 AI 助手除了 Claude Code 和 Cursor可以扩展对更多编辑器和 IDE 插件的支持如 VS Code 的 Continue 插件等。这个项目清晰地展示了一个全栈应用如何将数据爬取、AI 处理、后台任务、现代前端和用户体验有机结合。无论你是想直接使用这个技能目录来提升自己的开发效率还是想学习如何构建一个类似的平台AGNXI 的代码都值得你花时间深入研究。我在搭建过程中最大的体会是清晰的架构设计和对第三方服务的合理运用能让你一个人也能快速构建出功能复杂、体验专业的应用。遇到问题多查日志、善用调试工具并勇于翻阅官方文档大部分技术难题都能迎刃而解。