ASS 1.0 核心规范

本文档定义了 Agent Skill Specification (ASS) 1.0 的核心结构和要求。

1. 概述

Agent Skill 是一个可复用的能力模块，可以被 AI Agent 动态加载以扩展其能力边界。ASS 规范旨在：

• 提供标准化的技能定义格式
• 确保跨平台兼容性
• 保障安全性和可审计性

2. 技能结构

每个符合 ASS 1.0 规范的技能必须包含以下文件：

my-skill/
├── skill.yaml          # 元数据定义 (必需)
├── README.md           # 技能文档 (必需)
├── src/                # 源代码目录
│   └── index.ts        # 入口文件
└── tests/              # 测试目录
    └── index.test.ts

3. skill.yaml 规范

ass_version: "1.0"
name: "skill-name"
version: "1.0.0"
description: "技能的简短描述"

author:
  name: "作者名称"
  url: "https://example.com"

license: "Apache-2.0"

keywords:
  - keyword1
  - keyword2

categories:
  - document-processing

compatibility:
  platforms:
    - claude-code
    - openai-gpt
  min_runtime: "1.0"

triggers:
  - "当用户提到 PDF 时"
  - "当文件扩展名为 .pdf 时"

security:
  network_access: false
  filesystem_scope: "workspace"
  requires_approval: false

4. 安全模型

ASS 1.0 定义了三级安全模型：

级别	网络访问	文件系统	用户审批
沙箱模式	❌	仅工作区	无需
标准模式	✅ (白名单)	可配置	敏感操作需要
完全信任	✅	完全访问	首次加载需要

5. 接口规范

技能必须导出以下标准接口：

export interface AgentSkill {
  // 技能元数据
  readonly metadata: SkillMetadata;
  
  // 初始化方法
  initialize(context: SkillContext): Promise<void>;
  
  // 执行入口
  execute(input: SkillInput): Promise<SkillOutput>;
  
  // 清理资源
  dispose(): Promise<void>;
}

6. 版本兼容性

• ASS 1.0 技能可以在任何声称支持 ASS 1.0 的运行时中执行
• 运行时必须向后兼容同一主版本号的所有次版本
• 重大变更 (Breaking Changes) 只能在主版本升级时引入