---

name: app-entry-creator description: Create Navidrome client app catalog entries from a URL. This skill should be used when the user provides a URL and wants to add an app to the Compatible Client Apps catalog. It automates discovering app metadata, downloading screenshots, and generating the index.yaml file.

App Entry Creator

This skill creates complete app entries for the Navidrome Compatible Client Apps catalog by analyzing a provided URL and discovering all relevant information automatically.

When to Use

Use this skill when:

• User provides a URL and wants to create a new app entry
• User mentions adding an app to the catalog
• User wants to create an entry in assets/apps/

Workflow

Step 1: Analyze the Provided URL

Determine the URL type and extract initial information:

Step 2: Discover Related URLs

From the initial URL, find all related resources:

1. From GitHub repos: Look for:

   • Website URL (in repo description or README)
   • App store links (Play Store, App Store) in README
   • Docker images (in README or packages)
   • Screenshots in README or /screenshots, /images, /docs folders

2. From app websites: Look for:

   • GitHub/source repository link
   • App store badges/links
   • Docker installation instructions

3. From app stores: Look for:

   • Developer website
   • GitHub link in description

Step 3: Determine Open Source Status

If the app has a GitHub/GitLab repository, determine if it's truly open source:

How to check:

1. Visit the repository URL
2. Look at the file list - are there actual source code files?
3. Check for a LICENSE file - is it an open source license (MIT, GPL, Apache, etc.)?
4. If the repo only has Releases with no source, it's a releases-only repo

Default behavior:

• If repoUrl is set and isOpenSource is omitted → treated as open source
• Only add isOpenSource: false when you've confirmed the source is NOT publicly available

Step 4: Determine API Support

Check documentation/README for mentions of:

• "OpenSubsonic" → api: OpenSubsonic
• "Subsonic API" or just "Subsonic" → api: Subsonic
• "Navidrome API" or Navidrome-specific features → api: Navidrome

Default to Subsonic if unclear but the app claims Subsonic compatibility.

Step 5: Identify Platforms

Map discovered information to platforms:

Step 6: Download Screenshots

1. Find screenshot sources (in priority order):

   • App store listings (highest quality)
   • README screenshots
   • /screenshots or /images folder in repo
   • App website gallery

2. Download images using terminal commands:

   Copycd assets/apps/<app-name>
   curl -L -o thumbnail.png "<image-url>"
   curl -L -o screen1.png "<image-url>"
   

3. Skip these image types:

   • Small icons/logos (< 200px)
   • Badges (build status, download counts)
   • Diagrams/flowcharts
   • Social media preview images

4. Run the conversion script:

   Copynpm run convert:images <app-name>
   

Step 7: Create the App Entry

1. Create the folder using kebab-case:

   Copymkdir -p assets/apps/<app-name>
   

2. Generate index.yaml with all discovered information following the schema in references/app-schema.json

3. Required fields (must have values):

   • name: Display name
   • url: Official website or GitHub URL
   • platforms: At least one platform
   • api: One of OpenSubsonic, Subsonic, Navidrome
   • description: 1-2 sentences (max 500 chars)
   • screenshots.thumbnail: Filename of downloaded thumbnail

4. Optional fields (include if found):

   • repoUrl: Repository URL (for release date tracking)
   • isOpenSource: Set to false if repo exists but source is not public (see Step 3)
   • isFree: Set to true if app is free
   • screenshots.gallery: Array of screenshot filenames (max 5)
   • keywords: Search terms not in name/description (max 6)

Step 8: Validate the Entry

Run validation to ensure correctness:

Copynpm run validate:app <app-name>

Fix any errors before presenting to user.

Example Workflow

Given URL: https://github.com/jeffvli/feishin

1. Fetch GitHub page → Extract: name "Feishin", description, README
2. Parse README → Find: screenshots, Docker image, web demo URL
3. Discover URLs:
   • Website: https://feishin.vercel.app/ (from README)
   • Docker: ghcr.io/jeffvli/feishin (from README)
4. Check open source status: Repo has TypeScript source code and MIT license → open source (no need to set isOpenSource)
5. Determine API: README mentions "Navidrome" → api: Navidrome
6. Identify platforms: Windows, macOS, Linux (releases), Docker, Web
7. Download screenshots from README images
8. Create entry:

   Copyassets/apps/feishin/
     index.yaml
     thumbnail.webp
     screen1.webp
     screen2.webp
   

9. Validate: npm run validate:app feishin

Output Format

After completion, present:

1. Summary of discovered information
2. The generated index.yaml content
3. List of downloaded images
4. Validation results
5. Any manual steps needed (if images couldn't be found)

References

• Schema: apps/app-schema.json - JSON Schema for validation
• Template: apps/_template/index.yaml - Example index.yaml structure
• Documentation: Adding Client Apps

Error Handling