降价作家

文档 社区

技能解读

当前原文的自动摘译,尚未人工审校。

何时加载此技能

在执行以下操作时加载此技能: 创建或编辑任何 *.md 文件 编写文档更改(自述文件、指南、设计文档) 在 .github/decisions/ 中创建或更新 ADR 维护存储库上下文文件,例如 AGENTS.md、llms.txt 或 copilot-instructions.md

要求(必须具备)

在此存储库中编写或编辑 Markdown 的代理必须满足以下所有条件:

R1——语言和持久性

所有提交的 Markdown 都必须是英文。除非明确说明日期,否则避免使用时间敏感的措辞(“今天/现在”)。

R2——文档结构

恰好一个顶级标题:单个# ...标题。标题是分层且有序的:#→##→###(无跳过级别)。标题是唯一的(避免可能破坏锚点的重复)。

R3 — 链接

首选存储库文件的相对链接。不要引入损坏的链接;如果您添加/更改链接,请验证工作区中是否存在目标。使用 / 作为路径分隔符(切勿使用 \)。使用描述性链接文本(避免转储原始 URL,除非 URL 本身就是引用)。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
文档
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# SKILL: Markdown Writer

> Purpose: help agents reliably author and review Markdown with correct structure, links, and minimal ambiguity.
> This skill is intended to be used by any agent that creates/edits/reviews `.md` content.

## When to Load This Skill

Load this skill when you:

- Create or edit any `*.md` file
- Write documentation changes (README, guides, design docs)
- Create or update ADRs in `.github/decisions/`
- Maintain repo context files such as `AGENTS.md`, `llms.txt`, or `copilot-instructions.md`
- Create or update `SKILL.md` packages or `.agent.md` prompts (Markdown structure still applies)
- Review documentation as a critic (links, headings, formatting)

---

## Requirements (Must-Haves)

Agents writing or editing Markdown in this repo must satisfy all of the following:

### R1 — Language and permanence

- All committed Markdown must be **English**.
- Avoid time-sensitive phrasing (“today/now”) unless a date is explicitly stated.

### R2 — Document structure

- Exactly one top-level title: a single `# ...` heading.
- Headings are hierarchical and ordered: `#` → `##` → `###` (no skipped levels).
- Headings are unique (avoid duplicates that may break anchors).

### R3 — Links

- Prefer **relative links** for repo files.
- Do not introduce broken links; if you add/change a link, verify the target exists in the workspace.
- Use `/` as a path separator (never `\`).
- Use descriptive link text (avoid dumping raw URLs unless the URL itself is the reference).

### R4 — Anchors

- Avoid deep anchor links unless the section is stable.
- Keep heading titles simple to reduce renderer-specific anchor differences.

### R5 — Code blocks

- Fenced code blocks must be balanced (opening/closing fences match).
- Add a language tag when possible (e.g. `yaml`, `json`, `bash`, `text`).

### R6 — Frontmatter

- Only use YAML frontmatter when the file format expects it.
- If frontmatter exists, it must be valid YAML wrapped in `---` lines.

### R7 — Safety and hygiene

- Do not include secrets, tokens, credentials, or sensitive logs.
- Keep edits minimal: do not rewrite unrelated sections.

### R8 — Lists and readability

- Use `-` for unordered lists.
- Keep bullets short and scannable; avoid deep nesting unless it improves clarity.

### R9 — Tables

- Prefer tables only when they improve comparison; avoid very wide tables (use bullets instead).

---

## Common Markdown Pitfalls (Avoid)

- Broken relative links after renames/moves (always re-check targets).
- Inconsistent heading casing that creates near-duplicates (hurts search and navigation).
- Over-wide tables (hard to read in GitHub; prefer bullets if the table exceeds typical width).
- Copy-pasted logs containing secrets, tokens, or internal URLs.

## Templates (Use When Applicable)

### Documentation page template

```markdown
# <Title>

## Purpose
<What this document is for, in 1–3 sentences>

## Audience
<Who should read this>

## Workflow / Process
1. <Step>
2. <Step>

## References
- <links>
```

### ADR template (minimal)

```markdown
# ADR-XXXX — <Title>

## Status
Proposed | Accepted | Superseded by ADR-YYYY

## Context
<Why we needed to decide>

## Decision
<What we decided, one sentence>

## Consequences
<What changes; what becomes easier/harder>
```

---

## Review Checklist (For Critics and Self-Review)

- [ ] One `#` title at top; headings are unique and ordered.
- [ ] No broken links to repo files; link paths use `/`.
- [ ] Fenced code blocks are balanced; language tags are present where relevant.
- [ ] The doc is skimmable: short sections, short bullets, minimal redundancy.
- [ ] No secrets, tokens, or sensitive logs embedded.
- [ ] Changes are minimal and do not rewrite unrelated sections.

---

## Standard Checks (Optional, Recommended)

Use these when you want a repeatable “doc QA” pass. If the repo does not have these tools configured, treat this section as guidance (do a manual check instead).

- **Markdown lint**: catch common Markdown style issues (headings, fences, spacing).
- **Spell check**: catch typos and inconsistent terminology (especially in headings).
- **Link check**: validate external URLs (best-effort) and internal relative links.

Suggested tooling (choose one set; do not require all):

- `markdownlint-cli2` (Markdown lint)
- `cspell` (spell check)
- `lychee` (link check)

Minimum manual equivalent if you cannot run tools:

- Re-scan headings: one `#`, no skipped levels, no duplicates.
- Re-scan all new/edited links: open targets; fix path separators and casing.
- Re-scan code fences: ensure opening/closing fences match; add language tags.

---

## References

- Agent file and repo context standards: `framework/spec/appendices/01-appendix-a1-ai-and-llm-standards.md` (A1.1)
- VS Code Copilot customization overview: https://code.visualstudio.com/docs/copilot/customization/overview

---
> Source: [AlexandrSurkov/ForgentFramework](https://github.com/AlexandrSurkov/ForgentFramework) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。