flixclusive-provider-development

name: flixclusive-provider-development description: > Comprehensive skill for building Flixclusive providers in this repository. Use this when asked to create a new provider module, implement provider capabilities (catalog/search/metadata/media links/ cross-match/tracker), wire a ProviderPlugin, add a SettingsScreen, update Gradle, debug build/deploy, or refactor provider code.

Flixclusive Provider Development Skill

This skill governs Flixclusive provider development. It is built around the provider SDK in core-stubs and the working provider implementations in this repository.

How to Use

Read every rule file before generating or editing code. Rules are in rules/ alongside this file.

CRITICAL: Correct SDK Type Names

The following aliases no longer exist or are deprecated — never use them in generated code:

ProviderPlugin capability getters are suspend

// ALL getters are suspend and return nullable types
override suspend fun getCatalogApi(context: Context): CatalogProviderApi? = catalogApi
override suspend fun getSearchApi(context: Context): SearchProviderApi? = searchApi
override suspend fun getMetadataApi(context: Context): MediaMetadataProviderApi? = metadataApi
override suspend fun getMediaLinkApi(context: Context): MediaLinkProviderApi? = mediaLinkApi
override suspend fun getCrossMatchApi(context: Context): CrossMatchProviderApi? = null
override suspend fun getTrackerApi(context: Context): TrackerProviderApi? = null

MediaMetadataProviderApi is split — not a single getMetadata

// SDK interface
interface MediaMetadataProviderApi {
    suspend fun getMovie(media: PartialMedia): Movie
    suspend fun getShow(media: PartialMedia): Show
}

getLinks uses a callback — not Flow

// SDK interface
interface MediaLinkProviderApi {
    val supportedLinkTypes: Set<MediaLinkType>
    suspend fun getLinks(
        media: MediaMetadata,
        episode: Episode? = null,
        onLinkFound: (MediaLink) -> Unit,
    )
}

Anti-patterns — Never Do These

• Do not invent SDK types or method signatures; verify from core-stubs source or API docs.
• Do not use FilmSearchItem, FilmMetadata, TvShow, PaginatedResponse, ProviderCatalog, or MetadataProviderApi in any generated code.
• Do not use Flow<MediaLink> as the return type of getLinks.
• Do not access manifest or settings in init {} blocks or property initializers — use by lazy.
• Do not create a new capability API instance on every getter call — cache via by lazy.
• Do not change a provider's id after the first release — it breaks update identity.
• Do not invent Gradle tasks; confirm from ./gradlew tasks or existing build files.
• Do not refactor code that is unrelated to the current task.
• Do not add error handling for scenarios that cannot happen in practice.

Real-World Reference Implementations

Before generating code, read the relevant sections of the working providers in this repo:

These are the canonical ground truth for patterns — not the rule files alone.

Key Principle

When in doubt — read existing code first. Check core-stubs source for every API signature you are unsure about. Never assume. Never invent. Search → read → confirm → generate.

Core SDK Reference

• Primary API docs: core-stubs docs
• Provider docs: provider-docs
• Source fallback: flixclusiveorg/core-stubs on GitHub

Provider Docs Index

Use this as a guide map when implementing or documenting a feature: