Open-source projects do not fail discovery because the code is weak. They fail because directory cards sound like abandoned GitHub READMEs or like SaaS ads that forgot the license. Maintainers who want contributors, users, and stars need a listing that reads like a real project, not a pricing page.
This guide is for public repos you want found through curated directories. Start by browsing the FindGreatSites directory, then create an account when you are ready to submit. For a wider map of discovery platforms that still send humans, see directories that actually get you discovered.
You already compete with polished commercial tools. Your advantage is honesty: license, demo, issue tracker, and a clear job the software does. Lead with that.
What directories need from an open-source listing
Curators look for a live URL that explains the project in under a minute. A bare repo with no README screenshots and no demo link often gets deferred. Give them a homepage, docs site, or GitHub Pages demo that loads without a login wall.
License clarity matters. State MIT, Apache-2.0, GPL, or whatever you ship in plain language on the listing and on the destination page. People deciding whether they can embed your code will bounce if that answer is buried.
- Primary URL - docs or marketing page that explains the project, not only the raw code tree if the tree is noisy.
- Repo link - public GitHub (or GitLab) where issues and releases live.
- Demo - runnable example, playground, or recorded walkthrough if a live demo is heavy.
- License - named, not "see LICENSE file" alone.
If the project is a library with no UI, your listing destination can still be docs with a quickstart. Directories reward understanding, not flashy landing animations.
Activity signals help too. A recent release, an open issue board, and a CODE_OF_CONDUCT file will not appear on every directory form, but curators still open the repo. Dusty projects with last commits from three years ago get a harder sell.
Pick category like a maintainer, not like a marketer
Tool versus community is the first fork. A CLI that formats JSON belongs with developer tools. A forum theme or Discord bot framework may fit community or bot categories depending on the directory taxonomy. Choose the filter browsers already use when they hunt for your kind of project.
Avoid dumping everything into "AI" or "SaaS" because those shelves are crowded and often wrong. If your project is a static site generator, say that. Specific categories attract people who can actually use the repo.
When two categories seem fair, pick the one that matches the primary job-to-be-done on day one. Secondary use cases can live in the description, not in a forced multi-category spam attempt.
Revisit the category after a major pivot the same way commercial products do. An infra library that became a full platform may need a new shelf. Edit in place when the directory allows it.
If the directory offers tags, use two or three precise ones (language, runtime, niche) instead of ten vague buzzwords. Tags should help filtering, not recreate a keyword stuffing era.
Write copy that does not sound like SaaS
Drop growth jargon. "Unlock productivity," "all-in-one platform," and "seamless enterprise workflows" read fake next to a GPLv3 badge. Speak like a maintainer writing a good README headline.
Lead with what the software does and who should clone it. Mention language and runtime early (Python library, Rust CLI, browser extension). Include contribution posture in one short line if you want PRs: "looking for docs help" beats a vague "community driven" claim.
- Name the problem in one sentence.
- Name the artifact (library, app, plugin, template).
- Name the license and maturity (beta, stable, maintenance mode).
- Point to docs or demo as the next click.
Keep pricing language out unless you truly sell a hosted edition. If you have a dual license or paid support, say so cleanly. Do not hide commercial offers inside open-source theater, and do not hide the open core behind startup slogans.
Screenshots should show the real UI or terminal output, not stock photos. For headless tools, a short docs screenshot or architecture diagram without marketing chrome still helps.
Compare your draft to the first paragraph of your README. If the directory text is softer marketing and the README is harder truth, trust the README tone and tighten the listing to match.
Submission hygiene that keeps trust
Submit when the README has install steps that work on a clean machine. Broken quickstarts waste curator time and burn your reputation on that directory.
Use a stable canonical URL. If you bounce between vanity domains every month, listings rot. Point the directory at the URL you will keep for a year.
Do not mass-submit identical thin copy to twenty farms the same day. Pick curated discovery surfaces first, confirm the listing went live, then expand. The same discipline commercial founders use still applies; only the tone of the card changes.
Track referrals. A directory that sends issue reporters or doc readers is a win even when stars move slowly. Stars alone are a vanity metric for discovery work.
When a curator asks a clarifying question, answer with links to docs and the license file. Fast, precise replies get projects approved. Defensive marketing replies get delayed.
After you are listed: keep the card alive
Update the listing when you change the primary pitch, license, or homepage. Stale "coming soon" demos hurt more for open source than for closed betas because your audience expects to try the thing immediately.
Link the listing from your README in a modest resources section if you want reciprocity of attention. Do not turn the README into a backlink farm.
When you launch a major version, refresh screenshots and the first sentence. Version bumps are natural moments to remind directories the project is maintained.
Open-source discovery works when the card matches the repo: clear license, working demo path, honest category, and copy a contributor would respect. List where humans browse, keep the page truthful, and let the software do the convincing after the click.
