# maisongr-skills 中文文档

规范地址：https://npmcn.com/package/maisongr-skills/

版本：1\.2\.0
npm 元数据更新时间：2026-11-04T00:29:05.181Z
中文译文更新时间：2026-11-04T03:08:04.260Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/maisongr-skills
原文对照：https://npmcn.com/package/maisongr-skills/?lang=original
项目主页：https://github.com/maison-gr/maisongr-ai-engineering-skills#readme
源码仓库：https://github.com/maison-gr/maisongr-ai-engineering-skills

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：84.2 kB，18 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.3
- 运行依赖：0 个
- 首次发布：2026-11-03T00:04:36.787Z
- 最新版本发布：2026-11-04T00:29:04.833Z
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

AI编码代理的工程学科：Claude Code， Codex, Cursor， GitHub Copilot和Gemini CLI的七大原则和十项技能。

## 安装

```sh
npm install maisongr-skills
```

也可以使用：`pnpm add maisongr-skills`、`yarn add maisongr-skills`、`bun add maisongr-skills`

## README

![Maison GR AI Engineering Skills: seven principles and ten skills for AI coding agents](https://raw.githubusercontent.com/maison-gr/maisongr-ai-engineering-skills/main/.github/social-preview.png)

# 每个AI编码代理都有一个工程标准

在猜测之前提问的特工，只会改变你的提问，  
告诉你他们到底做了什么 _不_ 核实。

Claude Code·OpenAI Codex·Cursor·GitHub Copilot·Gemini CLI

[![Validate](https://github.com/maison-gr/maisongr-ai-engineering-skills/actions/workflows/validate.yml/badge.svg)](https://github.com/maison-gr/maisongr-ai-engineering-skills/actions/workflows/validate.yml) [![npm version](https://img.shields.io/npm/v/maisongr-skills.svg)](https://www.npmjs.com/package/maisongr-skills) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/maisongr-skills/LICENSE)

```bash
npx maisongr-skills
```

* * *

## 为什么会这样？

AI编码代理很少会因为缺乏知识而失败。他们之所以失败，是因为完成任务比把它做好更难。所以他们:

-   猜猜你不是问是什么意思；
-   构建任务不需要的抽象和选项；
-   “改进”无人提及的文件；
-   报告“所有测试通过”而不运行它们；
-   推送、删除一个列或者在没有人要求的时候破坏一个公共API。

当你的团队使用三种不同的代理时，你会得到三种不同的标准，或者没有。

Maison GR为每个代理提供了相同的七个原则和十个任务方法，来自一个源文件，安装一个命令。

## 60秒

1.  在任何项目中，运行 `npx maisongr-skills`。
2.  向你的代理人要求一些稍微模棱两可的东西： _“向用户端点添加缓存。”_
3.  它不是猜测，而是询问要缓存什么以及缓存多长时间，或者陈述它所做的假设。
4.  当它完成时，它报告它做了什么和不能检查什么。例如:

```text
Changed:      src/api/users.ts: added a 60 s cache to GET /users
Verified:     npm test (42 passed), npm run lint (clean)
Not verified: cache invalidation under concurrent writes (no integration environment)
Decisions:    chose in-memory over Redis; revisit if you run more than one instance
```

任何时候都可以撤销它 `npx maisongr-skills remove`。

## 收据：“测试通过”你可以检查

代理可以写“已验证： `npm test` （42通过）“没有跑任何东西。”安装了Claude Code插件后，Maison GR检查。

-   代理在会话中运行的每个shell命令都将被记录下来，并附带其退出代码。
-   当代理尝试完成时，下面列出的每个命令 **验证** 与那个记录核对。
-   如果一个命令从未运行过，或者它的最后一次运行失败，而报告说它通过了，那么将发送代理返回运行它并报告实际结果，或者将它移动到 **不验证**。

```text
Maison GR receipts: your report lists commands under "Verified" that this session's record does not support:
- `npm test`: no command like this ran in this session.
Run them now and report the real result, or move them to "Not verified" with the reason.
```

同样的记录捕捉到了 **悄悄采取的防御行动** (见原则7； _保护不可逆动作_）. 如果会话是强制推送的，跳过Git钩子 `--no-verify`我把一切都安排好了 `git add -A`，改写历史（修改，重置，重置） `--hard`)，或者更改了Git配置，并且报告永远不会提到它，代理将被发送回拥有并证明操作的正确性-或者撤消操作。

```text
Maison GR receipts: this session took a guarded action without owning it in the report:
- this session force-pushed (`git push --force origin fix/foo`) but your report never mentions it.
Each is allowed only if the user asked for it here. Say so and justify it in your report, or undo it.
```

它只检查反引号中的命令名（以及上面的Git操作），不会连续阻塞两次，并将其记录保存在您的机器上，保存在Claude Code的插件数据文件夹中。收据需要 [Claude Code插件](https://npmcn.com/package/maisongr-skills/#readme-install);其他代理无需检查即可获得相同的报告格式。

## 它是如何工作的

```mermaid
flowchart LR
    N["npx maisongr-skills"] ==> A
    A["AGENTS.md<br/>7 principles, always on"] --> C[Claude Code]
    A --> X[Codex]
    A --> U[Cursor]
    A --> P[Copilot]
    A --> G[Gemini CLI]
    S["10 skills<br/>loaded on demand"] -.-> C & X & U & P & G
```

-   **原则** 简短的、永远在线的指令在吗 `AGENTS.md`，大多数代理已经读取了该文件。大约6 KB。
-   **技能** 代理是否只在任务匹配时加载详细方法 [代理技能](https://agentskills.io/specification) 格式。
-   **子代理** （Claude Code和Gemini CLI）在它们自己的上下文中运行审查、设计和测试。

安装程序在每个代理本机查找的地方编写每个部分。它将原则添加到您现有的标记块上 `AGENTS.md`，在以后的运行中只更新该块，并只删除它添加的块。

## 的原则

| ＃ | 原则 | 防止 |
| --- | --- | --- |
| 1 | **实施前先了解** | 正确地构建错误的东西 |
| 2 | **简单第一** | 拥有成本高于价值的代码 |
| 3 | **外科手术改变** | 未修改代码中不可审查的差异和回归 |
| 4 | **目标驱动执行** | 写完代码就结束的工作，而不是实现目标的工作 |
| 5 | **竣工前验证** | 对未经测试的工作有信心的报告 |
| 六 | **默认是安全的** | 有效代码中的漏洞 |
| 七 | **保护不可逆动作** | 其他编辑无法撤销的伤害 |

每个任务都遵循相同的循环：

```mermaid
flowchart LR
    I[Inspect] --> Q[Clarify] --> P[Plan] --> M[Implement] --> V[Verify] --> R[Report]
    Q -- ambiguous --> Ask((Ask you))
    V -- fails --> M
```

[每个原则背后的推理](https://npmcn.com/package/maisongr-skills/docs/principles.md) · [每一个都在一个现实的场景中](https://npmcn.com/package/maisongr-skills/EXAMPLES.md)

## 的技能

| 技能 | 用它来 |
| --- | --- |
| [`maisongr-engineering`](https://npmcn.com/package/maisongr-skills/skills/maisongr-engineering/SKILL.md) | 携带从请求到验证结果的任何重要更改 |
| [`maisongr-architecture`](https://npmcn.com/package/maisongr-skills/skills/maisongr-architecture/SKILL.md) | 设计决策，新模块或依赖项，决策记录 |
| [`maisongr-code-review`](https://npmcn.com/package/maisongr-skills/skills/maisongr-code-review/SKILL.md) | 审查diff或pull请求，根据严重性对结果进行排序 |
| [`maisongr-debugging`](https://npmcn.com/package/maisongr-skills/skills/maisongr-debugging/SKILL.md) | 重现失败，找到根本原因，证明解决办法 |
| [`maisongr-testing`](https://npmcn.com/package/maisongr-skills/skills/maisongr-testing/SKILL.md) | 在适当的水平上进行有意义的测试，证明可能会失败 |
| [`maisongr-security-review`](https://npmcn.com/package/maisongr-skills/skills/maisongr-security-review/SKILL.md) | 威胁建模、访问控制、注入、秘密、依赖 |
| [`maisongr-documentation`](https://npmcn.com/package/maisongr-skills/skills/maisongr-documentation/SKILL.md) | 准确的，经过验证的readme，指南，参考文献和操作手册 |
| [`maisongr-database`](https://npmcn.com/package/maisongr-skills/skills/maisongr-database/SKILL.md) | 安全迁移、完整性约束、正确和快速查询 |
| [`maisongr-api`](https://npmcn.com/package/maisongr-skills/skills/maisongr-api/SKILL.md) | API契约、验证、一致错误、兼容进化 |
| [`maisongr-frontend`](https://npmcn.com/package/maisongr-skills/skills/maisongr-frontend/SKILL.md) | 可访问（WCAG 2.2 AA），响应迅速，完成界面 |

当有匹配的请求时，代理会选择相应的技能。 _“用户说CSV导入会删除行”_ 负载 `maisongr-debugging`：重现，找到根本原因，修复，添加回归测试。直接呼叫： `/maisongr:maisongr-security-review` 在《克劳德法典》中， `$maisongr-security-review` 在法典。

## 安装

**任何特工，一个命令** （Node.js 18.3或更高版本），从项目的根目录：

```bash
npx maisongr-skills                       # all five agents
npx maisongr-skills --agent codex,cursor  # only some: claude, codex, cursor, copilot, gemini
npx maisongr-skills --global              # your user account, every project
npx maisongr-skills --dry-run             # show what would change
npx maisongr-skills remove                # undo
```

提交结果，这样你的整个团队和每个经纪人都能以同样的标准工作。

**Claude Code插件**，克劳德代码内部：

```text
/plugin marketplace add maison-gr/maisongr-ai-engineering-skills
/plugin install maisongr@maison-gr
```

**Gemini CLI扩展：**

```bash
gemini extensions install https://github.com/maison-gr/maisongr-ai-engineering-skills
```

插件和扩展安装技能和子代理；对于Claude Code中的always-on原则，也可以运行 `npx maisongr-skills --agent claude` 或添加 `@AGENTS.md` 到你的 `CLAUDE.md`。这个 [安装指南](https://npmcn.com/package/maisongr-skills/docs/installation.md) 涵盖项目和用户范围，手动复制，更新和删除每个平台。

## 让它成为你的

-   **添加项目的细节。** 把你的命令、约定和界限放在Maison GR块下面 `AGENTS.md`，从…开始 [`templates/project-instructions.md`](https://npmcn.com/package/maisongr-skills/templates/project-instructions.md)． 具体指示优先于一般原则。
-   **计划更大的改变。** 请代理代为填写 [`templates/implementation-plan.md`](https://npmcn.com/package/maisongr-skills/templates/implementation-plan.md) 等待你的批准。
-   **选择你的技能。** 每个技能文件夹都是独立的；只保留团队需要的。

## 探员还是搞错了吗？

如果安装了Maison GR的代理仍然猜测、过度构建、触摸它不应该拥有的文件，或者要求进行它从未进行过的检查， [把成绩单发给我们](https://github.com/maison-gr/maisongr-ai-engineering-skills/issues/new?template=agent-failure-report.md)． 每个报告都成为下一个版本的测试用例。

要贡献一个修复、一项技能或一个新平台，请阅读 [贡献](https://npmcn.com/package/maisongr-skills/CONTRIBUTING.md)． 仓库是如何构建的： [体系结构](https://npmcn.com/package/maisongr-skills/docs/architecture.md)。

## 学分

Maison GR从 [andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) 以及LLM编码代理的四项原则。它增加了验证、安全性和不可逆操作的原则、十项任务技能、子代理、一个用于五个平台的生成源和一个安装程序。 [RESEARCH.md](https://npmcn.com/package/maisongr-skills/RESEARCH.md) 列出每一个项目和文件，告知设计。

## 进一步的阅读

[原则](https://npmcn.com/package/maisongr-skills/docs/principles.md) · [例子](https://npmcn.com/package/maisongr-skills/EXAMPLES.md) · [安装](https://npmcn.com/package/maisongr-skills/docs/installation.md) · [兼容性](https://npmcn.com/package/maisongr-skills/docs/compatibility.md) · [常见问题解答](https://npmcn.com/package/maisongr-skills/docs/faq.md) · [体系结构](https://npmcn.com/package/maisongr-skills/docs/architecture.md) · [更新日志](https://npmcn.com/package/maisongr-skills/CHANGELOG.md)

## 许可证

[麻省理工学院](https://npmcn.com/package/maisongr-skills/LICENSE) ©Maison GR

## 常见问题

### maisongr-skills 是什么？

AI编码代理的工程学科：Claude Code， Codex, Cursor， GitHub Copilot和Gemini CLI的七大原则和十项技能。

### 如何安装 maisongr-skills？

在项目目录运行 npm install maisongr-skills，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 maisongr-skills，可以用 npx maisongr-skills 直接运行。

### maisongr-skills 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/maisongr-skills 是否存在。

### maisongr-skills 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.3。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### maisongr-skills 可以商用吗？

maisongr-skills 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### maisongr-skills 还在维护吗？

最新版本 1\.2\.0 发布于 2026/11/04（1 天前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/11/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。