OpenParable
Skip to content
← Back to skills

Implementing Extra

Development
implementing-extra

Implementing Extra is an Agent Skill for development published in the arnaudmiribel/streamlit-extras repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guides implementation of new streamlit-extras from spec to verification. Use when adding a new extra, creating a Streamlit component, or when the user says "implement extra", "new extra", or "add extra".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/arnaudmiribel/streamlit-extras/blob/HEAD/.claude/skills/implementing-extra/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/implementing-extra, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Implementing a New Extra

Multi-step workflow for adding new extras to streamlit-extras. Always read and follow src/streamlit_extras/AGENTS.md first.

Workflow Checklist

Copy this checklist and track progress:

Implementation Progress:
- [ ] Step 1: Write product spec in work-tmp/
- [ ] Step 2: Decide component type
- [ ] Step 3: Implement the extra
- [ ] Step 4: Verify implementation

Step 1: Write Product Spec

Create a spec in work-tmp/<extra_name>-spec.md before coding.

Use the template in references/spec-template.md which follows Streamlit's product spec format:

  1. Summary - 2-3 sentences describing the extra
  2. Problem - Motivation, user requests, pain points
  3. Proposal - API design, behavior, examples
  4. Out of Scope - Features not included in v1

Follow the Streamlit API design principles from: https://raw.githubusercontent.com/streamlit/streamlit/refs/heads/develop/specs/AGENTS.md

Step 2: Decide Component Type

Read the decision table in src/streamlit_extras/AGENTS.md under "Choosing a Component Type".

Quick reference:

RequirementType
No UI/frontend neededpure python
HTML/CSS onlyst.html
Markdown + HTMLst.markdown(unsafe_allow_html)
URL in iframecomponents v1: iframe
Full HTML in iframecomponents v1: html
JavaScript execution (simple)components v2: inline
Basic JS/HTML/CSS UIcomponents v2: inline or static assets
Complex UI / React / npm depscomponents v2: react

For CCv2 components, use the /building-streamlit-custom-components-v2 skill.

Step 3: Implement

Create src/streamlit_extras/<extra_name>/__init__.py with:

  1. Main function decorated with @extra
  2. Example function for the gallery
  3. Required metadata (see references/metadata.md)

Template:

from streamlit_extras import extra

@extra
def my_extra(param: str, *, key: str | None = None) -> None:
    """One-line description.

    Args:
        param: Description.
        key: Unique key for this instance.
    """
    ...

def example() -> None:
    """Example for gallery."""
    my_extra("demo")

__title__ = "My Extra"
__desc__ = "Short description of what it does."
__icon__ = "..."  # Single emoji
__author__ = "Your Name"
__examples__ = [example]

Step 4: Verify

Run these checks before committing:

# Linting and formatting
uv run ruff check --fix
uv run ruff format

# Type checking
uv run mypy
uv run ty check

# Tests (validates metadata)
uv run pytest

For CCv2 React components, also verify the build:

# Build wheel (compiles React frontends via hatch hook)
uv build

# Check build artifacts exist
ls src/streamlit_extras/<extra_name>/frontend/build/

CRITICAL: Never commit build artifacts or lock files. The following are gitignored and must NOT be git add-ed:

  • frontend/build/ — built by CI before publishing; never commit locally-built JS bundles
  • frontend/package-lock.json — lock files are not needed in the repo
  • frontend/node_modules/ — never commit dependencies

If you accidentally staged them, remove with git rm --cached <path>.

References