企业官网建设流程全解析

1. 为什么 Cursor 里的 Skill 总是“加载不上”

如果你在 Cursor 里写过.cursor/skills/xxx/SKILL.md，大概率遇到过这种场景：文件明明建好了，Agent 却像没看见一样，问它“有哪些技能可用”答不上来，让它执行某个工作流也只会临场发挥。问题通常不在模型，而在“声明”和“加载”这两步没打通。

Cursor 的 Skill 机制本质上是两段式：第一段是能力声明，把可用技能的名字和描述写进AGENTS.md，让 Agent 启动时就知道自己“会什么”；第二段是按需读取，Agent 判断需要某个技能时，再通过 CLI 把完整的SKILL.md内容读进上下文。只写文件不做声明，Agent 就没有索引；只做声明但 CLI 读不到内容，Agent 拿到的是空壳。

这套链路里还有两个容易忽略的点。一是双层目录：项目级.cursor/skills/优先级高于全局~/.cursor/skills/，同名技能项目级会覆盖全局，很多人把技能放错层导致“改了没生效”。二是 Token 成本：如果把所有技能的完整内容都塞进AGENTS.md，上下文会被迅速吃满，所以正确做法是AGENTS.md只存摘要，正文靠read命令按需拉取。

这篇就按“声明 → 加载 → 验证”的顺序，把AGENTS.md的标记结构、cursor-skills的 CLI 触发链路、以及用 TaoToken 统一 Key 接入的配置骨架串起来，最后给一套能直接跑的验证动作，确认自动加载真的生效了。

2. TaoToken 前置：统一 Key 与接入地址

在配 Skill 之前，先把模型调用这条链路固定下来。Cursor 里的 Agent 要真正跑起来，背后得有稳定的模型入口。TaoToken 在这里的角色是提供一个统一的 API Key 和兼容的接入地址，这样你在config.toml、settings.json里填一次，后续换模型、加技能都不用反复改鉴权。

需要记住两个地址，用途不同：

官网入口（注册、看文档、进控制台）：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

API 基址（写进配置文件的那个）：https://taotoken.net/api

注意 API 基址不要带 UTM 参数，配置文件里多一个查询串有些客户端会解析异常。Key 的获取在控制台的 API Keys 页面，生成后只显示一次，建议直接存进环境变量而不是硬编码进仓库。

按你的使用场景，入口可以这样分流：

• 只是想让 Agent 能对话、验证模型通不通：走模型对话页 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• 要长期在 Cursor 里做编码、跑 Agent 工作流：走 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• 管理 Key、看用量：走控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• 生成或轮换 Key：走 API Keys https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

先把 Key 拿到手，后面所有配置都围绕它展开。

3. 可复制配置：AGENTS.md 骨架 + config.toml + settings.json

这一节是全文的核心，三份文件配好，Skill 自动加载的骨架就立起来了。

3.1 AGENTS.md 的标记结构

AGENTS.md放在项目根目录，关键是那对 HTML 注释标记。cursor-skills sync只会替换标记之间的内容，标记外的项目说明、自定义指令都会被保留，所以这个文件可以反复 sync 而不会覆盖你手写的东西。

# 项目 Agent 说明 本项目使用 cursor-skills 管理技能，技能列表由 CLI 自动维护，请勿手动编辑标记区域。 <!-- SKILLS_TABLE_START --> <available_skills> <skill> <name>figma2code</name> <description>Convert Figma designs to React components</description> <location>project</location> </skill> <skill> <name>code-review</name> <description>Automated code review workflow</description> <location>global</location> </skill> </available_skills> <!-- SKILLS_TABLE_END --> <usage> 当需要使用某个技能时，执行 Bash("cursor-skills read <skill-name>") 获取完整技能内容， 再按照其中的工作流执行任务。不要凭记忆猜测技能内容。 </usage>

这里<usage>段是给 Agent 的行为指令，明确告诉它“先 read 再执行”，否则模型可能直接跳过读取步骤自己编流程。location字段区分 project 和 global，方便排查同名覆盖问题。

3.2 技能文件本身

每个技能是一个目录，核心是SKILL.md，开头用 YAML Front Matter 声明元数据，CLI 扫描时就是解析这段：

--- name: figma2code description: Convert Figma designs to React components --- ## 工作流程 1. 获取 Figma 设计稿 JSON 2. 解析设计结构 3. 生成 React 组件代码 ## 使用方式 调用 `scripts/generate.js` 并传入 Figma URL。

目录结构建议这样组织，脚本和模板分开放，read命令输出时会带上基础目录路径，Agent 才能正确解析相对引用：

.cursor/skills/ ├── figma2code/ │ ├── SKILL.md │ ├── scripts/ │ └── templates/ └── code-review/ └── SKILL.md

3.3 config.toml 接入 TaoToken

Cursor 的 CLI 侧配置用config.toml，把模型入口指向 TaoToken，Key 从环境变量读：

# ~/.cursor/config.toml [model] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" model = "claude-sonnet-4-5" [agent] skills_dir = ".cursor/skills" global_skills_dir = "~/.cursor/skills" agents_file = "AGENTS.md"

api_key_env指向环境变量名而不是明文，这样配置文件可以进 Git。环境变量在 shell 里设置：

export TAOTOKEN_API_KEY="sk-你的key"

Windows PowerShell 用$env:TAOTOKEN_API_KEY="sk-你的key"，想持久化就写进系统环境变量。

