package-registry
Skill8 starsChanged 8 months agoMITView on GitHub
Documentation guidance for projects published to npm and PyPI package registries. Covers metadata fields that affect registry pages, README cross-renderer compatibility, trusted publishing, provenance badges, and audit checks. Use when a project has package.json or pyproject.toml and is published publicly.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- llms-full.txtllms.txt
- llms.txtllms.txt
- api-referenceSkill
- changelogSkill
- doc-refreshSkill
- docs-verifySkill
- feature-benefitsSkill
- geo-optimisationSkill
- launch-artifactsSkill
- llms-txtSkill
- pitchdocs-suiteSkill
- platform-profilesSkill
- public-readmeSkill
- roadmapSkill
- user-guidesSkill
- visual-standardsSkill
- pitchdocsSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 63
Avoid heading anchor links: if PyPI rendering matters — broken on PyPI
- Very specific: line 96
Check if repository.url (npm) or [project.urls].Repository (PyPI) matches the actual GitHub repo URL
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Package Registry Documentation Guidance
When This Applies
These checks are conditional — only run when the project is published to a package registry.
| File Present | Registry | Action |
package.json | npm (npmjs.com) | Check npm metadata fields, badge templates |
pyproject.toml | PyPI (pypi.org) | Check PyPI metadata fields, Markdown compatibility |
| Both | npm + PyPI | Check both; cross-renderer compatibility is critical |
Detection:
[ -f "package.json" ] && echo "npm project detected"
[ -f "pyproject.toml" ] && echo "PyPI project detected"npm Registry Metadata
The README displayed on npmjs.com comes from the published tarball, not live from GitHub. Changes to your README on GitHub do not update the npm page until you publish a new version.
See SKILL-reference.md for the full package.json field table and always-included files list.
PyPI Registry Metadata
See SKILL-reference.md for the full pyproject.toml field table, well-known URL labels, and PEP 639 SPDX licence guidance.
Verified vs Unverified Details
PyPI's sidebar splits project information into two sections:
- Verified details (green checkmark): URLs verified through Trusted Publisher. GitHub statistics (stars, forks) only shown here.
- Unverified details: URLs and metadata that cannot be automatically verified.
Configuring a Trusted Publisher automatically verifies the repository URL.
README Cross-Renderer Compatibility
READMEs render on multiple platforms. What works on GitHub may break on npm or PyPI.
| Markdown Feature | GitHub | npm | PyPI | Workaround |
Heading anchors (#section) | Yes | Yes | No | Use full URLs to GitHub README |
Relative images (./docs/img.png) | Yes | No | No | Use absolute raw.githubusercontent.com URLs |
GitHub callouts ([!NOTE]) | Yes | No | No | Use bold text or blockquotes |
<details>/<summary> | Yes | Yes | Unreliable | Avoid for critical content |
colspan/rowspan in tables | Partial | Partial | No | Use simpler table structures |
<div align="center"> | Yes | Yes | No | Acceptable loss; PyPI strips most HTML alignment |
| Mermaid diagrams | Yes | No | No | Use pre-rendered SVG/PNG images |
Task lists (- [ ]) | Yes | Yes | No | Use bullet lists with emoji checkmarks |
| Footnotes | Yes | No | No | Use inline parenthetical notes |
Key Rules for Multi-Renderer READMEs
- Always use absolute URLs for images — relative paths break on both npm and PyPI
- Avoid GitHub-specific callouts (
[!NOTE],[!WARNING]) — plain text elsewhere - Avoid heading anchor links if PyPI rendering matters — broken on PyPI
- Avoid
<details>/<summary>for critical content — unreliable on PyPI - Test before publishing:
twine check dist/*validates PyPI README rendering
Solving GitHub vs PyPI Differences
For Python projects needing optimised READMEs on both platforms, consider hatch-fancy-pypi-readme:
- Assembles PyPI READMEs from fragments
- Runs regex substitutions to transform GitHub-specific content
- Converts relative links to absolute links
Trusted Publishing and Provenance
This section covers documentation-relevant aspects. The plugin does NOT create publish workflows (that's DevOps).
npm Trusted Publishing
- OIDC trusted publishing went GA July 2025 — replaces long-lived tokens entirely
- Classic tokens permanently revoked December 2025; granular tokens max 90 days
- Publishing with
--provenanceflag adds a Sigstore badge on npmjs.com linking to the exact source commit and build workflow - Requires
id-token: writepermission in GitHub Actions repository.urlin package.json must exactly match the GitHub repo URL (case-sensitive)
PyPI Trusted Publishing
- Trusted Publisher since April 2023 — first major registry to support OIDC
- Digital attestations (PEP 740) since November 2024 — Sigstore signing for package files
- "Verified details" sidebar badge appears automatically when trusted publisher is configured
- Repository URL in
[project.urls]must match the GitHub repo for verification pypa/gh-action-pypi-publishhandles publishing when configured as a trusted publisher
What to Audit (Not Configure)
- Check if
repository.url(npm) or[project.urls].Repository(PyPI) matches the actual GitHub repo URL - Flag opportunity to add provenance/attestation badges to README if not present
- Link to trusted publishing setup docs in audit output
Registry-Specific Badges
See SKILL-reference.md for npm and PyPI badge templates and recommended badge order.
Audit Checklist
See SKILL-reference.md for the full npm and PyPI audit checklists.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.