feat: add html-docs skill - #1254
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1455810d38
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| default_prompt: "Use $html-docs to turn this source into a polished private course with an observable learner finish line, evidence-state mastery, rich lesson pages, cue-synced explanatory videos, diagnostic practice, captions, and feedback." | ||
|
|
||
| policy: | ||
| allow_implicit_invocation: true |
There was a problem hiding this comment.
When a user makes a generic request for a visual document or course without naming HTML Docs, this policy permits implicit activation even though the critical-risk workflow automatically publishes a private preview to a third-party service. That can upload local repository or document content without the explicit publication authorization required by SKILL.md; disable implicit invocation or require confirmation before any network upload.
AGENTS.md reference: AGENTS.md:L52-L54
Useful? React with 👍 / 👎.
| RESPONSE=$(curl -sS -X "$METHOD" "$URL" \ | ||
| -H "content-type: $CONTENT_TYPE" \ | ||
| "${AUTH_ARGS[@]}" \ | ||
| "${TOKEN_ARGS[@]}" \ | ||
| "${EXTRA_HEADERS[@]}" \ |
There was a problem hiding this comment.
When --doc-id updates a document while another reviewer has made a newer edit, this unconditional PUT supplies no ETag or If-Match, so it can overwrite the concurrent revision rather than receiving the documented 412 revision_conflict. The bundled API reference explicitly requires fetching the latest ETag before replacement; the script should fetch and send it, or require it as an argument.
AGENTS.md reference: AGENTS.md:L52-L54
Useful? React with 👍 / 👎.
| echo "publish_result.edit_url=$EDIT_URL" >&2 | ||
| echo "publish_result.token=$OUT_TOKEN" >&2 |
There was a problem hiding this comment.
For anonymous publishes, the response's edit URL and token grant mutation access, yet both are written unconditionally to stderr, where agent session capture, CI logs, or shared terminal recording can retain them. This directly conflicts with the skill's instruction to redact these values from terminals and logs; store them in a permission-restricted file or reveal them only through an explicit secure-output option.
AGENTS.md reference: AGENTS.md:L52-L54
Useful? React with 👍 / 👎.
| RESPONSE=$(curl -sS -X POST "$URL" \ | ||
| -H "content-type: $CONTENT_TYPE" \ | ||
| "${AUTH_ARGS[@]}" \ | ||
| "${EXTRA_HEADERS[@]}" \ | ||
| --data-binary "$CONTENT" 2>&1) || true |
There was a problem hiding this comment.
If a supplied HTML or Markdown file consists of content beginning with @—for example, an untrusted file containing @/etc/passwd—passing the content directly to --data-binary makes curl read and upload the named local file instead. The installed curl --manual states that when --data-binary data starts with @, the remainder is treated as a filename; send the body through stdin with --data-binary @- instead.
AGENTS.md reference: AGENTS.md:L52-L54
Useful? React with 👍 / 👎.
| elif [[ -d "$TARGET" ]]; then | ||
| # For directories, look for index.html | ||
| if [[ -f "$TARGET/index.html" ]]; then | ||
| CONTENT=$(cat "$TARGET/index.html") |
There was a problem hiding this comment.
When the advertised directory mode is used for a multi-page site or an index referencing relative CSS, JavaScript, images, or lesson files, the script reads and uploads only the index file and silently drops every other directory entry. The resulting hosted site has broken routes and assets; package the complete directory or reject directory inputs unless they are explicitly self-contained.
AGENTS.md reference: AGENTS.md:L52-L54
Useful? React with 👍 / 👎.
| publish.sh ./site/ --api-key hdk_xxx # authenticated, directory | ||
| publish.sh page.html --doc-id <id> --doc-token <tok> # update existing |
There was a problem hiding this comment.
When users follow these authenticated update examples with real values, the account API key or anonymous document token is placed in shell history and may be visible in process listings, contradicting the skill's requirement that credentials never enter shell history or logs. Require the environment/auth credential store, stdin, or a protected file descriptor instead of documenting secret-bearing arguments.
AGENTS.md reference: AGENTS.md:L52-L54
Useful? React with 👍 / 👎.
1 participant
Summary
Adds the public
html-docsskill bundle fromraunaqbn/html-docs-skill. The skill creates source-grounded HTML documents, narrated videos, and courses, then publishes and reviews them through HTML Docs.This is a source-only contribution: 18 skill-owned files are included, while generated catalog and registry artifacts are intentionally excluded.
Provenance and safety
risk: criticalbecause the workflow can authenticate, mutate documents, upload assets, and publish externally.If-Match.Validation
npm run validate— passed (2,029 skills; only the repository's existing advisories)npm run validate:references— passednpm run security:docs— passednpm test— all tests reached the final generated-catalog contract; the source-only tree reports the expected 2,029-vs-2,028 generated registry mismatch. Generated artifacts were restored and are not included, per the contributor contract; PR CI owns the generated preview.Change Classification
Quality Bar Checklist ✅
docs/contributors/quality-bar.mdanddocs/contributors/security-guardrails.md.SKILL.mdfrontmatter is valid (checked withnpm run validate).risk:tag.## Limitationssection.npm run security:docspassed.risk:were manually reviewed.npm run validate:referencespassed.license: MITandlicense_source:are declared.Agent assistance disclosure
Codex assisted with the mechanical bundle import, metadata adaptation, validation, and PR preparation. The contributor reviewed the resulting source-only diff and its safety-critical guidance before submission.