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:

   bash

   cd 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:

   bash

   npm run convert:images <app-name>
   

Step 7: Create the App Entry

1. •

   Create the folder using kebab-case:

   bash

   mkdir -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:

npm 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:
   code

   assets/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