nikfot/skill-contracts-protocol
GitHub: nikfot/skill-contracts-protocol
SCP 是一个为 LLM 智能体提供声明式、可强制执行技能契约的协议，规范了工具使用、证据收集和任务完成条件。
Stars: 0 | Forks: 0
# SCP -- 技能契约协议
用于 LLM 智能体技能的声明式、可强制执行的契约。定义使用哪些工具、收集哪些证据以及何时完成。
## 这是什么？
当今的 LLM 智能体要么自由发挥（没有防护栏），要么将编排逻辑硬编码在框架代码中。**SCP** 将这种逻辑置于一个可移植、声明式的契约中：智能体可以使用哪些工具、应该遵循哪些步骤、在完成之前必须收集哪些证据。一份规范，任何框架——可直接将其放入 Cursor 技能、LangGraph、PydanticAI 或您自己的智能体循环中。
SCP 扩展了 [agentskills.io](https://agentskills.io) 格式，增加了可强制执行的运行时约束。每个 SCP 文件同时也是一个有效的 `agentskills.io` 技能——SCP 在此基础上增加了*契约层*。
## 生态定位
```
graph TB
subgraph Format["Format Layer -- agentskills.io"]
SPEC["agentskills.io specification
SKILL.md + YAML frontmatter
Discovery, packaging, metadata"] end subgraph Contract["Contract Layer -- SCP"] SCP["Skill Contracts Protocol
tool_ids, evidence gates,
query plans, finalization rules
Runtime enforcement engine"] end subgraph Content["Content Layer -- Skill Libraries"] ELASTIC["Elastic agent-skills"] CLICK["ClickHouse agent-skills"] WEAV["Weaviate agent-skills"] CUSTOM["Your org's skills"] end SCP -->|"extends"| SPEC ELASTIC -->|"uses format"| SPEC CLICK -->|"uses format"| SPEC WEAV -->|"uses format"| SPEC CUSTOM -->|"uses format"| SPEC SCP -.->|"adds contracts to"| Content ``` ## 快速示例 在任何 SKILL.md 前置信息中添加一个 `scp` 约束块： ``` --- scp: "1.0" name: investigate-latency description: Investigate service latency spikes activation: triggers: [latency, slo burn, p99] constraints: tool_ids: - run_es_query - generate_report plan: - tool: run_es_query description: Fetch raw latency data args_template: query: "FROM heartbeat-* | WHERE url.domain == '{{domain}}'" - tool: run_es_query description: Compute percentiles evidence: required: - id: data_presence description: Data exists for target service - id: latency_distribution description: Percentile stats are computed finalization: require_all_evidence: true min_iterations: 1 --- # 调查延迟 Your regular skill markdown content here... ``` ## 安装 ``` uv add skill-contracts-protocol # 或 pip install skill-contracts-protocol ``` ## 验证技能文件 ``` scp validate path/to/skills/ ``` ## 检查 Elastic 兼容性 ``` scp elastic-check path/to/skills/ ``` ## 使用运行时 ``` from scp import load_skill from scp.runtime import SkillEnforcer, EvidenceTracker, PlanExecutor contract = load_skill("path/to/SKILL.md") enforcer = SkillEnforcer(contract) tracker = EvidenceTracker(contract) planner = PlanExecutor(contract) # 在您的 agent 循环中： for step in planner: result = your_tool_runner(step.tool, step.args) tracker.record(result) if enforcer.can_finalize(tracker): break ``` ## 包内容 | 模块 | 用途 | |--------|---------| | `scp.models` | Pydantic 模型：`SkillContract`、`Evidence`、`QueryStep`、`FinalizationRules` | | `scp.loader` | 将 SKILL.md YAML 前置信息解析为 `SkillContract` | | `scp.validator` | 引用完整性检查（`tool_ids` 与计划步骤） | | `scp.cli` | CLI：`scp validate`、`scp convert`、`scp elastic-check` |
| `scp.runtime` | 强制执行引擎：`SkillEnforcer`、`EvidenceTracker`、`PlanExecutor` |
| `scp.adapters` | 系统提示构建器 + Elastic Agent Builder 适配器 |
| `scp.elastic_compat` | Elastic 命名/限制验证 |
## 与 agentskills.io 有何不同？
`agentskills.io` 定义了**格式**（SKILL.md + YAML 前置信息），并专注于发现和打包。SCP 通过**契约层**扩展了该格式——工具防护栏、证据门槛、查询计划和最终化规则——加上一个在执行时强制执行这些契约的 Python 运行时。
## 与 Cursor 技能有何不同？
Cursor 技能告诉智能体*做什么*；SCP 告诉它*如何保持在正轨上*——可强制执行的工具防护栏、证据门槛和最终化规则，这些是目前任何 SKILL.md 都无法表达的。
## 许可证
MIT
SKILL.md + YAML frontmatter
Discovery, packaging, metadata"] end subgraph Contract["Contract Layer -- SCP"] SCP["Skill Contracts Protocol
tool_ids, evidence gates,
query plans, finalization rules
Runtime enforcement engine"] end subgraph Content["Content Layer -- Skill Libraries"] ELASTIC["Elastic agent-skills"] CLICK["ClickHouse agent-skills"] WEAV["Weaviate agent-skills"] CUSTOM["Your org's skills"] end SCP -->|"extends"| SPEC ELASTIC -->|"uses format"| SPEC CLICK -->|"uses format"| SPEC WEAV -->|"uses format"| SPEC CUSTOM -->|"uses format"| SPEC SCP -.->|"adds contracts to"| Content ``` ## 快速示例 在任何 SKILL.md 前置信息中添加一个 `scp` 约束块： ``` --- scp: "1.0" name: investigate-latency description: Investigate service latency spikes activation: triggers: [latency, slo burn, p99] constraints: tool_ids: - run_es_query - generate_report plan: - tool: run_es_query description: Fetch raw latency data args_template: query: "FROM heartbeat-* | WHERE url.domain == '{{domain}}'" - tool: run_es_query description: Compute percentiles evidence: required: - id: data_presence description: Data exists for target service - id: latency_distribution description: Percentile stats are computed finalization: require_all_evidence: true min_iterations: 1 --- # 调查延迟 Your regular skill markdown content here... ``` ## 安装 ``` uv add skill-contracts-protocol # 或 pip install skill-contracts-protocol ``` ## 验证技能文件 ``` scp validate path/to/skills/ ``` ## 检查 Elastic 兼容性 ``` scp elastic-check path/to/skills/ ``` ## 使用运行时 ``` from scp import load_skill from scp.runtime import SkillEnforcer, EvidenceTracker, PlanExecutor contract = load_skill("path/to/SKILL.md") enforcer = SkillEnforcer(contract) tracker = EvidenceTracker(contract) planner = PlanExecutor(contract) # 在您的 agent 循环中： for step in planner: result = your_tool_runner(step.tool, step.args) tracker.record(result) if enforcer.can_finalize(tracker): break ``` ## 包内容 | 模块 | 用途 | |--------|---------| | `scp.models` | Pydantic 模型：`SkillContract`、`Evidence`、`QueryStep`、`FinalizationRules` | | `scp.loader` | 将 SKILL.md YAML 前置信息解析为 `SkillContract` | | `scp.validator` | 引用完整性检查（`tool_ids` 与计划步骤） | | `scp.cli` | CLI：`scp validate
标签：agentskills.io, AI代理, Cursor, ESC漏洞, LangGraph, LLM代理, PydanticAI, 代理技能管理, 代理框架, 代理行为管理, 协议扩展, 可移植性, 合同层, 声明性协议, 声明性规范, 工具定义, 强制执行引擎, 技术栈集成, 技能合同, 技能定义, 文档结构分析, 最终化规则, 查询计划, 约束规则, 证据收集, 运行时约束, 逆向工具