contributing

Contributing to torch

Torch is an open playbook collection as much as it is a CLI. Every PR that adds a new site skill, fixes a selector, refines an anti-blocking layer, or improves a core skill makes the next person's scrape faster.

Upstream: github.com/agentcomputer/torch

What you can contribute

Kind	Where it lives	Typical PR size
New site skill	skills/sites/<slug>/SKILL.md	Single file
Update to a site skill	Same path, bump metadata.version	Single file
New core skill	skills/<name>/SKILL.md (+ references)	1-5 files
Improvement to a core skill	Existing skill file	Single file
Source code change	src/*.ts, bin/*	Scoped to one concern
Docs fix	README.md, SYSTEM.md	Single file

One concern per PR. Don't bundle a new site skill with a core skill rewrite — those get reviewed separately.

Skill authoring conventions

All skills in torch follow the Agent Skills spec that pi-coding-agent enforces. The loader will reject skills that don't comply.

Frontmatter

Every SKILL.md starts with YAML frontmatter:

---
name: <slug>
description: <specific, actionable description — this is what pi-coding-agent reads to decide when to route to the skill>
metadata:
  author: <your name or handle>
  version: "1.0.0"
---

Rules:

• name must match the parent directory name exactly.
• name must be ^[a-z0-9-]+$ — lowercase letters, digits, hyphens only. No dots, no underscores, no consecutive hyphens, no leading/trailing hyphen. Max 64 chars.
• description must be present and ≤ 1024 chars.
• description should be specific — it's what the agent reads to decide when to invoke the skill. "Does X" is weaker than "Does X when Y, using Z library, for targets like A, B, C".

Content

Skill content is just markdown after the frontmatter. Structure it however makes sense for the subject, but good skills share these traits: