write-skill-readme

Write Skill README

BenszAPI Task Workspace

Intermediate files for new tasks of this Skill are uniformly written to ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/{skill名}/input|output|log/. The same task reuses one task root directory; only when multiple Skills collaborate is shared/created. Official deliverables are not written to this directory; historical hidden directories are only allowed to be explicitly read for compatibility, migration, or cleanup.

Collaboration agreement with bensz-collect-bugs

For bugs caused by design flaws in this skill, first use bensz-collect-bugs to record them in a standardized way to ~/.bensz-skills/bugs/, do not directly modify the skill source code already installed locally by the user; if there is a workaround, record the bug first, then continue completing the task.
Only when the user explicitly requests public reporting such as "report bensz skills bugs" should you use the local gh to upload newly added bugs to huangwb8/bensz-bugs; do not pull / clone the entire repository.

Write best-practice-compliant README.md user guides for Agent Skills.

Trigger Conditions

Use this skill when the user requests generating/writing/updating README.md, a user guide, or skill documentation for a skill.

Core Workflow

⚠️ Safety restriction: This skillis only used to generate/update README.md files，must never modify any existing content of the target skill(including but not limited to SKILL.md, SKILL.yaml, config.yaml, scripts/, references/, etc.). These files can only be read as analysis input; no write or edit operations may be performed on them.

Step 1: Analyze the skill structure

Read and analyze the following files:

SKILL.yaml — skill metadata (name, description, version, author, metadata)
SKILL.md — skill core specification (trigger conditions, workflow, input/output)
config.yaml(optional) — configurable parameters
scripts/ directory (optional) — hardcoded usage
references/ directory (optional) — reference documentation

Step 2: Determine the README type

Select a template based on the skill characteristics:

Skill Type	Characteristics	Recommended Template
Functional	Mainly triggered through prompts, with a clear workflow	Template A: systematic-literature-review style
Tool-based	Mainly invoked through scripts/command line	Template B: install-bensz-skills style
Hybrid	Prompt-first + script fallback	Template C: make_latex_model style

Step 3: Generate the core sections

Generate README.md content in the following order:

3.1 Title and audience statement

# {技能名称} — 用户使用指南

本 README 面向**使用者**：如何触发并正确使用 `{技能名称}` skill。
执行指令与硬性规范在 `SKILL.md`；默认参数在 `config.yaml`。

3.2 Quick Start (core section)

Principle: The Prompt section should beshort, intuitive, and copyable. Prioritize giving users a "minimal usable" general format, so users can tell at a glance: which skill to use, what the input is, and what will be produced.

Contents to include (recommended minimal set):

Regular Prompt (minimal usable)(1 item) — Must use a unified format to specify "which skill / input / output"
Advanced Prompt (optional)(1 item) — Add "parameter constraints" on top of the regular Prompt, without expanding into lengthy descriptions

Regular Prompt template (write into README as the "most recommended usage"):

请使用 {skill_name} skill {完成xxx任务}
输入：{输入是什么（文件/路径/URL/文字/文件夹等）}
输出：{输出是什么（文件/路径/格式/数量等）}

Advanced Prompt template (write into README as "advanced usage / with parameter constraints"):

{常规Prompt}
另外，还有下列参数约束：
- 参数1：{说明}
- 参数2：{说明}

3.3 Design Philosophy / Feature Overview

Explanation:

The skill's core value
How it works (simplified version, for beginners)
Design philosophy (if any)
Differences from / combined use with other skills

3.4 Prompt examples / Usage examples

Byscenario classification + progressive complexityorganization (but keep each example short, to avoid turning the README into a "parameter manual"):

### 示例 1：[场景描述]（最简单）

Prompt


### 示例 2：[场景描述]