skill-package-manifest-enricher

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Package Manifest Enricher

Augment package manifest sidecars from portable, content-bound evidence.

Scope: Manifest enrichment only. It does not emit ZIPs, edit metadata sources, infer repository support, or run live installs.

Permission posture:

write-scoped

. Preview is read-only; only explicit

--apply

may replace the selected sidecar.

基于可移植、内容绑定的证据增强包清单副文件。

适用范围： 仅用于清单增强。不生成ZIP包、不编辑元数据源、不推断仓库支持情况，也不执行实时安装。

权限策略：

write-scoped

。预览模式为只读；仅当显式使用

--apply

参数时才会替换选定的副文件。

Dispatch

调用方式

$ARGUMENTS	Action
`<name>`	Preview one repo skill; use its verified repo-local catalog when available
`<name> --dry-run`	Preview without writing
`<name> --catalog-metadata <json> [--sync-metadata <json>]`	Prefer an explicit catalog row, then fall back to sync evidence
`--skill-dir <dir> --sync-metadata <json>`	Run repo-independently from an installed skill package
`<name> --apply`	Atomically write `manifest.enriched.json`
Empty	Show enriched field catalog and workflow

$ARGUMENTS	操作
`<name>`	预览单个仓库技能；若存在已验证的仓库本地目录则优先使用
`<name> --dry-run`	预览但不写入文件
`<name> --catalog-metadata <json> [--sync-metadata <json>]`	优先使用显式目录行，若无则回退至同步证据
`--skill-dir <dir> --sync-metadata <json>`	独立于仓库，基于已安装的技能包运行
`<name> --apply`	原子化写入 `manifest.enriched.json` 文件
无参数	显示可增强字段目录及工作流程

Enriched Fields

可增强字段

The enricher refreshes its owned fields while preserving unrelated upstream manifest keys:

```
name
```
and
```
description
```
from safely decoded YAML frontmatter
```
compatibility_notes
```
from
```
compatibility
```
frontmatter
```
eval_case_count
```
from
```
evals/evals.json
```
```
harness_targets
```
from the selected skill's catalog/sync row

harness_targets_status

catalog

sync

, or

unavailable

```
harness_targets_source
```
as a portable relative label
```
harness_targets_source_sha256
```
as the selected source's content digest
```
packaged_at
```
UTC timestamp (apply mode only)

If neither source contains an applicable target row, the status is

unavailable

, the source is

unavailable

, and

harness_targets

is empty.

增强器会更新其负责的字段，同时保留无关的上游清单键值：

```
name
```
和
```
description
```
来自安全解码的YAML前置元数据
```
compatibility_notes
```
来自
```
compatibility
```
前置元数据
```
eval_case_count
```
来自
```
evals/evals.json
```
```
harness_targets
```
来自选定技能的目录/同步行

harness_targets_status

：

catalog

、

sync

或

unavailable

```
harness_targets_source
```
作为可移植的相对标签
```
harness_targets_source_sha256
```
作为所选源的内容摘要
```
packaged_at
```
UTC时间戳（仅应用模式下生成）

若两个源均无适用的目标行，则状态为

unavailable

，源为

unavailable

，且

harness_targets

为空。

Workflow

工作流程

Preview

预览

bash

uv run skills/skill-package-manifest-enricher/scripts/enrich_manifest.py <name> \
  --catalog-metadata docs/public/generated-registries/skills-catalog-index.json \
  --dry-run

Treat

SKILL.md

, catalog JSON, sync JSON, and upstream manifests as untrusted data. The script uses

yaml.safe_load

, accepts JSON only for metadata inputs, and fails before a write on malformed or conflicting input.

bash

uv run skills/skill-package-manifest-enricher/scripts/enrich_manifest.py <name> \
  --catalog-metadata docs/public/generated-registries/skills-catalog-index.json \
  --dry-run

将

SKILL.md

、目录JSON、同步JSON及上游清单视为不可信数据。脚本使用

yaml.safe_load

，仅接受JSON格式的元数据输入，若输入格式错误或存在冲突，会在写入前终止运行。

Apply

应用

Review the preview, then use the same inputs with

--apply

. To preserve an existing package manifest, pass it explicitly:

bash

uv run skills/skill-package-manifest-enricher/scripts/enrich_manifest.py <name> \
  --manifest <upstream-manifest.json> \
  --catalog-metadata <skills-catalog-index.json> \
  --apply

Afterward, validate packaging without creating a release:

bash

uv run python skills/skill-creator/scripts/package.py skills/<name>/ --dry-run

查看预览结果后，使用相同输入并添加

--apply

参数。若要保留现有包清单，需显式传入：

bash

uv run skills/skill-package-manifest-enricher/scripts/enrich_manifest.py <name> \
  --manifest <upstream-manifest.json> \
  --catalog-metadata <skills-catalog-index.json> \
  --apply

