评论区

效率工具 社区

技能解读

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

产地

作者:Carlos Fachini 来源:https://github.com/carlosfachini/comment-block-skill 许可证:MIT

操作模式

辅助模式,默认:分析活动文件、差异、选择或周围代码。建议类型、标题、正文、日期、可选作者和插入位置。编辑前要求确认。手动模式:当用户说comment-block manual或use comment-block manual时,仅询问缺少的标题和正文。使用FEATURE,除非用户提供或明确暗示其他类型。快速模式:当用户写入comment-block: Title | Body时,将左侧解析为标题,右侧解析为正文。仅当插入位置不明确或存在风险时才进行确认。

评论数据

type:FEATURE、SECTION、LOGIC、TODO、BUGFIX、REFACTOR、NOTE之一。默认type:FEATURE。清晰时从措辞推断类型。示例:“修复”-> BUGFIX、“重构”-> REFACTOR、“待办事项”-> TODO、“注释”-> NOTE、“逻辑”-> LOGIC、“部分”-> SECTION。 title:简洁,插入块中大写。 date:YYYY-MM-DD中的当前本地日期。

协助确认

在辅助模式下编辑前,显示:确认后才继续。如果用户已经提供了准确的内容和明确的位置,则简短的确认就足够了。

安置规则

在正在记录的完整功能、部分、声明、选择器、组件、路由、函数、类、块或模板节点之前插入。如果用户要求包装某个区域并且语法支持该区域后的注释,请在整个区域后放置匹配的结束注释。否则,请使用在区域之前包含 [START: TYPE] 和 [END: TYPE] 的首选单块格式。

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

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

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

# Comment Block

Insert structured, visually framed comments directly into user code around a complete feature, section, or logical block.

## Origin

- Author: Carlos Fachini
- Source: https://github.com/carlosfachini/comment-block-skill
- License: MIT

## Operating Modes

- **Assisted mode, default:** analyze the active file, diff, selection, or surrounding code. Propose type, title, body, date, optional author, and insertion location. Ask for confirmation before editing.
- **Manual mode:** when the user says `comment-block manual` or `use comment-block manual`, ask only for missing title and body. Use `FEATURE` unless the user provides or clearly implies another type.
- **Quick mode:** when the user writes `comment-block: Title | Body`, parse the left side as title and the right side as body. Confirm only when the insertion location is ambiguous or risky.
- **Config mode:** when the user says `comment-block config`, explain optional settings: default author, default type, confirmation behavior, and language detection preferences. Do not edit code unless asked.

## Comment Data

- `type`: one of `FEATURE`, `SECTION`, `LOGIC`, `TODO`, `BUGFIX`, `REFACTOR`, `NOTE`.
- Default `type`: `FEATURE`.
- Infer type from wording when clear. Examples: "fix" -> `BUGFIX`, "refactor" -> `REFACTOR`, "todo" -> `TODO`, "note" -> `NOTE`, "logic" -> `LOGIC`, "section" -> `SECTION`.
- `title`: concise, uppercased in the inserted block.
- `date`: current local date in `YYYY-MM-DD`.
- `author`: optional. Include only when configured or explicitly requested, such as "with author Carlos".
- `body`: one or more clear sentences describing why the block exists.

## Assisted Confirmation

Before editing in assisted mode, show:

```text
Suggestion:
Type: FEATURE
Title: Final Price Calculation
Body: Centralizes subtotal, discount, and total rules displayed in the summary.
Date: 2026-04-24
Location: before the PriceSummary component.

Apply?
```

Proceed only after confirmation. If the user already supplied exact content and an unambiguous location, a brief confirmation is enough.

## Placement Rules

- Insert before the complete feature, section, declaration, selector, component, route, function, class, block, or template node being documented.
- If the user asks for wrapping a region and the syntax supports comments after the region, place a matching end comment after the complete region. Otherwise use the preferred single block format that contains both `[START: TYPE]` and `[END: TYPE]` before the region.
- Never insert inside string literals, template literal content, JSX prop lists, tag attributes, object keys, import/export clauses, decorators, or partially selected syntax.
- Do not comment strict `.json`. Only comment JSON-like files when they are JSONC, JSON5, VS Code settings, or another comments-enabled format.
- In mixed PHP files, choose syntax from the current region: PHP code uses `/* */`; HTML/template regions use `<!-- -->`.
- Ask for clarification when multiple plausible blocks match the request or when the only possible insertion point may break syntax.

## Syntax Selection

Use the smallest valid comment wrapper for the current language context. Inside that wrapper, always use the Comment Block visual frame:

- A `[START: TYPE]` line.
- A full-width `#` border line.
- Metadata and body lines wrapped with `||` side rails.
- A full-width `#` border line.
- An `[END: TYPE]` line.

Prefer a readable fixed frame width around 72 characters when practical. Pad `||` lines with spaces so the closing `||` aligns. If content is longer than the frame width, wrap it across multiple `||` lines instead of widening the frame excessively.

### HTML And Vue Templates

```html
<!-- [START: FEATURE]
########################################################################
|| Title: HERO SECTION                                                ||
|| Date: 2026-04-24                                                   ||
||                                                                    ||
|| Defines the main visible landing section.                          ||
########################################################################
[END: FEATURE] -->
<section>...</section>
```

### React JSX And TSX

Use JSX block comments outside prop lists and inside JSX expression braces:

```tsx
{/* [START: FEATURE]
########################################################################
|| Title: FINAL PRICE CALCULATION                                     ||
|| Date: 2026-04-24                                                   ||
||                                                                    ||
|| Centralizes subtotal, discount, and total rules.                   ||
########################################################################
[END: FEATURE] */}
<PriceSummary />
```

In normal JavaScript or TypeScript regions of a JSX/TSX file, use `/* */`.

### JavaScript, TypeScript, CSS, PHP Code, JSONC

```js
/* [START: FEATURE]
########################################################################
|| Title: FINAL PRICE CALCULATION                                     ||
|| Date: 2026-04-24                                                   ||
||                                                                    ||
|| Centralizes subtotal, discount, and total rules.                   ||
########################################################################
[END: FEATURE] */
```

### Python, Shell, Ruby

```python
# [START: FEATURE]
# ######################################################################
# || Title: FINAL PRICE CALCULATION                                   ||
# || Date: 2026-04-24                                                 ||
# ||                                                                  ||
# || Centralizes subtotal, discount, and total rules.                 ||
# ######################################################################
# [END: FEATURE]
```

## Formatting Rules

- Preserve surrounding indentation.
- Add exactly one empty `||                                                                    ||` rail line between metadata and body.
- Add `Author: ...` immediately after `Date: ...` when author is included.
- Keep title uppercase in the inserted block.
- Always include the visual `#` border and `||` side rails.
- Prefer ASCII punctuation unless the surrounding file already uses a different convention.

---
> Source: [carlosfachini/comment-block-skill](https://github.com/carlosfachini/comment-block-skill) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->

讨论

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