Inspiration

I own a NAS from another brand and the first thing I did was to install a Media Server app. One thing I didn't consider: some videos on my library had encoding that caused streaming issues and UGREEN's NAS might benefit from my experience.

What it does

It runs preflight checks on a NAS library's videos to prevent or troubleshoot streaming problems on your own devices: the NAS's file-agent reads each video's media information, and the assistant reports the files likely to fail, why, and what to check.

How we built it

Core

  • Format: a UGREEN Skill in Markdown only: SKILL.md plus three reference files (the trait rules, the catalogue format, the MIT licence). UGREEN's kit allows no code, scripts or runtime.
  • How it runs: the NAS assistant follows SKILL.md and hands each step to a registered agent with delegate --target file-agent --instruction '...'. The Skill never calls the NAS's tools itself.
  • What it uses: 3 delegate lines, one agent (the file-agent) and two of its tool sets:
    • ug-filesystem: listing and reading files, plus the one write;
    • ug-filemgr mediainfo: each video's media information, one file per call.

The pipeline

  1. A local-models check; it stops if the assistant is set to a cloud model.
  2. List the videos (subfolders included) and read the catalogue.
  3. Pick the videos not yet read or changed since, largest first, at most 20 a run.
  4. Read their media information and any .nfo stream details; the agent reports which fields are missing.
  5. Apply the rules against the user's devices and report.
  6. Write the catalogue after the user's yes and the platform's approval.

A second path answers "why won't this video play?" for a single file.

The rules engine (traits.md)

  • Tables for subtitles, audio, video, bitrate and container. Each row gives: the trait, how it causes trouble, the risk (likely or possible, with device conditions), the setting to check, the fix.
  • Files with several risky traits come first.
  • Evidence ranking: media information, then .nfo, then the file name, which is never enough for "likely". A missing field is reported as unknown, never guessed.

State between runs

  • playback-catalogue.md in the folder holds one semicolon-separated line per video: its traits, the source of each, the risk and its causes.
  • Runs are incremental, keyed on each file's modified time. A line is dropped only when the listing came back complete.
  • It writes only over a file whose first line is # Playback catalogue.

Robustness

  • It handles all five results an agent can return (completed, failed, cancelled, waiting for the user, waiting for approval) and tells access denied apart from an empty folder.
  • Every instruction is one shell single-quoted string, with apostrophes in film titles escaped. Tested with a shell parser, using Claude Code.
  • Everything a file returns is treated as data, never as instructions, which guards against prompt injection.

Privacy: it reads only technical descriptions, never picture or sound, and calls no outside service. UGREEN's subtitle search is an online service, so it's left out.

Validation:

  • UGREEN's static checker (kit 0.7.3) passes it with 0 errors and 0 warnings, on the package and on the unpacked ZIP.
  • A fresh Claude Code agent reviewed the rules as a video-encoding expert would, and all ten of its fixes were applied.
  • It hasn't run on a real NAS yet.

Built with: UGREEN's Skill Creation kit (its capability catalog and checker), Node.js to run the checker, and Claude Code (Anthropic) for drafting and review.

Challenges we ran into

Getting constantly reminded that a skill can only hand work to agents and can only recommend fixes instead of making them. Can't run on a schedule without additional setups, so the catalogue is its memory between runs.

Accomplishments that we're proud of

  • It turns real troubleshooting into rules a NAS can apply. Basically from what I learned file by file on my own server (failures come from combinations of traits) is now a check anyone can run on their library.
  • It's honest by design.
    • It never claims a file will certainly fail.
    • It never guesses a missing field.
    • It never states a device's specs from memory.
    • It says what it couldn't see. On a local-only NAS with a small model, that's what makes its answers trustworthy.
  • It's safe by design. It works only on local models, never opens a video's picture or sound, and makes one write, the catalogue, only after the user's yes.
  • It's clean by UGREEN's own standard and the checker passes.

What we learned

Failures come from combinations and not single issues. Movies that have image subtitles or 7.1 audio alone predicts little (from my own NAS media server experience). That's why the skill judges each file by how it fails.

To not overclaim: saying "likely, on this device" beats saying "will fail/work".

Film titles with apostrophes break the agents' instructions, which UGREEN's checker doesn't catch, so the Skill escapes them.

What's next for playback-preflight

The most important step is confirming that it actually runs on a UGREEN nas. In the future I'd look at integrating it with learning features, such as the NAS's knowledge base, so it remembers what each user's server and devices can actually play and adapts over time.

Built With

Share this project:

Updates

Submission history