convez.ai
Skill
veawho

via54Skills

veawho/via54Skills

Ver no GitHub
InicialPluginScore · de 0 a 100

Personal Hermes Agent / Claude / OpenClaw / OpenCode / Codex skills by veawho. Naming: via54<lowercase-action>. Bilingual README (中文默认 + English).

Instalação

$npx convez-ai veawho/via54Skills

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 meses
Versão
—
Issues abertas
1
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

via54Skills

🌐 语言 / Language: 中文(默认 · you are here) · English →

veawho (Devin Wei) 个人写的 Hermes Agent / Claude / OpenClaw / OpenCode / Codex 通用 Skills 仓库。 Personal Skills repository by veawho (Devin Wei), cross-compatible with Hermes Agent, Claude Code, OpenClaw, OpenCode, and Codex CLI.


📑 目录 / Table of Contents


默认规则 / Default Rules

以下规则写入仓库的硬性默认。违反任何一条的 PR 不会被合入。

  1. 命名 / Naming: via54<lowercase-action>。Hermes 的 name 字段 regex ^[a-z0-9][a-z0-9._-]*$ 强制小写,Claude/OpenClaw/OpenCode/Codex 的 regex ^[a-z0-9]+(-[a-z0-9]+)*$ 也只允许小写 + 单连字符。所以全小写、无下划线、无点、无连字符是最大公约数。

  2. 双语 README / Bilingual READMEs: 所有顶层文档 (README.md、AGENTS.md、CONTRIBUTING.md) 必须中英双语。中文是作者的母语阅读语言,英文是给国际读者和工具的。

  3. README.md 是默认页,README.en.md 是纯英文版。两个文件顶部必须有 🌐 Language / 语言 互相链接的 banner。默认页必须包含切到英文版的链接,英文版必须包含返回中文版的链接。

  4. SKILL.md 中文注释 / Chinese Annotations in SKILL.md: 重要段落(决策矩阵、pitfalls、铁律、verification checklist)必须紧跟一段 > **中文注释**: ...。代码块、命令行、文件路径、JSON key 保持英文。

  5. Frontmatter 兼容性 / Frontmatter Compatibility: 必填字段必须满足所有支持工具的 regex,见下表。

  6. Live 铁律 / Live Iron Rule: skill 的每条结论必须有 ps / lsof / curl / find / 真启动至少 2 种 live tool 输出支持。禁止靠 backup manifest 或历史推断。这条铁律写在所有 skill 的 Common Pitfalls 第一条。

  7. README.en.md 是技术英语而非翻译 / Technical English in README.en.md: 这个文件不是中译英。必须使用软件工程标准英语——RFC 2119 关键词 (MUST, SHOULD, MAY),CommonMark / GFM 规范,以及被引用工具自身的术语 (SKILL.md, frontmatter, metadata, name, regex, validator)。从英语角度直接表述规则,不要镜像中文句式。


命名规范 / Naming Convention

via54<lowercase-action> — 每个 skill 必须 via54 前缀,小写,简洁。

例子 / Examples

Skill含义 / Meaning命名边界 / Naming pattern
via54mergevenv / service / 二进制合并单动作 / single verb
via54goportPython → Go 改写动词+宾语 / verb + object
via54deploy(未来) 部署短动词 / short verb
via54backuprotate(未来) 备份轮转复合动作(允许)/ compound (allowed)
via54Merge❌ 拒:camelCase 不通过 Hermes regex
via54_merge❌ 拒:下划线被 Claude/OpenCode/OpenClaw regex 拒
via54.merge❌ 拒:点被 Claude/OpenCode/OpenClaw regex 拒

中文注释: 选小写是因为 Hermes validator 拒 camelCase,Claude/OpenClaw/OpenCode/Codex 4 个工具的 regex 也都只接受 ^[a-z0-9]+(-[a-z0-9]+)*$。如果未来某个工具放宽,我们再讨论是否切到 camelCase。今天:全小写,无分隔符。

