Skill Guide Generator

Skill Guide Generator is an agent skill for reading an existing skill folder and generating practical, user-facing documentation for ordinary users.

It recursively scans the target skill directory, reads files such as SKILL.md, README.md, agents/, references/, assets/, examples/, prompts/, templates/, docs/, configuration files, and other relevant instructions, then generates a clear USER_GUIDE.md. For complex skills, it can also generate a shorter QUICK_START.md.

When To Use It

• You downloaded or created a skill, but ordinary users do not yet know how to use it.
• You want to turn a skill's SKILL.md, README, references, templates, and examples into a clear usage guide.
• You want a consistent USER_GUIDE.md saved in the target skill root, next to the target skill's SKILL.md.
• You need to identify a skill's trigger phrases, use cases, required inputs, output files, workflow, limitations, and customization options.
• You want to check whether the original skill documentation is incomplete, inconsistent, or hard for users to understand.
• You are organizing multiple skills and want their user-facing documentation to follow a consistent structure.

When Not To Use It

• It is not for implementing the target skill's core functionality.
• It does not verify whether the target skill's business or analytical output is correct; it only analyzes what the target skill documents say.
• It cannot infer capabilities that the target skill documents do not support.
• It should not be used by reading only one file; the intended workflow is to scan the full skill directory.
• It is not a simple README generator. Its purpose is to explain how ordinary users should operate a skill.

Directory Structure

Recommended structure:

skill-guide-generator/
  SKILL.md
  README.md
  README_CN.md
  agents/
    openai.yaml
  references/
    extraction-checklist.md
    output-writing-rules.md
  assets/
    USER_GUIDE_TEMPLATE.md
    USER_GUIDE_TEMPLATE_EN.md
    QUICK_START_TEMPLATE.md
    QUICK_START_TEMPLATE_EN.md

File purposes:

File/Directory	Purpose
SKILL.md	Core trigger description and execution workflow
agents/openai.yaml	UI metadata and default prompt
references/extraction-checklist.md	Checklist for extracting facts from a target skill
references/output-writing-rules.md	Writing rules for USER_GUIDE.md and QUICK_START.md
assets/USER_GUIDE_TEMPLATE.md	Chinese full user-guide template
assets/USER_GUIDE_TEMPLATE_EN.md	English full user-guide template
assets/QUICK_START_TEMPLATE.md	Chinese quick-start template
assets/QUICK_START_TEMPLATE_EN.md	English quick-start template
README.md	English user-facing documentation
README_CN.md	Chinese user-facing documentation

How To Trigger It

Explicit trigger:

$skill-guide-generator

Natural-language requests can also trigger it:

Analyze this skill folder and generate user-facing documentation.

Create USER_GUIDE.md and QUICK_START.md for this skill.

Read this skill's SKILL.md, README, references, and assets, then rewrite them into a guide ordinary users can understand.

请分析这个 skill 目录，生成中文用户使用说明。

What To Prepare

Material	Required	Recommended Format	Notes
Target skill root	Required	Local path	The folder should ideally contain SKILL.md.
Output location	Optional	Local path	Defaults to the target skill root, next to the target SKILL.md or AGENTS.md.
Output language	Optional	English / Chinese / bilingual	Chinese prompts produce Chinese guides by default; English prompts produce English guides by default; explicit language requests override this; ambiguous cases should be clarified first.
Quick-start preference	Optional	Yes / No	Complex skills should usually get a QUICK_START.md.
Special focus	Optional	Text	For example: inputs, trigger wording, output files, or doc conflicts.

The more complete the target skill directory is, the more accurate the generated guide will be. Ideally, the target skill includes:

SKILL.md
README.md or USAGE.md
agents/
references/
assets/ or templates/
examples/ or prompts/

If some files are missing, Skill Guide Generator will still analyze what is available and mark unclear parts as not explicitly documented or needs runtime confirmation.

What It Does

1. Confirms that the target skill path exists.
2. Recursively scans the target skill directory.
3. Identifies primary docs, runtime metadata, internal references, templates, examples, configs, and scripts.
4. Extracts information ordinary users need:
   • what the skill does
   • when to use it
   • when not to use it
   • how to trigger it
   • what materials to prepare
   • recommended input formats
   • what workflow the agent will run
   • what files the skill will produce
   • where outputs may be saved
   • quality checks and limitations
   • customization options
5. Generates a full USER_GUIDE.md using assets/USER_GUIDE_TEMPLATE.md or assets/USER_GUIDE_TEMPLATE_EN.md, depending on the selected output language.
6. Generates a concise QUICK_START.md using assets/QUICK_START_TEMPLATE.md or assets/QUICK_START_TEMPLATE_EN.md when useful.
7. Checks for unreplaced placeholders, missing sections, and unsupported capability claims.
8. Reports which files were read, which files were generated, and what documentation gaps were found.

Default Output

By default, outputs are saved in the target skill root, meaning the directory you asked it to analyze. If that directory contains AGENTS.md, the generated files should be saved next to it:

<target-skill-root>/
  USER_GUIDE.md
  QUICK_START.md   # optional, for complex skills or when requested

The skill should not silently save generated guide files to the agent's current workspace, a scratch directory, work/outputs, or any other fallback location. If the target skill root is not writable, it should ask you for permission or an alternate output directory before creating files elsewhere.

Language behavior:

• Chinese prompt + no explicit language preference -> Chinese USER_GUIDE.md / QUICK_START.md.
• English prompt + no explicit language preference -> English USER_GUIDE.md / QUICK_START.md.
• Explicit Chinese, English, or bilingual request -> follow the requested language.
• Ambiguous prompt, target audience, or output language -> ask one short clarification question before writing files.

USER_GUIDE.md usually includes:

1. One-sentence explanation
2. When to use this skill
3. When not to use this skill
4. How to trigger this skill
5. What materials to prepare
6. Recommended input formats
7. What the skill will do
8. What it will output
9. What the report/output roughly looks like
10. Usage examples
11. Output quality checks
12. Limitations and cautions
13. Customization options
14. Quick-start prompt template
15. Unclear or improvable parts of the original docs
16. Improvement suggestions for the original skill docs

QUICK_START.md usually includes:

- What the skill does
- When to use it
- Trigger syntax
- Minimum required materials
- Better input materials
- Default output
- Copyable prompts
- Key cautions

Recommended Prompts

Most common:

Use $skill-guide-generator to analyze this skill folder:
<target skill root>

Recursively read all relevant docs, references, assets, examples, prompts, templates, and config files.
Generate USER_GUIDE.md in English and save it in the target skill root.
If the skill is complex, also generate QUICK_START.md.
Do not invent unsupported capabilities. Mark unclear items explicitly.

Specify output:

Use $skill-guide-generator to analyze <target skill root>.
Generate:
1. USER_GUIDE.md
2. QUICK_START.md

Output language: English.
Output location: target skill root.
Focus on triggers, input materials, output files, workflow, quality checks, and documentation gaps.

Documentation quality review:

Use $skill-guide-generator to review the documentation in <target skill root>.
Generate USER_GUIDE.md and include an "Improvement Suggestions For The Original Skill Docs" section.
Pay special attention to inconsistencies between README.md, SKILL.md, agents/openai.yaml, and references.

Chinese output:

请使用 $skill-guide-generator 分析这个 skill 目录：
<目标 skill 根目录>

请生成中文 USER_GUIDE.md；如果有必要，也生成简短 QUICK_START.md。
保存到目标 skill 根目录。
不要编造原文档没有支持的功能；不确定的地方请明确标注。

Output Quality Requirements

Before and after generating documentation, check that:

• The target skill directory was scanned recursively.
• Major documentation and reference files were read.
• The true skill trigger name was identified, not confused with the folder name.
• User-facing information is separated from internal agent references.
• Inferred behavior is not presented as a guaranteed capability.
• Unclear items are marked as not explicitly documented or needs runtime confirmation.
• Inconsistencies between README, SKILL.md, agent metadata, or references are listed.
• At least three copyable usage examples are included.
• A material-preparation table is included.
• Output files and possible directories are explained.
• A concrete improvement table for the original skill docs is included.
• The generated documentation language matches the user's request, or the agent asked for clarification before writing files.

Cautions

• If the target skill root is inaccessible, ask the user for the correct path.
• If the target skill has no SKILL.md, continue only when other documentation is sufficient, and clearly mention the missing root SKILL.md.
• If the folder name differs from the name in SKILL.md frontmatter, document the real trigger name.
• If the target skill root or requested output directory is not writable, ask the user for permission or an alternate output directory before creating files elsewhere.
• Skill Guide Generator generates user-facing documentation. It does not implement the target skill's functionality.
• Do not claim support for features absent from the original docs. Use explicit uncertainty labels instead.

Good Template For These Tasks

This skill works well as a reusable base for:

• generating USER_GUIDE.md for any Codex skill
• generating Chinese or English usage guides for Claude/Codex-compatible skills
• organizing user-facing docs across a skills directory
• checking whether trigger names, input requirements, and output conventions are clear
• rewriting developer-oriented SKILL.md content into ordinary-user documentation