编程代理技能

Archyl 提供 11 个编程代理技能，把您的整个架构带进编程代理——Claude Code、Codex、Cursor 或任何兼容工具。您无需在编辑器和 Archyl 仪表板之间来回切换，代理就能在您编码之前验证变更、记录已上线的内容、对照 C4 模型审查 Pull Request，并预测架构漂移——全部在终端中完成。

这些技能是开源的，可在 github.com/archyl-com/agent-skills 获取。

AI 原生的架构工作流

这 11 个技能协同工作，形成一个持续的架构闭环：

preflight → code → review → CI (GitHub Actions) → postship → generate context
    ↑                                                              |
    └──────────────────────────────────────────────────────────────┘

前置条件

• 拥有 API 访问权限的 Archyl 账户
• API 密钥（可在 Archyl 仪表板的 个人资料 > API 密钥 中获取）
• Claude Code、Codex、Cursor 或兼容的编程代理

安装

第 1 步：添加市场

在 Claude Code 中运行以下命令：

/plugin marketplace add archyl-com/agent-skills

然后配置自动更新：

1. 运行 /plugin
2. 选择 Marketplaces
3. 选择 archyl-marketplace
4. 选择 Enable auto-update

第 2 步：安装插件

/plugin install archyl-developer@archyl-marketplace

archyl-developer 插件会安装全部 11 个技能以及 Guard 钩子。安装后重启您的编程代理。

第 3 步：配置 MCP 服务器

将 Archyl MCP 服务器添加到项目的 .mcp.json 文件中：

{
    "mcpServers": {
        "archyl": {
            "type": "http",
            "url": "https://api.archyl.com/mcp",
            "headers": {
                "X-API-Key": "arch_your_api_key_here"
            }
        }
    }
}

将 arch_your_api_key_here 替换为您在 Archyl 仪表板中获取的实际 API 密钥。

其他编程代理

这些技能文件兼容任何支持插件格式的代理。对于 Cursor、Codex 或其他工具，您也可以直接使用 agent-skills 仓库中的文件。

快速设置

最快的上手方式是运行设置脚本。它会生成代理所需的全部配置文件。

设置脚本

在项目根目录下运行：

npx archyl-setup

该命令会创建三个文件：

模板：CLAUDE.md

生成的 CLAUDE.md 包含如下指令：

# Architecture

This project is documented in Archyl (project ID: `proj_xxx`).

## Before coding
Run `/archyl-preflight` to validate your approach against the architecture.

## After shipping
Run `/archyl-postship` to update the C4 model and create ADRs.

## Architecture rules
Always run `/archyl-review` before requesting a code review.

您可以根据团队的工作流自定义这些模板。

核心技能

archyl-developer

基础技能。它让您的代理系统地了解 Archyl 的 200 多个 MCP 工具，涵盖以下领域：

示例提示词：

Create a new system called PaymentPlatform with containers for
the API server, a PostgreSQL database, and a React frontend.

Create an ADR titled "Migrate from REST to gRPC for internal services".
Set it as proposed, explain the context around latency requirements,
and link it to the ApiGateway and PaymentService containers.

Show me the technology radar. Add Temporal as an adopted workflow
orchestration technology and tag it on the OrderProcessing container.

archyl-preflight

在开始编码之前运行，对照现有架构验证您计划采用的方案。Preflight 会将您的计划与 C4 模型、合规规则和近期的 ADR 进行比对，尽早发现违规。

示例提示词：

/archyl-preflight I'm planning to add a new Redis cache between the
API server and the database to reduce read latency.

/archyl-preflight We want to split the UserService into separate
authentication and profile services.

该技能会在您写下第一行代码之前，标记出依赖违规、命名冲突或与现有 ADR 相矛盾的方案等问题。

archyl-postship

在上线之后运行，自动更新您的架构文档。它会分析代码库中发生的变化，并：

• 更新 C4 模型（新的容器、组件、关系）
• 为重要决策创建 ADR
• 在需要时开启变更请求供团队审查

示例提示词：

/archyl-postship We just shipped the Redis caching layer.
Update the architecture to reflect the new cache container
and its relationships.

/archyl-postship Document the authentication service split
we shipped this sprint.

archyl-harness

在治理下编码的工作会话协议——也是 Archyl Harness 背后的技能。它教会您的代理完整的闭环：开始前调用 plan_work，调用 start_work_session 获取聚焦的上下文和建议性租约，使用 remember/recall 读写项目的知识图谱，最后调用 finish_work_session 提交一份可以开启架构变更请求的成果。

Work under the harness: plan, declare a session, respect the
guardrails, and finish with an honest summary.

审查与治理技能

archyl-review

结构化的架构审查机器人。它将 diff 与您的 C4 模型、合规规则和 ADR 进行比对，给出具备架构意识的代码审查意见。

示例提示词：

/archyl-review Review the current branch against the architecture.
Flag any conformance violations or undocumented dependencies.

/archyl-review Check if PR #42 introduces any new cross-system
dependencies that aren't in the C4 model.

archyl-changelog

生成架构变更日志——一条变更时间线，包括 ADR、发布、合规检查、漂移事件和模型更新。

示例提示词：

/archyl-changelog Show the architecture timeline for the last month.

/archyl-changelog What changed in the PaymentPlatform system
since the v2.0 release?

archyl-autofix

当检测到代码与架构文档之间出现漂移时，autofix 会提出具体的修复方案——修改代码或修改模型——使两者重新保持同步。

示例提示词：

/archyl-autofix We have drift on the PaymentService container.
Propose fixes to resolve it.

/archyl-autofix Show all current drift issues and suggest
the fastest path to zero drift.

智能分析技能

archyl-dora

将架构变更与 DORA 交付效能指标关联起来。了解架构决策如何影响部署频率、变更前置时间、变更失败率和平均恢复时间。

示例提示词：

/archyl-dora Show DORA metrics for the last quarter.
Did the microservice split improve deployment frequency?

/archyl-dora Correlate recent architecture changes
with our change failure rate trend.

archyl-roi

计算架构决策的财务影响。估算架构改进所节省的时间、避免的事故以及开发者生产力的变化。

示例提示词：

/archyl-roi What's the estimated ROI of our migration
from monolith to microservices?

/archyl-roi Calculate the cost of our current architectural
drift vs the cost of fixing it.

archyl-predict

在架构问题发生之前进行预测。基于历史趋势预测漂移、DORA 指标退化和复杂度热点。

示例提示词：

/archyl-predict Which components are most likely to drift
in the next 30 days?

/archyl-predict Based on current trends, will our deployment
frequency regress this quarter? Which services are at risk?

编排

archyl-orchestrate

协调在同一代码库上工作的多个代理。负责服务之间的 API 契约协商、依赖冲突的解决，并确保各代理不会做出相互冲突的架构变更。

示例提示词：

/archyl-orchestrate Two agents are modifying services that share
an API contract. Coordinate the changes to avoid conflicts.

/archyl-orchestrate Agent A is adding a new field to the
UserService API. Check if Agent B's PaymentService integration
will break.

在多代理环境中，不同代理负责不同的服务，需要在互不干扰的前提下协商共享契约，此时该技能尤其有用。

合规规则包

Archyl 为常见架构模式提供预置的合规规则包——微服务、事件驱动、分层架构等。这些规则包与上述所有技能配合使用，自动执行您的架构约束。

有关可用规则包以及如何创建自定义规则，请参阅合规规则指南。

SDK

如果您想在编程代理之外将 Archyl 集成到自定义工具中，我们提供 TypeScript、Python 和 Go 的 SDK。

有关 SDK 详情和 API 参考，请参阅 MCP 服务器文档。

工作原理

每个技能都为编程代理提供关于特定 Archyl MCP 工具的结构化知识，包括参数、预期值和最佳实践。当您要求代理执行架构任务时，它会：

1. 根据技能提供的知识，识别需要调用的 MCP 工具
2. 构造正确的参数（项目 ID、元素类型、关系类型）
3. 串联多个调用以完成复杂工作流
4. 返回已创建、修改或标记内容的摘要

代理始终会先调用 list_projects 来发现可用项目，并获取后续操作所需的 projectId。

C4 模型参考

这些技能理解 C4 模型的全部 4 个层级：

关系类型

连接元素时，代理会使用适当的关系类型：

贡献

这些技能是开源的。您可以通过以下方式贡献：

• 修复工具名称、参数或描述
• 为新的 Archyl 功能增加覆盖
• 改进工作流示例
• 为更多使用场景创建新的技能文件

详情请参阅贡献指南。