文件标准
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 文档
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
import { thing } from 'my-project';
thing.doSomething();
# Documentation Standards
## Core Principles
1. **Audience-First**: Write for your reader, not yourself
2. **Keep Current**: Outdated docs are worse than no docs
3. **Show, Don't Just Tell**: Use examples and diagrams
4. **Consistent Format**: Follow established patterns
## Hard Requirements (Writing)
- **No AI slop** - remove filler, keep docs concrete and task-oriented
- **No em dashes/en dashes** - use hyphens (`-`) instead
## Voice
Prefer neutral/imperative phrasing - avoid "you/your" in professional docs.
Canonical guidance: `rules/810-documentation.mdc`.
## Diataxis Quick Guide
Use one primary documentation mode per page:
- **Tutorial** - learning by doing
- **How-to guide** - task completion
- **Reference** - factual lookup
- **Explanation** - concepts and rationale
Canonical Diataxis guidance lives in `rules/810-documentation.mdc`. Keep this skill concise and link back to the rule instead of duplicating detailed standards.
## README Structure
```markdown
# Project Name
Brief description of what this project does.
## Features
- Feature 1
- Feature 2
## Installation
```bash
npm install my-project
```
## Quick Start
```javascript
import { thing } from 'my-project';
thing.doSomething();
```
## Documentation
Link to full docs.
## Contributing
Link to CONTRIBUTING.md.
## License
MIT - See LICENSE.
```
## Markdown Best Practices
### Headers
- Use `#` hierarchy (don't skip levels)
- Keep headers concise
- Use title case for headings, preserving established acronyms and product names
### Code Blocks
````markdown
```python
def hello():
print("Hello, World!")
```
````
### Lists
```markdown
- Unordered item
- Another item
- Nested item
1. Ordered item
2. Another item
```
### Links and References
```markdown
[Link text](https://acme.com)
[Reference link][1]
[1]: https://acme.com
```
### Tables
```markdown
| Header 1 | Header 2 |
|----------|----------|
| Cell 1 | Cell 2 |
```
## Interactive vs static diagrams
- **Static (Markdown):** Mermaid in this skill and in `rules/800-markdown.mdc`.
- **Interactive (React SPA):** `@xyflow/react` patterns, playbook, and rule **`rules/815-reactflow-diagrams.mdc`** - use skill **`skills/reactflow-architecture-diagrams/`**. See [references/static-vs-interactive.md](../reactflow-architecture-diagrams/references/static-vs-interactive.md) for a short comparison table.
## Mermaid Diagrams
### Flowchart
```mermaid
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
C --> E[End]
D --> E
```
### Sequence Diagram
```mermaid
sequenceDiagram
participant User
participant API
participant DB
User->>API: Request
API->>DB: Query
DB-->>API: Result
API-->>User: Response
```
### Architecture Diagram
```mermaid
graph LR
subgraph Frontend
A[React App]
end
subgraph Backend
B[API Gateway]
C[Service]
end
subgraph Data
D[(Database)]
end
A --> B
B --> C
C --> D
```
## Technical Writing Tips
1. **Use active voice**: "The function returns a value" not "A value is returned"
2. **Be concise**: Remove unnecessary words
3. **Define acronyms**: Spell out on first use
4. **Use present tense**: "The function adds" not "The function will add"
5. **Include examples**: Show, don't just tell
## Detailed References
- **React Flow (interactive canvases)**: See `skills/reactflow-architecture-diagrams/SKILL.md` and `rules/815-reactflow-diagrams.mdc`
- **Markdown & Mermaid**: See [references/markdown-mermaid.md](references/markdown-mermaid.md)
- **Technical Writing**: See [references/technical-writing.md](references/technical-writing.md)
- **Open Source**: See [references/open-source.md](references/open-source.md)
---
> Source: [d-padmanabhan/agent-engineering-handbook](https://github.com/d-padmanabhan/agent-engineering-handbook) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
核心原则
硬性要求(写作)
Diataxis 快速指南
自述文件结构
标头
文件/命令 -> rules/810-documentation.mdc · rules/800-markdown.mdc · @xyflow/react · rules/815-reactflow-diagrams.mdc · skills/reactflow-architecture-diagrams/ · skills/reactflow-architecture-diagrams/SKILL.md
内容校验值 -> 8c24e5053a1e
当前原文的自动摘译,尚未人工审校。
核心原则
受众至上:为读者而不是自己而写作 保持最新:过时的文档比没有文档更糟糕 显示,不要只是讲述:使用示例和图表 一致的格式:遵循既定模式
硬性要求(写作)
无 AI 溢出 - 删除填充物,保持文档具体且以任务为导向 无长破折号/短破折号 - 使用连字符 (
-) 代替Diataxis 快速指南
每页使用一种主要文档模式: 教程 - 边做边学 操作指南 - 任务完成 参考 - 事实查找 解释 - 概念和基本原理
标头
使用
#层次结构(不要跳过级别) 保持标题简洁 标题使用标题大小写,保留已建立的首字母缩略词和产品名称