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.

Layout

skills/
├── /          # 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.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/ commands keep working.

Naming and structure conventions

• 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.

Install (portable skills)

# a single skill
npx skills add joyehuang/skills/

# everything at the root
npx skills add joyehuang/skills

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

How pi loads local skills

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/