目录即名字 / Directory = Name

  • Skill 目录 = skill 名:via54merge/SKILL.md,via54goport/SKILL.md
  • SKILL.md frontmatter 的 name 字段必须 = 目录名
  • 所有 skill 都放仓库根目录(没有 category 子目录,这个仓库本身就是单一 namespace)

GitHub Markdown 规范 / GitHub Markdown Spec

两个 README 必须符合 GitHub Flavored Markdown (GFM) 才能在 github.com 正确渲染。

GFM 强制规则 / GFM Rules We Enforce

  1. 每个文件一个 # 标题(文件标题)。其余章节标题用 ## 、### 等。
  2. 围栏代码块用三反引号(```)。总是带语言标签(bash、yaml、python 等)用于语法高亮。
  3. GFM 表格用 | 分隔 + --- 对齐行。保持列数一致。
  4. 相对链接用于仓库内导航([text](README.en.md)、[text](via54merge/SKILL.md))。GitHub 自动解析到 blob/main/...。
  5. 允许的 HTML:只有 GFM 安全标签(details、summary、kbd、sub、sup、img、br 等)。禁止: <script>、<style>、<iframe>、inline CSS、class / id 属性。
  6. 行长度: GFM 不强制,但散文行保持 ≤200 字符以保留 diff 可读性。
  7. 无尾随空格。无连续空行 (连续 >2 空行禁止)。
  8. Tab:markdown 散文里禁止(嵌套列表用 2 或 4 空格)。

验证 / Validation

# 轻量 GFM lint (自定义检查 — 没有通用工具)
python3 << 'PYEOF'
import re, pathlib
for p in [pathlib.Path('README.md'), pathlib.Path('README.en.md')]:
    txt = p.read_text()
    no_code = re.sub(r'```.*?```', '', txt, flags=re.DOTALL)
    h1 = len(re.findall(r'^# [^\n]+', no_code, re.MULTILINE))
    assert h1 == 1, f'{p}: {h1} H1 headings (want 1)'
    assert '\t' not in txt, f'{p}: contains tabs'
    assert not re.search(r'\n\n\n+', txt), f'{p}: consecutive blank lines'
    print(f'  ✓ {p}')
PYEOF

兼容性 / Compatibility

现状: SKILL.md 是 Anthropic 2025-12-18 发布的 Agent Skills 开放标准。Claude Code / Hermes Agent / OpenClaw / OpenCode / Codex CLI 全部兼容。

各工具的字段约束(实测 / 文档)

字段 / FieldHermesClaude CodeOpenClawOpenCodeCodex CLI
name (必填)^[a-z0-9][a-z0-9._-]*$ ≤64^[a-z0-9]+(-[a-z0-9]+)*$ ≤64同 Claude同 Claude同 Claude
description (必填)≤1024≤1024≤1024≤1024≤1024
licenseoptionaloptionaloptionaloptionaloptional
compatibility忽略optionaloptionaloptionaloptional
metadatametadata.hermes.{tags,related_skills} 嵌套flat string→stringflatflatflat
when_to_use不支持optionaloptionaloptionaloptional
allowed-tools不支持实验性实验性不支持不支持

我们的标准 frontmatter 模板 / Our Standard Template

---
name: via54xxx                  # 必填,小写,匹配目录名
description: Use when ...       # 必填,≤1024,以 "Use when" 开头,带 trigger 关键词
license: MIT                    # 可选,但建议填
compatibility: Designed for Claude Code, Hermes Agent, OpenClaw, OpenCode, Codex CLI. macOS / Linux. Requires ...
metadata:                       # 可选,flat string→string,跨工具识别
  author: veawho
  version: 1.0.0
  audience: developers
  tags: keyword1 keyword2 ...    # 空格分隔的 keyword,所有工具都识别
  hermes:                       # Hermes 特有:嵌套结构,其他工具忽略未知字段不影响
    tags: [keyword1, keyword2, ...]   # 数组形式,Hermes 偏好
    related_skills: [via54goport, ...]
---

验证脚本 / Validation

每个 skill 必须在 push 前通过以下检查:

# 1. Hermes validator
~/.hermes/hermes-agent/venv/bin/python3 -c "
import sys; sys.path.insert(0, '$HOME/.hermes/hermes-agent')
from tools.skill_manager_tool import _validate_frontmatter
import pathlib
_validate_frontmatter(pathlib.Path('via54xxx/SKILL.md').read_text())
print('✓ Hermes OK')
"

# 2. Claude/OpenCode/OpenClaw/Codex name regex
python3 -c "
import re; import yaml; import pathlib
content = pathlib.Path('via54xxx/SKILL.md').read_text()
m = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
name = yaml.safe_load(m.group(1))['name']
assert re.match(r'^[a-z0-9]+(-[a-z0-9]+)*$', name), f'Claude regex fail: {name}'
print('✓ Claude/OpenCode/OpenClaw/Codex OK')
"

双语策略 / Bilingual Strategy

目标: 中文是作者的母语阅读语言,英文是国际通用 + 让 Claude/OpenClaw 等英文 AI 工具更好理解 metadata。

规则 / Rules

  1. README.md / AGENTS.md / CONTRIBUTING.md: 顶部放中文(完整版本),下面紧跟 English version(等价内容,不一定逐字)。中文在前是用户偏好,不是质量判断。
  2. README.en.md: 纯英文原生文档,不是翻译。遵循 RFC 2119 关键词 (MUST, SHOULD, MAY),使用被引用工具自身的术语 (SKILL.md, frontmatter, metadata, validator)。
  3. 语言切换 banner 每个 README 顶部都要有:
    > **🌐 Language / 语言**: [← 中文(默认)](README.md) · **English**(you are here)
    
  4. SKILL.md body: 不需要逐段双语——这是技术文档,中文注释足够了。规则:
    • 每个 ## 大段落开头(Overview / When to Use / Decision Matrix / Pitfalls / Verification):在第一段 > 引用块里用 **中文摘要** (Chinese Summary): ... 给一段中文摘要
    • 关键表格 / 决策 / pitfall / iron rule 之后:跟一段 > **中文注释**: ...
    • 代码块、命令行、文件路径保持英文(这些是机器可读的,翻译反而错)
  5. Frontmatter description: 保持英文。原因:description 是 trigger 字段,英文 AI 工具的触发匹配更好。中文会大幅降低英文 AI 工具的识别率。
  6. Frontmatter metadata.tags: 保持英文(空格分隔),同 description 原因。
  7. Commit messages: 英文。GitHub 是英文主导,中文 commit message 难搜。

双语示例 / Bilingual Example

# via54merge — Consolidate Duplicated Python Runtimes, Services & Binaries

> **中文摘要** (Chinese Summary): 本技能用于在 macOS / Linux 开发机上合并重复的 Python venv...

## Overview

When you have multiple Python venvs serving overlapping purposes...

> **中文注释**: 不要为了合并而合并。每次合并的真实成本包括验证、回归测试、部署风险...

## Decision Matrix

| Criterion | Score 0 | Score 1 | Score 2 |
|---|---|---|---|
| ... | ... | ... | ... |

> **中文注释**: 决策矩阵打分。≥7 分强烈合并,5-6 分痛点强才合并,≤4 分别碰。

静态站点 (Docusaurus / VitePress) / Static Site

当前仓库用纯 Markdown README。如果 skill 数量增长超过 ~10 个,SSG + 原生 i18n 是合理升级路径。这节记录升级成本,避免下次重新研究。

何时升级 / When to Migrate

信号 / Signal阈值 / Threshold
仓库 skill 数量≥ 10
分类或主题分组数≥ 3
想在 SKILL 文档旁加教程 / 博客 / changelog任意
用户要搜索 / 版本钉住 / 侧边栏导航任意

如果以上都不满足,保持纯 Markdown —— Docusaurus + VitePress 增加 ~150 MB node_modules + 每次改动都要 build。

Docusaurus v3 (当前 3.10.x)

要求最低
Node.js18.0+ (推荐 20 LTS)
node_modules 磁盘~400 MB
package.json scriptsstart, build, serve, clear, deploy
i18n 配置docusaurus.config.js → i18n: { defaultLocale: 'zh', locales: ['zh', 'en'] }
内容布局i18n/zh/... 镜像源文件 + 每个页面 locale.json
Build 时间冷启动 30-90s,热 1-5s

VitePress (当前 1.x stable)

要求最低
Node.js18.0+ (推荐 20 LTS)
node_modules 磁盘~250 MB
配置文件.vitepress/config.mts → locales: { root: { label: '中文', lang: 'zh-CN' }, en: { lang: 'en-US' } }
内容布局docs/<lang>/<page>.md
Build 时间冷启动 5-30s,热 <1s

对比 / Comparison

维度Docusaurus v3VitePress
依赖体积~400 MB node_modules~250 MB node_modules
Build 速度较慢 (React + MDX)较快 (Vue + markdown)
i18n UX完整 locale switcher,版本化文档完整 locale switcher,无版本化
搜索Algolia / 本地本地 FlexSearch (默认)
主题Infima (CSS)默认 Vue theme
SKILL.md frontmatter 透传需要插件需要插件
适合大型 doc portal小中型文档 + 博客

via54Skills 推荐 / Recommendation

  • 现在 (2 个 skill): 保持纯 Markdown + 双 README.md / README.en.md。
  • 约 10 个 skill 时: 迁到 VitePress——更轻、更快、目录式 i18n 自然映射到 skill 目录。
  • 如果出现博客 / 教程系列: 升级 Docusaurus——自带更多(MDX、博客插件、版本化文档),值得更重的工具链。

现有 Skills / Current Skills

SkillSizeTopic
via54merge12.2 KBvenv / service / native binary consolidation
via54goport14.6 KBPython service → Go rewrite (eval + scaffold)

更多 skill 按需添加,每个 PR 单独 review。


安装 / Installation

方法 A: Symlink 到 Hermes Agent(本机 dev 用户推荐)

# Single skill
ln -s /Users/david/Desktop/developments/via54Skills/via54merge \
      ~/.hermes/skills/via54merge

# Or whole repo via external_dirs in ~/.hermes/config.yaml:
# skills:
#   external_dirs:
#     - /Users/david/Desktop/developments/via54Skills

方法 B: Claude Code

mkdir -p ~/.claude/skills
ln -s /Users/david/Desktop/developments/via54Skills/via54merge \
      ~/.claude/skills/via54merge
ln -s /Users/david/Desktop/developments/via54Skills/via54goport \
      ~/.claude/skills/via54goport

方法 C: OpenClaw

按 OpenClaw 文档:~/.agents/skills/ 或 <workspace>/skills/ 或 ~/.openclaw/skills/,任一即可。

mkdir -p ~/.agents/skills
ln -s /Users/david/Desktop/developments/via54Skills/via54merge \
      ~/.agents/skills/via54merge

方法 D: OpenCode

按 OpenCode 文档:~/.config/opencode/skills/、<repo>/.opencode/skills/、或 ~/.claude/skills/ 也行。

方法 E: Codex CLI

按 Codex CLI 文档:$CODEX_HOME/skills/。

Git Clone(用户角度)

git clone https://github.com/veawho/via54Skills.git

Git Workflow

cd /Users/david/Desktop/developments/via54Skills
git checkout -b feat/via54<new-skill>
# write via54<new-skill>/SKILL.md + maybe references/
git add via54<new-skill>/
git commit -m "feat: add via54<new-skill> skill

<short description in English>

Bilingual:
- SKILL.md Chinese Summary at top
- 中文注释 after key sections
- README.md / AGENTS.md bilingual (中/英)
- Frontmatter: Claude/Hermes/OpenClaw/OpenCode/Codex compatible

Validated:
- Hermes _validate_frontmatter OK
- Claude regex ^[a-z0-9]+(-[a-z0-9]+)*$ OK
- Description ≤1024 chars OK"
git push -u origin feat/via54<new-skill>
# PR review → merge → local skill auto-picks-up

远程 / Remote: github.com/veawho/via54Skills。


License

MIT (matches Hermes skill convention).

Ver o original no GitHub

Bom para

Relacionados