docs: add CONTRIBUTING guide and issue/PR templates#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sdhilip200 wants to merge 1 commit into
base:main
Choose a base branch
from
Open

docs: add CONTRIBUTING guide and issue/PR templates #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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.
8 changes: 8 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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.
23 changes: 23 additions & 0 deletions .github/ISSUE_TEMPLATE/template_request.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
---
name: New template request
about: Suggest a new page template for the catalog
title: "Template: <short name>"
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.
21 changes: 21 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
<!-- Thanks for contributing! Keep PRs focused — one logical change each. -->

## What & why
<!-- What does this change, and why? Link any related issue, e.g. Closes #12 -->

## 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 `<!-- REPLACE: … -->` 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`.
82 changes: 82 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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 `<img src="https://…">`. 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 `<!-- REPLACE: short description -->` 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!
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
docs: add CONTRIBUTING guide and issue/PR templates#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sdhilip200
wants to merge
1
commit into

base:main
Choose a base branch

from

 Open


docs: add CONTRIBUTING guide and issue/PR templates
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


31 changes: 31 additions & 0 deletions
.github/ISSUE_TEMPLATE/bug_report.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

8 changes: 8 additions & 0 deletions
.github/ISSUE_TEMPLATE/config.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

23 changes: 23 additions & 0 deletions
.github/ISSUE_TEMPLATE/template_request.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
---
name: New template request
about: Suggest a new page template for the catalog
title: "Template: <short name>"
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.

21 changes: 21 additions & 0 deletions
.github/PULL_REQUEST_TEMPLATE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
<!-- Thanks for contributing! Keep PRs focused — one logical change each. -->

## What & why
<!-- What does this change, and why? Link any related issue, e.g. Closes #12 -->

## 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 `<!-- REPLACE: … -->` 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`.

82 changes: 82 additions & 0 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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 `<img src="https://…">`. 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 `<!-- REPLACE: short description -->` 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!

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs: add CONTRIBUTING guide and issue/PR templates#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sdhilip200
wants to merge
1
commit into

base:main
Choose a base branch

from

 Open


docs: add CONTRIBUTING guide and issue/PR templates
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


31 changes: 31 additions & 0 deletions
.github/ISSUE_TEMPLATE/bug_report.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

8 changes: 8 additions & 0 deletions
.github/ISSUE_TEMPLATE/config.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

23 changes: 23 additions & 0 deletions
.github/ISSUE_TEMPLATE/template_request.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
---
name: New template request
about: Suggest a new page template for the catalog
title: "Template: <short name>"
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.

21 changes: 21 additions & 0 deletions
.github/PULL_REQUEST_TEMPLATE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
<!-- Thanks for contributing! Keep PRs focused — one logical change each. -->

## What & why
<!-- What does this change, and why? Link any related issue, e.g. Closes #12 -->

## 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 `<!-- REPLACE: … -->` 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`.

82 changes: 82 additions & 0 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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 `<img src="https://…">`. 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 `<!-- REPLACE: short description -->` 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!

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs: add CONTRIBUTING guide and issue/PR templates#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sdhilip200
wants to merge
1
commit into

base:main
Choose a base branch

from

 Open


docs: add CONTRIBUTING guide and issue/PR templates
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


31 changes: 31 additions & 0 deletions
.github/ISSUE_TEMPLATE/bug_report.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

8 changes: 8 additions & 0 deletions
.github/ISSUE_TEMPLATE/config.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

23 changes: 23 additions & 0 deletions
.github/ISSUE_TEMPLATE/template_request.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
---
name: New template request
about: Suggest a new page template for the catalog
title: "Template: <short name>"
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.

21 changes: 21 additions & 0 deletions
.github/PULL_REQUEST_TEMPLATE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
<!-- Thanks for contributing! Keep PRs focused — one logical change each. -->

## What & why
<!-- What does this change, and why? Link any related issue, e.g. Closes #12 -->

## 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 `<!-- REPLACE: … -->` 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`.

82 changes: 82 additions & 0 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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 `<img src="https://…">`. 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 `<!-- REPLACE: short description -->` 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!

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
docs: add CONTRIBUTING guide and issue/PR templates#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sdhilip200
wants to merge
1
commit into

base:main
Choose a base branch

