List codeaf in npx skills (vercel-labs/skills) once #1277 ships

[AbirAbbas]

What is asked

Get codeaf listed in npx skills, the CLI that installs Agent Skills (SKILL.md folders) into 78 coding agents. The upstream change is small: one entry in src/agents.ts, 'codeaf' in the AgentType union in src/types.ts, then their validate-agents.ts and sync-agents.ts scripts (which regenerate the README table and the package keywords).

Blocked on #1277 reaching a release

A listing claims that codeaf picks up what npx skills installs. On dev, and in every released build (v0.4.1 and earlier), that is false: nothing in internal/session reads a SKILL.md.

The reader is #1277 (Santosh). It is on santos/dev2: #1365 and #1382 merged there, and #1396 is open. internal/skills scans .codeaf/skills, .agents/skills, .claude/skills, .codex/skills, .cursor/skills and .gemini/skills in both the project and the home directory. That covers both places npx skills writes for an agent like codeaf:

• a project install: <project>/.agents/skills/<name>
• a global install: ~/.agents/skills/<name>

For an agent whose project folder is .agents/skills ("universal" upstream), installer.ts writes global installs to the shared ~/.agents/skills and never links them into the agent's own globalSkillsDir.

So this issue does not build a loader. It opens the upstream pull request once #1277 is on dev and in a release.

The entry, and why its global folder is ~/.agents/skills

// src/agents.ts, beside the other *Home constants
const codeafHome = process.env.CODEAF_HOME?.trim() || join(home, '.codeaf');

codeaf: {
  name: 'codeaf',
  displayName: 'codeaf',
  skillsDir: '.agents/skills',
  globalSkillsDir: join(home, '.agents/skills'),
  detectInstalled: async () => existsSync(codeafHome),
},

The first draft had globalSkillsDir: join(codeafHome, 'skills'), which is codeaf's own skills folder in #1277. Two reasons to declare ~/.agents/skills instead:

1. It is where a global install actually goes. The README table and skills list -g would otherwise show ~/.codeaf/skills/, a folder npx skills never writes to for codeaf.
2. npx skills remove -g deletes inside the declared folder without checking it. For every agent it targets, remove.ts runs rm -rf <globalSkillsDir>/<name> without checking that the path is a skill. With no -a, it targets every agent in its table, installed or not. ~/.codeaf/skills is also the resident's promoted-commands shelf (store.SkillsRoot), and internal/exec puts its bin/ on PATH. So once codeaf is listed with that folder, anyone removing a skill named bin, or one that shares a name with a promoted command, deletes that folder under ~/.codeaf, even if they installed the skill for a different agent. Declaring ~/.agents/skills keeps npx skills out of ~/.codeaf entirely. Cline and Dexto declare the same folder.

skills add -g -a codeaf then shows ~/.agents/skills, and #1277's scan reads it.

Acceptance, end to end, on a codeaf release that carries #1277

• In a project, npx skills add <a public skill repo> -a codeaf -y writes .agents/skills/<name>/SKILL.md. Then codeaf in that project offers the skill: it is in the /skill picker, and a turn can use it.
• The same works with -g: the skill lands in ~/.agents/skills/<name>, and codeaf opened in any folder offers it.
• Neither install nor npx skills remove -g touches anything under ~/.codeaf.
• Upstream's own gates are green: validate-agents.ts, sync-agents.ts (README table, agent count, discovery paths, package keyword), pnpm format:check, pnpm type-check and pnpm test.

Notes

• Upstream has about 83 "add agent" pull requests open. The ones that merged recently (fx, Sarvam Code, Posit Assistant) took days to weeks, so the pull request can be opened as soon as the release exists.
• skills use <pkg>@<skill> launches only claude, codex and sarvam-code (USE_AGENT_CONFIGS in src/use.ts). codeaf can be added there later, once a skill prompt can be handed to codeaf on its command line the same way.

[AbirAbbas]

The upstream change is ready locally and not pushed. It is one commit on vercel-labs/skills main (v1.7.0) touching src/types.ts, src/agents.ts, README.md, package.json and a new tests/codeaf-agent.test.ts: 5 files, +71/-2.

Checked on Node 24, as their CI runs it:

• validate-agents.ts passes.
• sync-agents.ts puts codeaf in the README row for .agents/skills/ and ~/.agents/skills/, beside Cline, Dexto and Sarvam Code, and adds the package keyword.
• format:check, type-check and build are clean.
• pnpm test: 878 of 879 pass, including the 4 new tests. The one failure (private-repo-add-security > "falls back to normal Git authentication") fails the same way with this change stashed.

End to end, with the real CLI and a throwaway HOME:

• add -g -a codeaf writes ~/.agents/skills/<name>, and add -a codeaf writes .agents/skills/<name>. Nothing is written under ~/.codeaf.
• skills.Discover from santos/dev2 finds both installs: scope user and scope project, root .agents/skills, no warnings.
• The remove -g hazard is real. With the first-draft entry (globalSkillsDir: ~/.codeaf/skills), npx skills remove -g bin deleted a stand-in resident shelf at ~/.codeaf/skills/bin, even though the skill had been installed only for Claude Code. With ~/.agents/skills declared, that folder survives.

The upstream pull request opens once #1277 is in a codeaf release.