Why
Tutorials teach you to code. Nothing teaches you to develop: read a stranger's codebase, find
your way round an issue tracker, get a pull request merged by someone who doesn't know you.
Meanwhile millions of open issues sit on GitHub waiting for exactly that person.
SkillIssues connects the two. It keeps every open issue of hundreds of thousands of active
repositories fresh, works out which ones fit you, helps you set up a workspace, and pays you XP
when GitHub says your fix was merged.
Features
- Every open issue, fresh: ~8 million issues from every public repository with 25+ stars
pushed in the last two years, kept current from GitHub's own event stream
- For you: a feed that weighs your languages, level and interests, how doable an issue is,
and how long it has waited. Every repository gets one slot, and stars never count
- Honest difficulty: read from the repository's own labels (
good first issue,
difficulty/easy, …). No label means unknown, never easy
- A beginner's checklist on every issue: labelled, described, unassigned, no open pull
request already, recent, short discussion
- Search and filters: by repository, title, language or tech, labels, topics and comment
count, with results balanced so one kind of match can't drown the rest
- XP for real merges only: base XP by difficulty, bonuses for old issues and clean reviews,
levels, streaks, badges, quests and learning paths. Opening pull requests earns almost nothing,
so spamming maintainers gets you nowhere
- "I'm working on this": claim an issue so other SkillIssues users leave it to you
- A desktop app that forks, clones, branches, commits, pushes and opens the pull request
with your own GitHub account, then opens VS Code
- Themes: twelve built-ins (Catppuccin, Dracula, Nord, Gruvbox, Tokyo Night, Rosé Pine…),
or write your own in TOML and share it
- Private by design: the server never holds your GitHub token, not even encrypted. Public
profiles are opt-in
- Free, all of it: no plans, no ads, no paywalled features. If you have money for open source,
the site points you at the maintainers to sponsor instead
- Easy on the eyes: dark by default, and a light mode with warm, slightly dimmed paper for
long reading
- Watch it run: SkillIssues Live draws every request, query
and crawled page moving through the system, in real time, with anything of yours turned into
symbols
Get it
On the web: skillissues.dizziedbliss.lol. Browse
without an account; sign in with GitHub to save issues, claim them and earn XP.
On the desktop: download from the download page
or the latest release. The app asks
before it downloads an update, every time.
Run SkillIssues-Installer.exe. It downloads the newest version from this repository's releases,
checks it against the release's SHA-512, and installs it, for you or for everyone on the PC. Run it
again later to update, repair or remove SkillIssues. No internet while installing? The release also
has SkillIssues-Setup-<version>.exe, the full offline installer.
Neither is code-signed yet, so SmartScreen will warn about an unrecognised app. Choose
More info → Run anyway.
Open the .dmg (Apple silicon) and drag SkillIssues to Applications.
The app isn't signed, so the first time, right-click it and choose Open. Updates open the
release page instead of installing themselves.
chmod +x SkillIssues-*.AppImage
./SkillIssues-*.AppImage
Where your system has no keyring, the app keeps your sign-in in memory only and asks again each
launch. It never writes a token to disk unencrypted.
[!WARNING]
Side effects may include merged pull requests, maintainers who know your name, and an
uncontrollable urge to fix "just one more" good first issue. If symptoms persist, open
a discussion and tell the rest of us.
How it works
flowchart LR
Kaggle[/"repository dataset"/] -->|repoimport| PG[("Postgres")]
Search[/"GitHub search"/] -->|discovery| Ingestd
Archive[/"GH Archive<br/>hourly events"/] --> Ingestd
GH["GitHub GraphQL"] <-->|crawl| Ingestd["ingestd"]
Ingestd --> PG
PG --> API["go-api"]
API --> Web["web · Vercel"]
API --> Desktop["desktop · Electron"]
Desktop -->|"fork, push, PR<br/>with your token"| GH
ingestd keeps the catalog. Repositories come from a public dataset and from GitHub
search. Their open issues come from a crawl that commits each page together with its bookmark,
so a crash never skips one. Changes arrive from GH Archive's hourly event files, which cost no
API budget. Every eligible repository gets the same treatment: there's no priority queue for
big projects.go-api serves the catalog in index order, so page 500 costs the same as page 1. It holds
no GitHub credential at all.- The web app and the desktop app run the same screens. Issue descriptions are read from
GitHub in your browser and rendered through a sanitiser, because anyone can write one.
- Every number (page sizes, intervals, thresholds, XP amounts) is a live setting, changeable
on the running system.
The full picture: ARCHITECTURE.md and
the ingestion design.
Run it yourself
You need Docker with Compose v2, and a GitHub token for GITHUB_TOKEN. The crawler reads only
public data, so a token with no scopes is enough.
git clone https://github.com/dizziedbliss/SkillIssues.git
cd SkillIssues
cp .env.example .env # set GITHUB_TOKEN; everything else has a dev default
docker compose up -d --build
docker compose ps # migrate and metrics-role exit 0; everything else running
The migrate service applies the schema; nothing needs setting up by hand.
The catalog starts empty. Repositories come from the Kaggle dataset
github-repository-metadata-with-5-stars (repo_metadata.json, ~3 GB). Put it at
data/repo_metadata.json, then:
cd backend
DATABASE_URL=postgresql://skillissues:skillissues@localhost:5432/skillissues \
go run ./cmd/repoimport --file ../data/repo_metadata.json
Only eligible repositories are stored. A full pass takes about 16 minutes and is safe to re-run;
ingestd starts crawling their issues on its own.
docker compose logs -f go-api ingestd
You'll need Node.js 22 and npm 11. web, desktop and packages/* are one npm workspace with
one lockfile, so install once, at the root:
npm ci
cd desktop
npm run dev # expects the API at http://localhost:8000
Go 1.27 (what CI and the images use; go.mod needs 1.26 or later):
cd backend && go vet ./... && gofmt -l . && go build ./... && go test -short ./...
cd web && npm run typecheck && npm run build
cd desktop && npm run check && npm run build && npm test
The database tests run against a migrated Postgres when TEST_DATABASE_URL is set, and pass
with Redis stopped.
Configuration
Three layers: bootstrap values and secrets come from the environment (.env), and everything
operational lives in the settings table, validated by the database and changeable while the
system runs:
# read everything
curl localhost:8000/admin/config -H "Authorization: Bearer $ADMIN_SYNC_TOKEN"
# give the crawler four workers, right now, no restart
curl -XPUT localhost:8000/admin/config/ingest.routine_workers \
-H "Authorization: Bearer $ADMIN_SYNC_TOKEN" -d '{"value": 4}'
Every change is recorded in settings_audit. Every key, with its default and bounds:
docs/settings.md.
[!TIP]
psql works too, and hits the same validation trigger. That's handy when a bad value has made
the API itself unhealthy.
Themes
A theme is a TOML file of design tokens, plus an optional stylesheet. Start from any built-in and
change only what you name:
[meta]
name = "Night shift"
base = "tokyo-night"
[colors]
accent = "#ff7a59"
[dark]
background = "#0b0d14"
Write one in Settings → Themes: the editor checks it as you type and shows a live preview.
Share it, and it appears in the Community tab. Stylesheets are checked against an allowlist on
the server and in your browser, because a theme somebody shares is code running on your page.
The full reference: the themes guide.
Documentation
Contributing
Bug reports, fixes, docs, tests, translations and accessibility improvements are all welcome.
Read CONTRIBUTING.md and the Code of Conduct, then open
an issue (there's a form for each kind, including "my repository isn't indexed" and "exclude my
repository") or a pull request.
SkillIssues is built with AI coding tools, mostly Claude, with every change directed, read and
tested by a person before it merges. You're welcome to use them too: Using AI tools in
CONTRIBUTING.md has the rules, and CLAUDE.md is the brief for coding agents, with a
guide in each part of the code.
Found a security problem? Please don't open an issue: use
private vulnerability reporting.
See SECURITY.md.
Whatcha think?
We'd love to hear from you. Ideas, questions, a theme you're proud of, your first merged pull
request: bring them to Discussions.
License
MIT
