GitHub Repo Guide PDF

Analyze a GitHub repository URL or OWNER/REPO and produce a Chinese user guide focused on how to use the project, not how it is implemented. Build a Markdown...

Security Scan

The skill is internally consistent with its stated purpose (turning a GitHub repo into a Chinese usage guide + PDF); it reads/clones repos and runs a local PDF build script, and there are only minor documentation/expectation gaps about required local tools.

Purpose & Capability

The skill's claimed purpose (produce a usage-first guide + PDF from a GitHub repo) matches the instructions and included build script. One minor mismatch: SKILL.md expects tools like gh, rg, pandoc, and a TeX engine (tectonic/xelatex/lualatex) and Python 3, but the skill metadata does not declare any required binaries. This is an omission in metadata rather than a functional inconsistency.

Instruction Scope

Runtime instructions are scoped to finding user-facing docs, cloning the repo to a temporary directory, reading necessary files, producing Markdown, and running the included Python script to make a PDF. The instructions explicitly prefer user-facing docs and avoid dumping entire repo content into the agent context. There is no instruction to exfiltrate data to third-party endpoints.

Install Mechanism

There is no install spec (instruction-only plus one local Python script). The included script invokes local binaries (pandoc, TeX engines) but does not download or execute remote code. No high-risk install behavior detected.

Credentials

The skill declares no required environment variables or credentials. However, practical use of 'gh' (recommended) will use the user's gh authentication if present (and is needed for private repos or rate-limited access). This is proportionate to the task, but users should be aware that local GitHub credentials may be used implicitly.

Persistence & Privilege

always is false and the skill does not request persistent system-wide privileges or modify other skills. The skill can be invoked autonomously (default), which is normal; that alone is not a red flag here.

Assessment

This skill appears to do what it says — clone a repo, extract user-facing docs, generate a Markdown guide and build a PDF with the included script. Before installing or running it: ensure you have the tools it expects (gh for GitHub metadata/cloning if you want that flow, ripgrep (rg) for fast file discovery, python3, pandoc, and a PDF engine like tectonic/xelatex/lualatex). If you plan to run it against private repos, be aware 'gh' will use your local auth tokens; do not provide private or sensitive repos unless you trust the environment. The script runs locally and does not send data to external endpoints, but it will read files in the repository (which could include secrets); consider running in an isolated workspace if that is a concern. Finally, note that the skill metadata omits the required binaries — expect to install them yourself or the job may fail.

Turn a GitHub repository into a usage-first Chinese guide and PDF.

Inputs

• Accept a GitHub repo URL or OWNER/REPO.
• Default audience: user/operator, not maintainer or contributor.
• If the repo is a monorepo, has several products, or mixes SDK plus server plus docs, ask one scoping question before continuing.

Workflow

1. Normalize the repo identifier.
2. Use gh first for repo metadata. Fall back to browser only if gh is blocked or missing needed details.
3. Clone the repo into a temporary directory with shallow depth when possible.
4. Inspect user-facing docs and entry points.
5. Write a Chinese Markdown guide that teaches usage, not internals.
6. Build a PDF with scripts/build_pdf.py.
7. Reply with one short status line plus MEDIA: lines for the generated files.

Collection Rules

Prefer these sources, in this order:

1. README* and localized README files
2. docs/ and obvious user-guide files
3. command reference and configuration docs
4. package.json, pyproject.toml, Cargo.toml, go.mod, or equivalent manifest files for install/runtime hints
5. examples, templates, or sample config files
6. GitHub repo metadata from gh repo view

Use rg --files to find files quickly. Favor user-facing docs over architecture or internal implementation notes.

Analysis Rules

Focus on what a real user needs to learn:

• what the project is
• who it is for
• prerequisites and install
• quick start
• main commands or workflows
• important config options
• when to use which mode or command
• troubleshooting and common pitfalls
• minimal cheat sheet

Avoid deep implementation detail unless it is required to explain usage.

If docs are weak, infer carefully from manifests, command docs, examples, and CLI entry points. State uncertainty briefly instead of pretending.

Preferred GitHub Retrieval

Use gh first.

Examples:

gh repo view OWNER/REPO --json name,description,url,defaultBranchRef,licenseInfo,stargazerCount,forkCount,updatedAt

gh repo clone OWNER/REPO /tmp/repo -- --depth=1

If gh is insufficient, use browser to inspect the GitHub page or linked docs site.

Recommended File Discovery

rg --files . | rg '(^README|^readme|^docs/|guide|manual|command|config|example|package\.json$|pyproject\.toml$|Cargo\.toml$|go\.mod$)'

Read only the files needed to build the guide. Do not dump the whole repo into context.

Output Structure

Use this structure unless the repo clearly needs a different shape:

1. What it is
2. Who it is for
3. Installation and prerequisites
4. Quick start
5. Core workflows or commands
6. Configuration and modes
7. Recommended usage paths by scenario
8. Troubleshooting and common mistakes
9. One-page cheat sheet
10. Sources used

Output Paths

Write outputs under the workspace media directory so they can be sent directly:

• Markdown: media/<slug>-user-guide-zh-YYYYMMDD-HHMMSS.md
• PDF: media/<slug>-user-guide-zh-YYYYMMDD-HHMMSS.pdf

Use a short slug derived from the repo name.

PDF Build

After the Markdown guide is ready, run:

python3 skills/github-repo-guide-pdf/scripts/build_pdf.py \
  --markdown /absolute/path/to/guide.md \
  --output /absolute/path/to/guide.pdf \
  --title "<title>" \
  --source-url "https://github.com/OWNER/REPO"

If font selection fails, rerun with:

--mainfont "Hiragino Sans GB"

Final Reply

After success, reply with:

1. one short sentence saying the guide is ready
2. one MEDIA: line for the Markdown file
3. one MEDIA: line for the PDF file

Example:

Done. I turned the repo into a Chinese usage guide and PDF.
MEDIA:media/example-user-guide-zh-20260328-150500.md
MEDIA:media/example-user-guide-zh-20260328-150500.pdf

Validation Checklist

Before replying, verify all of the following:

• the repo URL or OWNER/REPO was normalized correctly
• the guide is usage-first, not implementation-first
• the Markdown file exists and is non-empty
• the PDF exists and is non-empty
• both files live under the workspace media directory
• the MEDIA: paths match the actual files