[Feature Request] add first-class Skill selection with extraSkills and --skill

[colinaaa]

Background

create-rstack already supports extending the project creation flow through extraTools, which works well for copying templates, merging package.json, and running extra commands.

We want to add a separate first-class Skill step during project creation, so selected skills can be installed into the new project's .agents/skills/ directory via the skills CLI, instead of continuing to model this capability as part of tools.

The goal is to let wrappers such as create-rsbuild, create-rspack, and create-rslib expose built-in Skill options, while also supporting non-interactive selection through a --skill CLI flag.

Goal

Add a new Skill extension layer to create-rstack, parallel to tools, including:

• an extraSkills API
• a --skill CLI flag
• a dedicated Skill selection step in the create flow
• installation into project-local .agents/skills/ via the skills CLI

Proposed API

Argv

Add:

type Argv = {
  ...
  skill?: string | string[];
};

create() options

Add:

type ExtraSkill = {
  value: string;
  label: string;
  source: string;
  skill?: string;
  when?: (templateName: string) => boolean;
  order?: "pre" | "post";
};

create({
  ...,
  extraSkills?: ExtraSkill[],
});

Field meanings

• value: unique identifier used by CLI args and interactive prompts
• label: prompt label
• source: source passed to skills add, such as GitHub shorthand, repo URL, or git URL
• skill: the single skill name installed by this option
• when: optional template-based filter
• order: controls prompt ordering

Each ExtraSkill represents one selectable skill option.

skill can remain optional so wrappers can still point source at a repo or subpath that already resolves to a single skill, but the intended model is one ExtraSkill -> one installed skill.

CLI Design

Add:

--skill <skill>

Behavior should match --tools:

• support --skill foo
• support --skill foo,bar
• support repeated flags, e.g. --skill foo --skill bar

Here foo / bar map to extraSkills[].value, rather than exposing raw repo URLs directly.

Prompt Flow

The current flow is roughly:

1. Project name
2. Template
3. Tools
4. Copy template
5. Run tool actions / commands
6. Generate AGENTS.md

Suggested new flow:

1. Project name
2. Template
3. Skills
4. Tools
5. Copy template
6. Install skills
7. Run tool actions / commands
8. Generate AGENTS.md

Rationale:

• Skills are a distinct concept and should appear as a first-class step
• Skill installation requires the target directory to exist, so execution should happen after template files are copied

Installation Strategy

The first version should use the skills CLI rather than depending on any internal, non-public programmatic API.

For each selected ExtraSkill, run one command inside the generated project directory, for example:

npx skills add <source> --agent universal --yes --copy [--skill <name>]

Default behavior should be fixed:

• always pass --agent universal
• always pass --yes
• always pass --copy

Rationale:

• --agent universal ensures installation goes to project-local .agents/skills/
• --yes avoids additional confirmation prompts inside scaffold flow
• --copy produces stable, commit-friendly, reproducible output

Non-interactive Behavior

• if --skill is explicitly provided, resolve skills directly and skip the Skill prompt
• if --dir and --template are provided but --skill is not, skip Skill selection by default
• only show the Skill multiselect prompt in interactive mode

Error Handling

The first version should be fail-fast:

• if any selected Skill installation fails, abort the create flow
• the error should include:
  • value
  • source
  • the actual executed command
• do not attempt rollback

Rationale: Skill installation is an explicit user-selected step, and continuing after failure would leave the generated project in a partially configured state.

Help Output

Add to --help:

--skill <skill>        add skills, comma separated

Also add a new section:

Optional skills:
  ...

This should be displayed alongside Optional tools.

Testing

Suggested coverage:

1. --skill argument parsing

• single value
• comma-separated values
• repeated flags

2. when(templateName) filtering

• only matching skills are shown and installed

3. prompt skipping behavior

• skip Skill prompt when --dir + --template + no --skill

4. installation command generation

• verify skills add is called correctly
• verify --agent universal --yes --copy is always included
• verify --skill <name> is appended when ExtraSkill.skill is set

5. help output

• includes --skill
• includes Optional skills

Notes / Constraints

• v1 does not support entering arbitrary repo or URL values directly in the prompt; custom sources should come from wrapper-defined extraSkills
• v1 does not expose agent selection; everything installs into .agents/skills/
• v1 should not depend on internal JS APIs from skills, to avoid coupling to non-public interfaces
• v1 assumes one selectable ExtraSkill corresponds to one installed skill

Open Questions

• should --skill "" behave like --tools "" and explicitly skip selection?
• should the final scaffold output include a note listing which skills were installed?