feat(cli): rename skills → skill (plural alias kept)

[christso]

Summary

Adopt allagents skill <subcommand> as the canonical singular form, matching gh skill and the agentskills.io ecosystem. The plural allagents skills <subcommand> remains a permanent, byte-identical alias — no deprecation warning, no breaking change.

• Rewriting the leading skills arg to skill before cmd-ts dispatch makes both invocations share the same hotPath, so they produce identical help/output (gate 2).
• Metas, JSON envelopes, examples, README, and the docs site are switched to the singular. The plural is documented as a synonym.
• --agent-help "skills X" lookups are normalized so existing automation that uses the plural still resolves.

Test plan

• bun run build
• bun test (1191 pass / 0 fail)
• Verification gate from rename: allagents skills → allagents skill (with backward-compatible plural alias) #373 (all five checks):
  • allagents skill list >/dev/null succeeds; allagents skill --help | grep 'allagents skill' matches.
  • allagents skills list >/dev/null succeeds; diff <(allagents skill 2>&1) <(allagents skills 2>&1) shows no diff.
  • allagents --agent-help | jq '.commands | map(.command) | any(. == "skill list")' → true.
  • allagents --help | grep 'skill' matches.
  • grep -E '^\s*\$\s*allagents skills ' README.md returns no matches.

Closes #373

Note: overlaps with #371 on src/cli/metadata/plugin-skills.ts,
src/cli/agent-help.ts, and src/cli/commands/plugin-skills.ts. Whichever
lands second can be rebased trivially — same edits, singular vs plural.

[cloudflare-workers-and-pages]

Deploying allagents with    Cloudflare Pages

Latest commit:	6532f57
Status:	✅  Deploy successful!
Preview URL:	https://9f0adccd.allagents.pages.dev
Branch Preview URL:	https://fix-373-skill-singular.allagents.pages.dev

View logs

[christso]

Code Review: ✅ APPROVE (with non-blocking suggestions)

Approach

The implementation diverges from the issue's suggested cmds: { skill: skillsCmd, skills: skillsCmd } and instead rewrites argv pre-dispatch so cmd-ts only ever sees the singular. This is the better choice — it sidesteps any risk of conciseSubcommands mis-handling the same command object under two keys, and it guarantees gate (2) byte-identical output for free because there's only ever one hotPath.

Correctness

• src/cli/index.ts: cmds.skill: skillsCmd registration + argsWithSkillAlias[0] === 'skills' rewrite — correct, and the rewrite is positioned after extractJsonFlag/extractAgentHelpFlag so it sees positional args, not flags.
• src/cli/agent-help.ts: parallel normalization in printAgentHelp so --agent-help "skills list" resolves to the skill list meta. Consistent with the index.ts approach.
• src/cli/commands/plugin-skills.ts: skillsCmd.name = 'skill', JSON envelope command: fields, and ambiguity-hint strings (Use --plugin to specify: allagents skill <add|remove> ...) all updated consistently.
• Metadata, README, docs, quick-start, plugins guide, and cli reference all swept. The skill add re-enable tip in cli.mdx correctly documents the alias rather than the now-obsolete "shorthand for plugin skills add" wording.

CLAUDE.md compliance

• Conventional commit (feat(cli): ...) ✓
• No Co-Authored-By ✓
• Tests updated ✓

Verification gate

All five checks from #373 appear satisfied by the diff.

Overlap with #379

The PR body correctly flags overlap with #371/#379. Whichever lands second needs a rebase — the metadata command: values and JSON envelope strings will conflict (plural vs singular). Recommend merging #379 first (smaller, narrowly-scoped), then rebasing #380 to overwrite those strings with the singular. After rebase the net diff from #379 → #380 on those files is just skills → skill.

Non-blocking suggestions

1. Add a unit test for the alias normalization — the new argv rewrite in index.ts (and the matching one in printAgentHelp) is the core user-facing behavior of this PR, but only verified manually via the test-plan checklist. A small unit test would lock it in:

test('rewrites leading "skills" to "skill"', () => {
  expect(normalizeSkillsAlias(['skills', 'list'])).toEqual(['skill', 'list']);
  expect(normalizeSkillsAlias(['skill', 'list'])).toEqual(['skill', 'list']);
  expect(normalizeSkillsAlias(['workspace', 'sync'])).toEqual(['workspace', 'sync']);
  expect(normalizeSkillsAlias([])).toEqual([]);
});

This would also test that skills mid-args (e.g. --agent-help skills) isn't accidentally rewritten — currently safe because [0] === 'skills', but a test pins that behavior.

2. Extract the duplicated normalization — the same [0] === 'skills' ? ['skill', ...slice(1)] : args pattern appears in both src/cli/index.ts and src/cli/agent-help.ts::printAgentHelp. CLAUDE.md notes "three similar lines is better than a premature abstraction", and here it's only two call sites with two-line logic. Acceptable to leave as-is, but if you do extract, a normalizeSkillsAlias helper would also enable suggestion #1.

Not blocking — the immediate behavior is correct and the verification gate is satisfied.