Troubleshooting

What Skills Are (and Aren’t)

A quick guide for one of the most common points of confusion: skills are AI behavior packs, not software packages you install with Homebrew.

If you’ve asked “Why does this skill mention macOS?” or “Do I need to install this on Linux first?” — you’re not alone. This confusion shows up in #help all the time.

One-line answer: most Heyron skills are instruction files for your agent (prompt + workflow), not native apps that need apt, brew, or pip.

Skills vs software (plain English)

Skill = guidance your agent follows (how to think, structure output, run a process).
Software package = executable installed on an OS (like Homebrew tools on your own machine).
Most community skills in the Heyron library are designed to run headless in Docker.
Some skills may require API keys, but still not local package installs.

How to tell if a skill will work for you

1) Check the skill description for external dependencies

If it needs a key, it should say so clearly (example: NOTION_TOKEN, GITHUB_TOKEN).

2) Look for “headless” compatibility notes

If the skill expects desktop UI automation, it may not be a fit. If it’s prompt/process based, it usually works fine in Heyron containers.

3) Run a tiny smoke test prompt

After adding a skill, ask for a minimal output first instead of a big workflow.

Use your [skill-name] behavior and give me a 5-bullet summary of this topic: [topic].

Common mistakes

Installing random packages locally “just in case.” Usually unnecessary for skill-only workflows.
Assuming a skill is broken because it mentions tooling. It may just be optional context in the original skill docs.
Skipping environment variables. If a skill needs an API key, missing that key will look like a broken skill.

Quick self-check before opening #help

Skill name: [name] Expected behavior: [what should happen] What I tried: [prompt/test] Result: [actual output/error] API keys set (if required): [yes/no] Does this skill require local OS packages? [unknown/yes/no]

Tip: if a skill came from ClawHub, make sure metadata wrappers were stripped and only the actual skill content was copied into your library.

Bottom line: treat skills as behavior modules first. Only treat them as software install tasks when the skill explicitly requires runtime binaries.