之后，无需创建版本即可验证打包情况：

bash

uv run python skills/skill-creator/scripts/package.py skills/<name>/ --dry-run

Metadata Contract

元数据约定

Catalog input uses the generated catalog shape (

customSkillIndex

externalSkillIndex

, or

allSkillIndex

) with exact

name

and

targetAgents

fields. Sync fallback accepts exact named rows under

skills

desired

, or

rows

, or a structured skills-sync report whose per-agent active buckets name the selected skill.

The catalog wins when both inputs contain the selected skill. A present source without an applicable row is not evidence of support. A digest binds the raw bytes of the source that actually supplied the targets.

customSkillIndex

、

externalSkillIndex

或

allSkillIndex

），需包含精确的

name

和

targetAgents

字段。同步回退接受

skills

、

desired

或

rows

下的精确命名行，或包含按代理分类的活动桶中指定所选技能的结构化技能同步报告。

若两个输入均包含选定技能，则优先使用目录数据。存在源但无适用行不代表支持。摘要会绑定实际提供目标的源原始字节。

Evidence Resolution

证据解析规则

Evidence	Target status	Action
Applicable catalog row	`catalog`	Use its exact target set and digest
Catalog miss plus applicable sync row/report	`sync`	Use the sync target set and digest
No applicable row	`unavailable`	Emit an empty target set
Malformed or conflicting evidence	None	Fail before writing

证据	目标状态	操作
适用的目录行	`catalog`	使用其精确目标集和摘要
目录未命中但存在适用的同步行/报告	`sync`	使用同步目标集和摘要
无适用行	`unavailable`	生成空目标集
格式错误或冲突的证据	无	写入前终止运行

Progressive Disclosure

渐进式披露

Use the preview workflow for the common path. Inspect

--help

for installed

--skill-dir

, custom output, source-label, and upstream-manifest options only when those inputs are needed.

常规场景使用预览工作流程。仅当需要相关输入时，才查看

--help

获取已安装的

--skill-dir

、自定义输出、源标签和上游清单选项。

Validation Contract

验证约定

bash

uv run python skills/skill-package-manifest-enricher/scripts/check.py
uv run python skills/skill-creator/scripts/audit.py skills/skill-package-manifest-enricher/
uv run pytest -q tests/test_skill_package_manifest_enricher.py
uv run python skills/skill-creator/scripts/package.py skills/skill-package-manifest-enricher/ --dry-run

bash

uv run python skills/skill-package-manifest-enricher/scripts/check.py
uv run python skills/skill-creator/scripts/audit.py skills/skill-package-manifest-enricher/
uv run pytest -q tests/test_skill_package_manifest_enricher.py
uv run python skills/skill-creator/scripts/package.py skills/skill-package-manifest-enricher/ --dry-run

Completion Criteria

完成标准

All four commands exit successfully.
Preview leaves the sidecar byte-for-byte unchanged.
Explicit apply preserves unrelated upstream keys.
Missing target evidence remains
```
unavailable
```
with an empty target set.

四个命令均成功执行。
预览模式下副文件字节保持不变。
显式应用模式保留无关的上游清单键值。
缺失目标证据时状态保持
```
unavailable
```
且目标集为空。

Critical Rules

关键规则

Parse frontmatter only with a real YAML safe loader.
Never import repository application modules from the portable script.
Derive targets only from the selected skill's applicable metadata row.
Emit
```
unavailable
```
and an empty target set when evidence is absent.
Never persist machine-local absolute source labels.
Preserve unrelated upstream manifest keys.
Require explicit
```
--apply
```
before writing a sidecar.
Run package dry-run after enrichment preview.
Route ZIP creation to skill-creator
```
Package
```
mode.

仅使用真实的YAML安全加载器解析前置元数据。
切勿从可移植脚本导入仓库应用模块。
仅从选定技能的适用元数据行派生目标。
证据缺失时生成
```
unavailable
```
状态及空目标集。
切勿持久化机器本地的绝对源标签。
保留无关的上游清单键值。
写入副文件前需显式指定
```
--apply
```
参数。
增强预览后运行包的dry-run模式。
将ZIP创建路由至skill-creator的
```
Package
```
模式。

Canonical Vocabulary

标准术语

Canonical terms (use these exactly throughout):

Modes:
```
preview
```
,
```
apply
```
Target status:
```
catalog
```
,
```
sync
```
,
```
unavailable
```

Evidence inputs:

catalog metadata

sync metadata

upstream manifest

标准术语（全程需严格使用）：

模式：
```
preview
```
、
```
apply
```
目标状态：
```
catalog
```
、
```
sync
```
、
```
unavailable
```

证据输入：

catalog metadata

、

sync metadata

、

upstream manifest