from

 Open


docs: add CONTRIBUTING guide and issue/PR templates
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


31 changes: 31 additions & 0 deletions
.github/ISSUE_TEMPLATE/bug_report.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

8 changes: 8 additions & 0 deletions
.github/ISSUE_TEMPLATE/config.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

23 changes: 23 additions & 0 deletions
.github/ISSUE_TEMPLATE/template_request.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
---
name: New template request
about: Suggest a new page template for the catalog
title: "Template: <short name>"
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.

21 changes: 21 additions & 0 deletions
.github/PULL_REQUEST_TEMPLATE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
<!-- Thanks for contributing! Keep PRs focused — one logical change each. -->

## What & why
<!-- What does this change, and why? Link any related issue, e.g. Closes #12 -->

## 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 `<!-- REPLACE: … -->` 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`.

82 changes: 82 additions & 0 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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 `<img src="https://…">`. 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 `<!-- REPLACE: short description -->` 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!

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs: add CONTRIBUTING guide and issue/PR templates#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sdhilip200
wants to merge
1
commit into

base:main
Choose a base branch

from

 Open


docs: add CONTRIBUTING guide and issue/PR templates
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


31 changes: 31 additions & 0 deletions
.github/ISSUE_TEMPLATE/bug_report.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

8 changes: 8 additions & 0 deletions
.github/ISSUE_TEMPLATE/config.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

23 changes: 23 additions & 0 deletions
.github/ISSUE_TEMPLATE/template_request.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
---
name: New template request
about: Suggest a new page template for the catalog
title: "Template: <short name>"
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.

21 changes: 21 additions & 0 deletions
.github/PULL_REQUEST_TEMPLATE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
<!-- Thanks for contributing! Keep PRs focused — one logical change each. -->

## What & why
<!-- What does this change, and why? Link any related issue, e.g. Closes #12 -->

## 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 `<!-- REPLACE: … -->` 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`.

82 changes: 82 additions & 0 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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 `<img src="https://…">`. 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 `<!-- REPLACE: short description -->` 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!

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs: add CONTRIBUTING guide and issue/PR templates#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sdhilip200
wants to merge
1
commit into

base:main
Choose a base branch

from

 Open


docs: add CONTRIBUTING guide and issue/PR templates
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


31 changes: 31 additions & 0 deletions
.github/ISSUE_TEMPLATE/bug_report.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

8 changes: 8 additions & 0 deletions
.github/ISSUE_TEMPLATE/config.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

23 changes: 23 additions & 0 deletions
.github/ISSUE_TEMPLATE/template_request.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
---
name: New template request
about: Suggest a new page template for the catalog
title: "Template: <short name>"
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.

21 changes: 21 additions & 0 deletions
.github/PULL_REQUEST_TEMPLATE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
<!-- Thanks for contributing! Keep PRs focused — one logical change each. -->

## What & why
<!-- What does this change, and why? Link any related issue, e.g. Closes #12 -->

## 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 `<!-- REPLACE: … -->` 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`.

82 changes: 82 additions & 0 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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 `<img src="https://…">`. 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 `<!-- REPLACE: short description -->` 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!

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
docs: add CONTRIBUTING guide and issue/PR templates#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sdhilip200
wants to merge
1
commit into

base:main
Choose a base branch

from

 Open


docs: add CONTRIBUTING guide and issue/PR templates
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


31 changes: 31 additions & 0 deletions
.github/ISSUE_TEMPLATE/bug_report.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

8 changes: 8 additions & 0 deletions
.github/ISSUE_TEMPLATE/config.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

23 changes: 23 additions & 0 deletions
.github/ISSUE_TEMPLATE/template_request.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
---
name: New template request
about: Suggest a new page template for the catalog
title: "Template: <short name>"
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.

21 changes: 21 additions & 0 deletions
.github/PULL_REQUEST_TEMPLATE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
<!-- Thanks for contributing! Keep PRs focused — one logical change each. -->

## What & why
<!-- What does this change, and why? Link any related issue, e.g. Closes #12 -->

## 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 `<!-- REPLACE: … -->` 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`.

82 changes: 82 additions & 0 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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 `<img src="https://…">`. 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 `<!-- REPLACE: short description -->` 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!