3.4 settings.json 补充编辑器侧行为

Cursor 的settings.json负责编辑器层面的开关，和config.toml分工不同：

{ "cursor.agent.skills.enabled": true, "cursor.agent.skills.autoSync": true, "cursor.agent.skills.agentsFile": "AGENTS.md", "cursor.agent.skills.projectDir": ".cursor/skills", "cursor.agent.skills.globalDir": "~/.cursor/skills", "cursor.agent.skills.readCommand": "cursor-skills read" }

autoSync打开后，新增技能目录时编辑器会提示同步到AGENTS.md，省去手动跑命令。readCommand要和实际安装的 CLI 命令名一致，如果你用 npx 方式调用，这里就写npx cursor-skills read。

4. 验证请求：确认自动加载真的生效

配置写完不代表生效，得用几个动作逐层验证。我一般按“CLI 层 → 文件层 → Agent 层”三步走。

4.1 CLI 层：技能能不能被扫出来

先确认 CLI 能发现技能。在项目根目录执行：

cursor-skills list

预期输出类似：

Available skills: figma2code [project] Convert Figma designs to React components code-review [global] Automated code review workflow

如果列表为空，检查.cursor/skills/下每个技能目录里是否有SKILL.md，以及 Front Matter 的---是否顶格写。CLI 扫描时单个技能读取失败会静默跳过，所以“少了一个”往往就是那个文件的格式问题。

4.2 文件层：AGENTS.md 标记区是否被正确更新

跑一次同步：

cursor-skills sync

交互界面里用空格勾选技能，回车确认。然后检查AGENTS.md：

grep -A 20 "SKILLS_TABLE_START" AGENTS.md

确认标记之间的<available_skills>里出现了你勾选的技能，且标记外的自定义内容没被动过。再跑一次sync，如果内容不变，说明幂等性正常，标记分割策略生效了。

4.3 Agent 层：read 命令能否返回完整内容

这是最关键的一步，直接模拟 Agent 的调用：

cursor-skills read figma2code

预期输出会带上基础目录和完整正文：

# Skill: figma2code Base directory: /Users/dev/project/.cursor/skills/figma2code Location: project --- ## 工作流程 1. 获取 Figma 设计稿 JSON ...

如果报Skill 'figma2code' not found，说明list阶段就没扫到，回到 4.1 排查。如果输出里没有Base directory，检查 CLI 版本，老版本不带这个字段，Agent 解析相对路径会失败。

4.4 端到端：在 Cursor 里发一条真实请求

最后在 Cursor 对话框里发一句：“帮我把这个 Figma 设计转成代码”。观察 Agent 的行为链路：它应该先识别到figma2code可用，然后执行cursor-skills read figma2code，再按技能里的工作流走。如果它直接开始写代码而没读技能，说明AGENTS.md里的<usage>指令没被采纳，可以把指令写得更强硬一点，比如加上“必须先执行 read 命令，否则视为无效响应”。

5. 本篇常见错排查

技能列表为空，但文件确实存在。九成是 Front Matter 格式问题。---必须独占一行且顶格，name和description的冒号后面要有空格。另外注意文件编码，带 BOM 的 UTF-8 会让正则匹配^---失败。

同名技能改了项目级但没生效。检查是不是全局目录里也有同名技能。项目级优先级高，但如果项目级那个SKILL.md解析失败被跳过了，实际生效的就变成全局的了。用cursor-skills list看location字段确认。

sync之后自定义内容被覆盖。说明AGENTS.md里没有那对标记，CLI 走了“无标记则生成完整内容”的分支，把整个文件重写了。补救办法是手动把标记加回去，把自定义内容挪到标记外。

Agent 读到了技能但不按流程走。这是提示词层面的问题，不是加载问题。在SKILL.md里把步骤写得更具体，减少模型自由发挥的空间；同时在AGENTS.md的<usage>里强调“严格按技能内容执行”。

API 请求 401 或鉴权失败。先确认环境变量TAOTOKEN_API_KEY在当前 shell 里能echo出来，Cursor 从 GUI 启动时可能读不到你终端里 export 的变量，这种情况写进系统环境变量更稳。再确认base_url是https://taotoken.net/api，没有多余斜杠或查询串。

Token 消耗异常快。检查是不是把完整技能内容写进了AGENTS.md。正确做法是只放摘要，正文靠read按需加载。如果某个技能特别大，可以在SKILL.md里拆分，把长示例放到templates/目录，正文只留引用。

6. 接入与排障入口

上面这套链路跑通后，Skill 的自动加载就稳定了。如果你在配置config.toml或settings.json时卡在鉴权环节，直接去 API Keys 页面重新生成一个 Key 试试，排除 Key 本身失效的可能：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

接入参数、兼容格式、报错码这些细节，接入文档里列得比较全，遇到 4xx 先查文档再改配置：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

如果你只是想先确认模型通不通，不想动 Cursor 配置，可以在模型对话页发一条测试请求，验证 Key 和基址没问题后再回到编辑器里配：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

长期在 Cursor 里跑编码和 Agent 工作流的，Coding Plan 的额度模型更适合这种高频调用场景，不用每次按量计费：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

最后提一个实操细节：cursor-skills sync建议在提交代码前跑一次，把AGENTS.md的变更一起提交，这样团队里其他人拉下来就能直接用，不用各自再同步一遍。技能目录本身也进 Git，SKILL.md的版本历史就是团队工作流的演进记录。