joyehuang/skills

A personal collection of agent skills — reusable procedural knowledge for AI coding agents (Claude Code, OpenCode, Cursor, Codex, pi, and anything that speaks the SKILL.md convention).

This is the canonical, unified skills repo. Everything previously scattered across joyehuang/joye-skills and the local pi runtime (~/.agents/skills/) now lives here. See MERGE-NOTES.md for what came from where.

skills/
├── <skill-name>/          # portable skills — one directory per skill, at the repo root
│   └── SKILL.md           # required: YAML frontmatter (name, description) + instructions
├── personal/              # machine-specific skills mirrored from the local pi agent
│   └── <skill-name>/SKILL.md
├── MERGE-NOTES.md
└── README.md

Two tiers, on purpose:

• Root level = portable. Anything installable by a stranger with npx skills add. No hardcoded absolute paths, no assumptions about this machine.
• personal/ = mine. Skills wired to my own setup (local paths under ~/.agents/, credential files under ~/.config/, my Cloudflare R2 bucket, my herdr conventions). Kept in version control so it's backed up and diffable, deliberately not at the root so npx skills add joyehuang/skills doesn't push my personal workflow into anyone else's agent.

Root layout is flat and unchanged from before the merge, so existing npx skills add joyehuang/skills/<skill-name> commands keep working.

• Directory name == name: in the SKILL.md frontmatter == the slug users type. Lowercase, hyphenated.
• SKILL.md is required and is the entry point. Frontmatter carries name and description; the description is what an agent matches against, so write it as trigger phrases, not a summary.
• Optional argument-hint: for slash-command style skills, disable-model-invocation: true for ones that should only run when explicitly invoked.
• Supporting files go in conventional subdirectories: scripts/ (executables), references/ and rules/ (long-form docs the agent reads on demand), assets/ (images, fonts, components), templates/, examples/, evals/.
• Keep SKILL.md short; push detail into references/ so it's only loaded when needed.

# a single skill
npx skills add joyehuang/skills/<skill-name>

# everything at the root
npx skills add joyehuang/skills

# see what's in the repo
npx skills add joyehuang/skills --list

The pi agent auto-discovers skills from ~/.agents/skills/. Each entry is a directory (or a symlink to one) containing a SKILL.md; pi reads the frontmatter name/description at startup and loads the body only when the description matches what you're asking for.

Current live setup on this machine:

~/.agents/skills/
├── ego-browser -> ~/.local/share/ego/ego-skills   # symlink, owned by the ego app — not vendored here
├── herdr-workflow/                                # mirrored to personal/herdr-workflow
├── publish-artifact/                              # mirrored to personal/publish-artifact
└── web-search/                                    # mirrored to personal/web-search

The three mirrored ones are copies, not moves — the live pi setup is untouched and still authoritative. To make this repo the single source of truth later, replace each live directory with a symlink:

# optional, one skill at a time; verify pi still sees it before doing the next
mv ~/.agents/skills/web-search ~/.agents/skills/web-search.bak
ln -s ~/dev/skills/personal/web-search ~/.agents/skills/web-search

Note publish-artifact/scripts/ needs its npm dependency installed at the deployed location (npm install in that directory; node_modules/ is gitignored). ego-browser is third-party and updated by the ego app itself — leave the symlink alone.

Claude Code uses a different path (~/.claude/skills/ globally, .claude/skills/ per project); the same symlink trick works there.

Apache License 2.0, except terminal-slide-deck, which keeps the MIT license it shipped under in joye-skills (terminal-slide-deck/LICENSE). screenshot/ carries its own upstream Apache-2.0 notice.