From 09175c74027a4c40e7542a7b084db619087c08fb Mon Sep 17 00:00:00 2001 From: Dhilip Subramanian <49802211+sdhilip200@users.noreply.github.com> Date: Fri, 26 Jun 2026 13:29:24 +1200 Subject: [PATCH] docs: add CONTRIBUTING guide and issue/PR templates Add contributor scaffolding for the repo (additive only; no changes to SKILL.md, templates, or behavior): - CONTRIBUTING.md: toolchain setup (mise/uv), the self-contained-template conventions, eval flow, and PR guidance. - .github/ISSUE_TEMPLATE/: bug report, new-template request, and config (with links to the API docs and Agent Skills spec). - .github/PULL_REQUEST_TEMPLATE.md: focused checklist incl. the self-contained-template requirements. Refs #1 --- .github/ISSUE_TEMPLATE/bug_report.md | 31 ++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 +++ .github/ISSUE_TEMPLATE/template_request.md | 23 ++++++ .github/PULL_REQUEST_TEMPLATE.md | 21 ++++++ CONTRIBUTING.md | 82 ++++++++++++++++++++++ 5 files changed, 165 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/template_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..597bf18 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,31 @@ +--- +name: Bug report +about: Something in the skill, templates, or publishing flow isn't working +title: "" +labels: bug +assignees: "" +--- + +**What happened** +A clear description of the problem. + +**What you expected** +What you expected to happen instead. + +**Steps to reproduce** +1. … +2. … + +**Publishing details (if relevant)** +- The request you made (endpoint + body shape). +- The API response status and `message` field. + +> ⚠️ Never paste an `update_key` — it's a secret write credential. Redact it. + +**Environment** +- Agent/client (e.g. Claude Code, Codex): +- Install method (install.sh / `skills` CLI / plugin / manual): +- OS: + +**Anything else** +Screenshots, the template involved, or other context. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..1b4383b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: true +contact_links: + - name: ht-ml.app API docs + url: https://ht-ml.app/llms.txt + about: Self-documenting API reference (also at https://api.ht-ml.app/v1/help). + - name: Agent Skills specification + url: https://agentskills.io/specification + about: The spec this skill is validated against. diff --git a/.github/ISSUE_TEMPLATE/template_request.md b/.github/ISSUE_TEMPLATE/template_request.md new file mode 100644 index 0000000..eb826f0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/template_request.md @@ -0,0 +1,23 @@ +--- +name: New template request +about: Suggest a new page template for the catalog +title: "Template: " +labels: template +assignees: "" +--- + +**Use case** +What does a user want to make? When should the skill offer this template? +(e.g. "a changelog / release notes page", "an RFC / design doc"). + +**Why it's not covered** +Which existing templates are close, and why they don't fit. (See the catalog in +`assets/templates/README.md`.) + +**What it should contain** +Key sections, layout, and any interactive bits (it must stay self-contained — all +CSS/JS/SVG inlined, no external resources). + +**Are you up for contributing it?** +- [ ] Yes, I'd like to open a PR (see `CONTRIBUTING.md`). +- [ ] No, just suggesting. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..a36e9f3 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,21 @@ + + +## What & why + + +## Type of change +- [ ] New template +- [ ] Docs +- [ ] Eval +- [ ] Bug fix +- [ ] Other: + +## Checklist +- [ ] `mise run validate` passes. +- [ ] If this is behavior-related, I considered an eval case in `evals/`. + +### For a new template +- [ ] Self-contained — all CSS/JS/SVG inlined, **no external resources**. +- [ ] Uses `` markers for editable regions. +- [ ] Renders standalone in a browser (sensible placeholder content). +- [ ] Registered in **both** `assets/templates/README.md` and the table in `SKILL.md`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b6c35f4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,82 @@ +# Contributing to `html` + +Thanks for your interest in improving the `html` Agent Skill! This is a small, +focused project, so contributions of any size are welcome — a new template, a +docs fix, a sharper eval, or a bug report. + +By contributing, you agree that your contributions are licensed under the +project's [MIT License](README.md#license). + +## Ways to contribute + +- **Add a page template** — the most useful contribution (see below). +- **Improve the docs** — `README.md`, `SKILL.md`, or `references/api.md`. +- **Strengthen the evals** — add discriminating cases in `evals/`. +- **Report a bug or request a template** — open an issue. + +For anything larger than a small fix, please **open an issue first** so we can +agree on the approach before you invest time. There's no `CONTRIBUTING` police — +when in doubt, ask in an issue. + +## Development setup + +This repo uses [mise](https://mise.jdx.dev) + [uv](https://docs.astral.sh/uv/) +for its toolchain. + +```bash +mise install # provision Python + uv +mise run validate # validate the skill against the Agent Skills spec +``` + +`mise run validate` runs the [`skills-ref`](https://agentskills.io) validator +against the repo. Please make sure it passes before opening a PR. + +## Adding a template + +Templates live in `assets/templates/` and are the catalog the skill offers when a +user wants to publish something but has no HTML of their own. The bar is: a +template should render nicely out of the box and publish to ht-ml.app in a single +request. + +**Conventions (please follow all of these):** + +1. **Fully self-contained.** Inline all CSS, JS, and SVG. No external resources — + no CDN links, no remote fonts, no ``. This is what lets a + template publish in one request with no asset-upload step. (A quick check: + the file should contain no `http://` or `https://` resource references.) +2. **Mark editable regions** with `` comments + so an agent knows exactly what to swap for the user's real content. +3. **Renders standalone.** Opening the raw file in a browser should look good as a + live preview, with sensible placeholder content already in place. +4. **Register it in *both* catalogs**, keeping the existing column format: + - the table in [`assets/templates/README.md`](assets/templates/README.md) + (use case + when to offer it), and + - the shorter table in [`SKILL.md`](SKILL.md) (the `…make a presentation` + phrasing). +5. **Keep it original.** Templates are original work created for this skill. + +After adding a template, run `mise run validate` and open the file in a browser to +confirm it renders. + +## Evals + +The skill's behavior is measured by the cases in [`evals/`](evals/). If your +change affects how the skill behaves (not just docs), consider adding or updating +a case in `evals/evals.json`. See [`evals/README.md`](evals/README.md) for the +setup and how cases are graded. + +## Pull requests + +- Keep PRs **focused** — one logical change per PR is easier to review and merge. +- Use a clear title and describe **what** changed and **why**. +- For template or behavior changes, confirm `mise run validate` passes and note it + in the PR. +- Link the issue your PR addresses (e.g. `Closes #12`). + +## Reporting bugs + +Open an issue with: what you did, what you expected, and what actually happened. +For publishing problems, include the request you made and the API response (but +**never paste an `update_key`** — it's a secret write credential). + +Thanks again for helping make `html` better!