Skill 指南

这一页说明 Ageniti app 如何把自己的 skill 暴露给 Agent、coding assistant 和自动化系统。文档站也提供 /llms.txt，会把英文文档合并成一份适合机器读取的纯文本内容。

Ageniti 是什么

Ageniti 是用来构建给 Agent 使用的应用的 SDK。它让 React 或 TypeScript 应用把选定能力暴露成结构化 action，并通过 CLI、HTTP、MCP、OpenAI-compatible tools、Vercel AI SDK 风格 tools、JSON 自动化、本地 dev console，以及 React 直接调用来使用。

Ageniti 不负责创建 agent。它负责让你的应用可以被 agent 调用。

核心模型

Existing app capability
        |
        v
Ageniti action contract
        |
        v
Shared runtime
        |
        +--> CLI
        +--> HTTP
        +--> MCP
        +--> OpenAI tools
        +--> AI SDK tools
        +--> JSON runner
        +--> Dev console
        +--> React invocation

Action contract 是事实来源。外部 surface 应该统一经过 shared runtime，这样校验、权限、确认、超时、重试、中间件、日志、artifacts 和 output 校验才会保持一致。

标准导入

import { createAgenitiApp, defineAction, s } from "@ageniti/core";

只有在宿主需要更窄边界时才使用 subpath import：

import { createMcpHandler } from "@ageniti/core/mcp";
import { createHttpHandler } from "@ageniti/core/http";
import { createAISDKTools, createOpenAITools } from "@ageniti/core/ai-sdk";

最小 Action 模式

import { createAgenitiApp, defineAction, s } from "@ageniti/core";
 
export const createTask = defineAction({
  name: "create_task",
  version: "1.0.0",
  description: "Create a workspace task.",
  visibility: "public",
  sideEffects: "write",
  idempotency: "conditional",
  permissions: ["task:create"],
  input: s.object({
    title: s.string().min(1).describe("Task title"),
    priority: s.enum(["low", "normal", "high"]).default("normal"),
  }),
  output: s.object({
    taskId: s.string(),
    status: s.string(),
  }),
  async run(input, ctx) {
    return ctx.services.tasks.create(input);
  },
});
 
export const app = createAgenitiApp({
  name: "task-app",
  description: "Workspace task operations exposed to agents.",
  actions: [createTask],
  services: {
    tasks,
  },
});

React 和 Expo 推荐结构

对于 React、Next.js、Expo 或任何有 UI 的 app，把 Ageniti 放在一个 headless、Node-safe 的入口里：

src/ageniti/app.js
src/ageniti/actions/create-task.js
src/ageniti/services/tasks.js

不要从用于 CLI、MCP、HTTP、package 或 publish 的 Ageniti 入口里 import React component、browser-only API、route handler 或 mobile runtime 代码。把可复用业务逻辑放到 services，再由 action 调用这些 services。

Surface

app.createCli() 创建 CLI，包含 action 命令、schema、manifest、docs、build、package、publish、init、doctor、lint、MCP 和 dev 命令。
app.createHttpHandler() 创建轻量 HTTP JSON handler，并通过 shared runtime 调用 action。
app.createMcpHandler() 创建 MCP JSON-RPC handler，支持 tools/list 和 tools/call。
app.createOpenAITools() 创建 OpenAI Chat Completions 风格 tool definitions。
app.createOpenAIResponsesTools() 创建 OpenAI Responses 风格 function tool definitions。
app.createAISDKTools() 创建 Vercel AI SDK 风格 executable tools。
app.createJsonRunner() 创建给脚本、测试和自动化使用的结构化 runner。
app.createDevServer() 启动本地 action 检查和测试 console。
app.createReactAdapter() 创建适合现有 React UI 调用 action 的 adapter。

给 Agent 的安全规则

通过 runtime 或 app 创建的 adapter 调用 action。不要直接调用 action.run()。
尊重 visibility、supportedSurfaces、sideEffects、requiresConfirmation、permissions、version、deprecated 和 deprecation。
Private action 不是 public API，不要从外部 agent surface 暴露或调用。
Destructive action 默认要求确认，并且默认不会暴露到 LLM-oriented surface，除非显式允许。
Secret、内部 ID、非公开实现说明放进 metadata，不要放进 publicMetadata。
面向 agent 的说明写在 description、docs 和 publicMetadata。
把 GUIDE.md、manifest、schema 和 action metadata 当作公开 contract。

说明书导出

Ageniti 可以从 app 和 action 上的自然语言字段导出一份确定性的统一说明书。它不会调用模型，也不会从 UI 代码里猜测隐藏行为。

推荐填写：

app description
app docs.summary
app docs.audience
app docs.whenToUse
app docs.setup
app docs.operationalNotes
action description
action docs.whenToUse
action docs.whenNotToUse
action docs.usageNotes
action docs.inputExample
action docs.outputExample
action publicMetadata

导出命令：

task-app docs
task-app docs --out-dir ./dist/ageniti
task-app build docs --out-dir ./dist/ageniti
task-app build bundle --out-dir ./dist/ageniti

输出文件是 GUIDE.md。bundle 会自动包含它。

构建和发布

npx @ageniti/core init react
npx @ageniti/core init expo
npx @ageniti/core init next
npx @ageniti/core doctor
task-app build
task-app build bundle --app-module ./src/ageniti/app.js --app-export app --out-dir ./dist/ageniti
task-app package --app-module ./src/ageniti/app.js --app-export app --out-dir ./dist/ageniti
task-app publish --app-module ./src/ageniti/app.js --app-export app --out-dir ./dist/ageniti

bundle 会生成：

ageniti.manifest.json
ageniti.actions.json
ageniti.mcp.json
cli.mjs
mcp-stdio.mjs
GUIDE.md
package.json
README.md
ageniti.bundle.json

生成的 npm package 是 app distribution package，包含可运行的 CLI、MCP launcher、manifest 和文档。

不要这样做

不要把 Ageniti 描述成 Agent 框架。
不要让 Ageniti 接管 planning、memory、workflow orchestration、routing 或 UI state。
不要扫描任意 React component 并自动暴露成 tools。
不要绕过 runtime validation 和 permissions。
不要把 secret 放进生成文档、public metadata、manifest 或示例。
不要因为调用方猜到了 action name，就暴露 hidden action。

有用文件

README.md：给人看的整体介绍。
docs/getting-started.md：第一个可运行集成。
docs/api.md：公开 API 参考。
docs/scope.md：明确的产品边界。
docs/release-checklist.md：发布检查清单。
docs/skill.md：包含在 npm 包内的 skill-facing SDK guide。