universal-emoji-parser

# AI Agent Skills, Commands & Subagents — Universal Emoji Parser This directory contains **skills** (deep-dive procedures), **slash commands** (short reusable invocations), and **subagents** (specialized personas) tuned for TypeScript library work in this repo. > **For non-Claude hosts** (Cursor, Codex, Gemini, GitHub Copilot): the markdown files in [`commands/`](commands/) and [`skills/`](skills/) are plain procedures. Invoke them by name (`#regenerate-emoji-lib` or "run regenerate-emoji-lib") — the agent will read the matching file and follow it step-by-step. > > The folder is also reachable as `.claude/` — a symlink to this directory — so Claude Code's native conventions (`.claude/commands/`, `.claude/skills/`, `.claude/agents/`) work out of the box. ## Layout ``` .agents/ ← (.claude/ symlinks here) ├── README.md # This file — full catalog ├── commands/ # One file per slash command (short, procedural) │ ├── regenerate-emoji-lib.md │ ├── add-special-case.md │ ├── write-tests.md │ ├── fix-build.md │ ├── bump-deps.md │ ├── release-npm.md │ └── check-html-output.md ├── skills/ # Deep-dive procedures and conventions (richer than commands) │ ├── emoji-parser-conventions.md │ ├── emoji-data-pipeline.md │ ├── npm-publish-walkthrough.md │ └── typescript-strict-style.md └── agents/ # Specialized subagent personas ├── parser-architect.md ├── emoji-data-curator.md ├── test-author.md ├── dependency-auditor.md ├── release-engineer.md └── doc-writer.md ``` ## Slash commands Reusable procedures invoked by slash command (or `#` in non-Claude hosts). | Command | Purpose | File | | ----------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `/regenerate-emoji-lib` | Regenerate `src/lib/emoji-lib.json` from `emojilib` + `unicode-emoji-json` | [commands/regenerate-emoji-lib.md](commands/regenerate-emoji-lib.md) | | `/add-special-case` | Add a keyword include/exclude override to `EMOJIS_SPECIAL_CASES` | [commands/add-special-case.md](commands/add-special-case.md) | | `/write-tests` | Author Mocha + Chai tests for a parsing bug or new feature | [commands/write-tests.md](commands/write-tests.md) | | `/fix-build` | Diagnose a failing TypeScript / Webpack / Mocha build | [commands/fix-build.md](commands/fix-build.md) | | `/bump-deps` | Update one or more npm dependencies safely (respects `.ncurc.json`) | [commands/bump-deps.md](commands/bump-deps.md) | | `/release-npm` | Walk through a manual release if CI is unavailable | [commands/release-npm.md](commands/release-npm.md) | | `/check-html-output` | Verify the HTML output contract for a given input | [commands/check-html-output.md](commands/check-html-output.md) | ### How to invoke | Host | Prefix | Example | | --------------- | ------------ | ----------------------- | | Claude Code | `/` (native) | `/regenerate-emoji-lib` | | OpenAI Codex | `#` | `#regenerate-emoji-lib` | | Cursor AI | `#` | `#regenerate-emoji-lib` | | Gemini / others | `#` | `#regenerate-emoji-lib` | When invoked, the agent **must**: 1. Look up the command name in this README 2. Read the linked command file end-to-end 3. Follow the steps exactly — the file IS the spec 4. If the procedure asks for confirmation or input, pause and ask; don't improvise ## Skills Richer, longer procedures that explain conventions and pipelines. Use these when the user asks "how does the catalog work?" or "how do I publish?" rather than "run X". | Skill | Purpose | File | | -------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------ | | `emoji-parser-conventions` | Deep dive on the parse pipeline, regex caching, dual-export shape | [skills/emoji-parser-conventions.md](skills/emoji-parser-conventions.md) | | `emoji-data-pipeline` | Step-by-step regeneration of the catalog from upstream | [skills/emoji-data-pipeline.md](skills/emoji-data-pipeline.md) | | `npm-publish-walkthrough` | Full release flow including GitHub Actions internals | [skills/npm-publish-walkthrough.md](skills/npm-publish-walkthrough.md) | | `typescript-strict-style` | TS rules enforced by `tsconfig.json` + ESLint | [skills/typescript-strict-style.md](skills/typescript-strict-style.md) | Skills don't have a slash-command form. They're read by agents as reference material. ## Subagents (specialized personas) Adopt the persona described in the file when the task matches. | Subagent | Domain | File | | -------------------- | --------------------------------------------------------------- | ------------------------------------------------------------ | | `parser-architect` | Public API shape, source-file placement, dual-export discipline | [agents/parser-architect.md](agents/parser-architect.md) | | `emoji-data-curator` | The catalog, `EMOJIS_SPECIAL_CASES`, regeneration pipeline | [agents/emoji-data-curator.md](agents/emoji-data-curator.md) | | `test-author` | Mocha + Chai specs, regression tests, regenerator handling | [agents/test-author.md](agents/test-author.md) | | `dependency-auditor` | `package.json` changes, `.ncurc.json`, license/CVE checks | [agents/dependency-auditor.md](agents/dependency-auditor.md) | | `release-engineer` | Webpack config, GitHub Actions, npm publish, GitHub releases | [agents/release-engineer.md](agents/release-engineer.md) | | `doc-writer` | Keeping `AGENTS.md`, `docs/`, and `README.md` synchronized | [agents/doc-writer.md](agents/doc-writer.md) | ## Adding a new skill, command, or subagent 1. Create the markdown file under `commands/<name>.md`, `skills/<name>.md`, or `agents/<name>.md` 2. Follow the structure of an existing file (frontmatter with `name` and `description`, then sections) 3. Add a row to the appropriate table above 4. Mention the new entry in [`../AGENTS.md`](../AGENTS.md) "Skills, Commands & Subagents" section 5. Commit with `feat: add <name> command` / `feat: add <name> skill` / `feat: add <name> subagent` ## Conventions - **Commands** are **procedural** — numbered steps, exact commands, file paths, copy-pasteable code. Aim for under 200 lines - **Skills** are **deep-dives** — they explain _why_, not just _how_; richer than commands; reference docs/ files freely - **Subagents** are **persona-based** — what they care about, what they don't, how they decide - All three must be **self-contained at the file level** — an agent reading only the file should be able to execute it - **Cross-link** to `docs/` rather than duplicating content - **Frontmatter** at the top of every file: ```markdown --- name: <command-or-skill-or-agent-name> description: One-line summary used by agent hosts to surface the file --- ```