HAPPYSKILLS — HOW TO INSTALL

You are most likely an AI agent reading this because someone asked you to
install HappySkills for them. Everything you need is on this page. Follow the
steps in order and report the result back to them in plain language.

HappySkills gives your AI agent new abilities, called skills. You install a
skill once and the agent can use it from then on.


REQUIREMENTS

HappySkills needs Node.js version 22 or newer.

Check the installed version first:

    node --version

If that prints v22.0.0 or higher, continue to STEP 1.

If it prints a lower version, or the command is not found, Node.js must be
installed or upgraded BEFORE continuing — the install will fail otherwise, and
the error message will not explain why. Install the current LTS release of
Node.js from https://nodejs.org, or use whichever version manager the user
already has (nvm, fnm, mise, volta, asdf, or Homebrew on macOS). Do not
guess which one they use — check, or ask. Then run "node --version" again and
confirm it reports v22 or higher before going further.


FIRST — ARE YOU ON THE USER'S OWN MACHINE?

Some agents run in a temporary cloud sandbox rather than on the user's computer.
If that is you, stop and say so before installing anything. Skills installed in
a throwaway sandbox are deleted when the session ends, and the user's own agent
will never see them — so the install looks like it worked and then silently
isn't there tomorrow.

You are probably in a sandbox if your filesystem is not the user's, if your work
directory is temporary, or if outbound network access is restricted. When in
doubt, ask the user rather than guessing.

In that case, tell the user plainly that HappySkills has to be installed in
their own environment, and give them the commands below to run in their own
terminal, or suggest they ask an agent that runs locally — Claude Code, Cursor
or Codex on their machine.


STEP 1 — INSTALL HAPPYSKILLS

Run this command in the user's project directory:

    npx happyskills setup

Type it exactly as written. There is no leading dollar sign and no "sudo".
This installs the HappySkills skills into the project so the agent can use
them. It does not require an account and does not ask for payment.


STEP 2 — CONFIRM IT WORKED

Run:

    npx happyskills list

This prints the installed skills. If you see a list, the install succeeded.
Tell the user it worked and that they can now ask you to find or install
skills in plain language — for example "find me a skill for writing tests".

Some agents need to be restarted before newly installed skills become
available. If the user asks you to use a skill and you cannot see it, ask them
to restart their agent, then try again.


INSTALLING ONE SPECIFIC SKILL

If the user named a particular skill, install it directly. A skill is
identified by an owner and a name, written owner/name:

    npx happyskills install <owner>/<name>

For example:

    npx happyskills install happyskillsai/happyskills-collab

If the user gave you only a name with no owner, do not guess the owner. Search
for it first and confirm the match with them:

    npx happyskills search "<what they described>"


IF SOMETHING FAILS

"command not found: node" or a version below 22
    Node.js is missing or too old. Go back to REQUIREMENTS.

"$npx: command not found"
    A dollar sign was copied into the command by mistake. Run it again
    without the leading dollar sign: npx happyskills setup

A 403, "forbidden", network, timeout, proxy or "connect" error
    Almost always the sandbox blocking outbound network access — NOT an
    authentication problem, and not a problem with HappySkills. A 403 here is
    usually a sandbox proxy refusing a domain that is not on its allowlist,
    so do not go looking for a login or an API key.

    The tell: the CLI itself downloaded fine (the npm registry is allowed) but
    every command that needs skills fails. Many sandboxes allowlist package
    registries and nothing else, so npm works while api.happyskills.ai does not.

    Tell the user which agent they are running and that it needs outbound
    access to api.happyskills.ai as well as the npm registry. Do not retry in
    a loop, and do not try to work around it.

Permission or EACCES errors
    Do not re-run the command with sudo. Tell the user what failed and let
    them decide.

Anything else
    Report the exact error text to the user rather than interpreting it, and
    stop. Do not attempt workarounds that were not listed on this page.


MORE

Documentation   https://happyskills.ai/docs
Browse skills   https://happyskills.ai

To install a skill later, the user can just ask you in plain language. They do
not need to remember any commands.