diff --git a/.agents/skills/blogflare-api/SKILL.md b/.agents/skills/blogflare-api/SKILL.md
new file mode 100644
index 0000000..e616cc7
--- /dev/null
+++ b/.agents/skills/blogflare-api/SKILL.md
@@ -0,0 +1,103 @@
+---
+name: blogflare-api
+description: 如何调用 BlogFlare 本地或线上的 REST API 来管理（增删改查）文章，附带 OpenAPI schema 与使用示例。
+---
+
+# BlogFlare API 操作指南
+
+当用户要求你“通过接口/API读取文章”、“通过接口更新文章”或者当你需要远程管理 BlogFlare 的数据时，请使用本指南提供的 RESTful API。
+
+## 认证机制
+
+所有 `/api/v1/posts` 下的接口都需要在 HTTP 请求头中带上 `Authorization: Bearer <Token>`。
+其中 Token 需要保存在数据库 `settings` 表的 `agent.api_token` 字段中。
+
+**如果在本地开发环境 (dev) 调试：**
+如果遇到 Token 未设置，你可以先帮用户在 `settings` 表插入/更新：
+`INSERT INTO settings (key, value) VALUES ('agent.api_token', 'your_test_token') ON CONFLICT(key) DO UPDATE SET value = excluded.value;`
+
+## 接口说明
+
+### 1. 获取文章列表 (GET `/api/v1/posts`)
+
+**参数：**
+
+- `limit` (默认 10)
+- `offset` (默认 0)
+
+**响应格式：**
+
+```json
+{
+	"data": [
+		{
+			"id": 1,
+			"slug": "hello-world",
+			"title": "...",
+			"published_at": "...",
+			"category_slug": "..."
+		}
+	],
+	"meta": { "total": 10, "limit": 10, "offset": 0 }
+}
+```
+
+### 2. 获取单篇文章详情 (GET `/api/v1/posts/[slug]`)
+
+**响应格式：**
+
+```json
+{
+	"data": {
+		"id": 1,
+		"slug": "hello-world",
+		"title": "...",
+		"content": "...",
+		"published_at": "...",
+		"updated_at": "...",
+		"category_slug": "tech"
+	}
+}
+```
+
+### 3. 创建新文章 (POST `/api/v1/posts`)
+
+**Body (JSON)：**
+
+```json
+{
+	"slug": "new-post-slug",
+	"title": "New Post Title",
+	"content": "Markdown content here...",
+	"category_slug": "tech"
+}
+```
+
+**响应格式：**
+
+```json
+{ "success": true, "slug": "new-post-slug", "title": "New Post Title" }
+```
+
+### 4. 更新文章 (PUT `/api/v1/posts/[slug]`)
+
+**Body (JSON) [可选字段]：**
+
+```json
+{
+	"title": "Updated Title",
+	"content": "Updated Markdown content...",
+	"category_slug": "life"
+}
+```
+
+**响应格式：**
+
+```json
+{ "success": true, "slug": "the-post-slug" }
+```
+
+## 注意事项
+
+- 本地调试可以运行 `npm run dev`，然后用 `curl` 测试。
+- 请勿随意删除或覆盖已有的真实文章数据。在更新之前，最好先 GET 取回全量 content 进行 diff 确认。