# Research WeChat article Skills and deliver an HTML report

Use SoyaOS Cloud, live GitHub search, and deterministic quality gates to create a traceable single-file Skill comparison report.

This is a real, runnable SoyaOS Cloud recipe. It finds multiple WeChat Official Account article Skills from live web results, compares their trade-offs, recommends one, and delivers a single HTML file that passes content, structure, design, and security checks.

## The requirement

The original request is polished for flow without changing its scope:

> Search the web for Skills that can help create WeChat Official Account articles. Provide several genuinely available candidates and compare their strengths, weaknesses, and best-fit scenarios. Recommend one, explain why, and state the trade-offs. Deliver the complete result as one modern, attractive, clearly structured HTML file. Before finishing, verify that the file opens correctly and that its content, structure, and design meet expectations; fix any issue before delivery.

## Why this is not one Chat request

Cloud v0.2.0 exposes `soya:starter` as a hosted text Agent. It does not provide a browser, shell, or Tool Calls. A model claiming that it searched the web—or freely emitting a large, unchecked block of HTML—would not be a real example.

The Recipe separates responsibilities:

1. A local Node.js program searches repositories through the public GitHub API.
2. It retrieves candidate `SKILL.md` files and records source URLs, repository update times, and search time.
3. SoyaOS Cloud compares only the allowlisted sources and returns constrained JSON.
4. A versioned template renders the JSON; model text cannot inject tags, scripts, or styles.
5. The program writes the final file only after all four machine gates pass.

This is client-side Recipe orchestration with Cloud inference, not native Cloud Tool Calls.

## Prerequisites

- Node.js 22 or newer.
- Sign in by following the [Cloud quickstart](/en/docs/cloud-quickstart).
- Create an API key and save it immediately in a password manager. Treat the key as an opaque string; clients do not need to understand its format.

Get the source:

```bash
git clone https://github.com/soyaos/cloud-recipes.git
cd cloud-recipes
```

## Run the Recipe

Set the key only in the current shell. Never put it in source control:

```bash
export SOYA_API_KEY='your-soyaos-api-key'
npm run run:wechat-skill-research
```

The default output is `output/wechat-skill-research.html`.

The public GitHub API normally works without authentication. If you receive `github_rate_limited`, retry after the reset or temporarily provide a least-privilege `GITHUB_TOKEN`:

```bash
export GITHUB_TOKEN='your-github-token'
npm run run:wechat-skill-research
```

To intentionally replace an existing output file:

```bash
node recipes/wechat-skill-research/run.mjs --force
```

## Prove that it succeeded

A successful result reports at least three `candidates`, one or more SoyaOS Cloud `requestIds` that you can inspect in Portal Traces, and all four `qualityGates`: `content`, `structure`, `design`, and `security`.

| Gate | What it checks |
|---|---|
| Content | Candidate count, pros and cons, one recommendation, allowlisted sources, and live search time |
| Structure | Doctype, language, viewport, one main region, heading hierarchy, required sections, and a closed document |
| Design | Embedded design tokens, candidate cards, recommendation emphasis, responsive layout, focus styles, and print layout |
| Security | No scripts, iframes, forms, event handlers, external CSS/JS/fonts/images, or key leakage |

If any gate fails, the Recipe exits unsuccessfully instead of delivering a file that merely looks plausible.

## Why results can change

Candidates come from live GitHub search. Repository contents, update times, and ranking change. The Recipe guarantees a traceable process and quality contract, not a frozen candidate list. Each report retains the sources observed during that run.

## Privacy and quota

- GitHub receives the search queries and public repository requests.
- Candidate excerpts and your requirement are sent to the SoyaOS Cloud hosted model; the Recipe does not ask the service to persist the bodies.
- The local HTML contains the analysis and public repository links. Review custom prompts for sensitive information before sharing it.
- A normal run uses one Cloud request. Malformed model JSON may trigger at most one repair request.

## Troubleshooting

- `missing_api_key`: `SOYA_API_KEY` is not set in the current shell.
- `cloud_http_error ... invalid_api_key`: the key is invalid or revoked; create a new one in the Portal.
- `github_rate_limited`: wait for reset or temporarily set `GITHUB_TOKEN`.
- `insufficient_live_candidates`: fewer than three live candidates qualified; do not substitute fixtures for a successful run.
- `html_quality_failed`: fix the named gate before running again.

Source and tests: [soyaos/cloud-recipes](https://github.com/soyaos/cloud-recipes)

---

Canonical HTML: https://soyaos.ai/en/docs/cloud-recipes/wechat-skill-research