Why does my RST README look broken on PyPI but fine in Sphinx?

PyPI's renderer does not support Sphinx-specific extensions or roles like :py:func:. This skill identifies these incompatible elements and provides PyPI-friendly alternatives.

Can it help with pyproject.toml configuration?

Absolutely. The skill provides the exact TOML snippets required to link your README file and set the correct content-type in your project metadata.

How do I verify my README before uploading to PyPI?

The skill includes workflows for using 'twine check' to validate your distribution packages, ensuring your README will render correctly before you publish.

Does this skill support GitHub Flavored Markdown?

Yes, it provides specific guidance and templates for GitHub Flavored Markdown (GFM) to ensure full compatibility between GitHub, GitLab, and PyPI.

PyPI README Creator

Name: PyPI README Creator
Author: Jamie-BitFlight

byJamie-BitFlight

•

Learning & Documentation

Generates professional, PyPI-compliant README files in Markdown or reStructuredText that ensure perfect rendering across all major code hosting platforms.

The PyPI README Creator is a specialized skill designed for Python developers to streamline the creation, formatting, and validation of package documentation for PyPI publication. It manages the technical nuances of both Markdown and reStructuredText (RST), specifically addressing the limitations of PyPI's renderer regarding Sphinx extensions. By automating pyproject.toml metadata configuration and providing validation workflows via Twine, this skill ensures your project's first impression is professional and free of rendering errors on PyPI, GitHub, and GitLab.

Key Features

01Converts Sphinx-heavy documentation into PyPI-compatible RST formats

02Validates markup using Twine to prevent rendering errors before publication

03Automates pyproject.toml metadata configuration for README inclusion

0418 GitHub stars

05Generates PyPI-compliant Markdown and reStructuredText (RST) files

06Provides standardized templates for installation, quick start, and usage sections

Use Cases

01Preparing a new Python package for its initial publication on PyPI

02Converting existing Sphinx documentation into a platform-agnostic README.rst

03Troubleshooting and fixing broken README rendering on the PyPI project page

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add jamie-bitflight/claude_skills pypi-readme-creator

For use in Claude.ai and ChatGPT

Download Skill