skills-readme-alignment-maintainer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skills README Alignment Maintainer

Skills README规范对齐维护工具

Run deterministic README standards maintenance for

*-skills

repositories in a workspace.

用于对工作区中的

*-skills

仓库执行确定性的README标准维护。

Inputs

输入参数

Pass runtime inputs from the calling prompt:

```
--workspace <path>
```
```
--repo-glob <pattern>
```
(default:
```
*-skills
```
)
```
--exclude <path>
```
(repeatable)
optional
```
--apply-fixes
```
optional
```
--md-out
```
,
```
--json-out
```

从调用prompt中传入运行时输入：

```
--workspace <path>
```
```
--repo-glob <pattern>
```
(默认值:
```
*-skills
```
)
```
--exclude <path>
```
(可重复使用)
可选
```
--apply-fixes
```
可选
```
--md-out
```
,
```
--json-out
```

Workflow

工作流

Run pass 1 audit with
```
scripts/readme_alignment_maintainer.py
```
.
Review profile assignments and issue categories.
If bounded remediation is desired, run pass 2 with
```
--apply-fixes
```
.
Re-check touched repos (handled by script).
Report Markdown and JSON outputs.

使用
```
scripts/readme_alignment_maintainer.py
```
执行第一步审计。
检查配置分配和问题分类。
如果需要进行有限范围修复，添加
```
--apply-fixes
```
参数执行第二步。
重新检查被修改的仓库（由脚本自动处理）。
输出Markdown和JSON格式的报告。

Commands

命令

Audit only:

bash

uv run python scripts/readme_alignment_maintainer.py \
  --workspace ~/Workspace \
  --repo-glob '*-skills' \
  --print-md \
  --print-json

Audit and bounded fixes:

bash

uv run python scripts/readme_alignment_maintainer.py \
  --workspace ~/Workspace \
  --repo-glob '*-skills' \
  --apply-fixes \
  --md-out /tmp/readme-alignment-report.md \
  --json-out /tmp/readme-alignment-report.json

Fail when unresolved issues remain:

bash

uv run python scripts/readme_alignment_maintainer.py \
  --workspace ~/Workspace \
  --repo-glob '*-skills' \
  --apply-fixes \
  --fail-on-issues

仅审计：

bash

uv run python scripts/readme_alignment_maintainer.py \
  --workspace ~/Workspace \
  --repo-glob '*-skills' \
  --print-md \
  --print-json

审计并执行有限范围修复：

bash

uv run python scripts/readme_alignment_maintainer.py \
  --workspace ~/Workspace \
  --repo-glob '*-skills' \
  --apply-fixes \
  --md-out /tmp/readme-alignment-report.md \
  --json-out /tmp/readme-alignment-report.json

存在未解决问题时返回失败：

bash

uv run python scripts/readme_alignment_maintainer.py \
  --workspace ~/Workspace \
  --repo-glob '*-skills' \
  --apply-fixes \
  --fail-on-issues

Safety Rules

安全规则

Never commit changes automatically.
Edit README files only.
Never edit source code, manifests, lockfiles, CI files, or AGENTS.md.
Apply only bounded heading/schema/discoverability insertions and bootstrap README creation.
Keep diffs minimal and preserve existing style where possible.

永远不要自动提交变更。
仅编辑README文件。
永远不要编辑源代码、清单文件、锁文件、CI文件或AGENTS.md。
仅可执行有限范围的标题/结构/可发现性内容插入，以及引导式README创建。
保持diff最小化，尽可能保留原有风格。

Profile Model

配置模型

Use

references/profile-model.md

public curated repos: enforce full schema including

## Customization Workflow Matrix

## Install individually by Skill or Skill Pack

## Update Skills

, wrapped discoverability sections (

## More resources for similar Skills

with required nested

###

subsections), and

## Keywords

private/internal repos: keep concise, omit growth-only sections
bootstrap repos: allow initial README creation with minimal complete structure

使用

references/profile-model.md

：

公开精选仓库：强制执行完整结构，包括

## Customization Workflow Matrix

、

## Install individually by Skill or Skill Pack

、

## Update Skills

、包装后的可发现性章节（

## More resources for similar Skills

及要求的嵌套

###

子章节），以及

## Keywords

私有/内部仓库：保持简洁，省略仅用于增长的章节
引导型仓库：允许创建具备最小完整结构的初始README

Output Contract

输出约定

The script emits:

Markdown summary of run context, profile assignments, issues, fixes, remaining issues, and errors.

JSON report containing:

```
run_context
```
```
repos_scanned
```
```
profile_assignments
```
```
schema_violations
```
```
command_integrity_issues
```
```
fixes_applied
```
```
post_fix_status
```
```
errors
```

Use JSON for automation integration and Markdown for operator review.

脚本会输出：

Markdown格式的运行上下文、配置分配、问题、修复内容、剩余问题和错误的摘要。

JSON格式的报告，包含：

```
run_context
```
```
repos_scanned
```
```
profile_assignments
```
```
schema_violations
```
```
command_integrity_issues
```
```
fixes_applied
```
```
post_fix_status
```
```
errors
```

JSON输出用于自动化集成，Markdown输出用于操作人员查看。

Automation Templates

自动化模板

Use

$skills-readme-alignment-maintainer

in automation prompts.

For ready-to-fill Codex App and Codex CLI templates, use:

```
references/automation-prompts.md
```

在自动化prompt中使用

$skills-readme-alignment-maintainer

。

如需可直接填充的Codex App和Codex CLI模板，请使用：

```
references/automation-prompts.md
```

References

参考文档

Profile mapping:
```
references/profile-model.md
```
Required sections by profile:
```
references/section-schema.md
```
Voice and style rules:
```
references/style-rules.md
```
Discoverability requirements:
```
references/discoverability-rules.md
```
Verification checklist:
```
references/verification-checklist.md
```
Seed standards artifacts:
```
references/seed-artifacts.md
```
Automation prompt templates:
```
references/automation-prompts.md
```

配置映射：
```
references/profile-model.md
```
各配置要求的必填章节：
```
references/section-schema.md
```
语气和风格规则：
```
references/style-rules.md
```
可发现性要求：
```
references/discoverability-rules.md
```
验证检查清单：
```
references/verification-checklist.md
```
标准种子物料：
```
references/seed-artifacts.md
```
自动化prompt模板：
```
references/automation-prompts.md
```