KWC Project Scaffold

Use this Skill as the entry point for KWC project scaffolding work. Prioritize categorizing user requirements into the following types: project initialization, component creation, page metadata creation, environment configuration, deployment, debugging.

Correct Understanding of Deliverables

Do not interpret the KWC workflow as "rendering a component locally". The core deliverables of KWC are:

The component project itself
Page metadata
```
*.page-meta.kwp
```
Target environment configuration and authentication
Environment rendering results after uploading via
```
kd project deploy
```

The final page display depends on the

<controls>

in the page metadata and component type mapping, not whether a component is mounted in the local

main.tsx

main.tsx

and

npm run dev

are only used for local auxiliary preview, not the final delivery path.

Metadata-First Development Model

From the user's development perspective, a KWC function should be divided into three layers:

Component code: Responsible for rendering and business logic
Component metadata
```
.js-meta.kwc
```
: Declares "how this component can be referenced by pages and which configurable properties it can expose"
Page metadata
```
.page-meta.kwp
```
: Declares "which component instances this page consists of and what property values are passed to each instance"

Therefore, when handling requirements, do not only ask "how many components need to be written", but also judge:

Which parameters are hard-coded in the component code
Which parameters need to be exposed to page configurators and defined as
```
<property>
```
in component metadata
Which component instances will appear in the
```
<controls>
```
of the page metadata

Default principles:

Implementation details that can be fixed inside the component should not be exposed to metadata
Only parameters that need to be assembled, reused, or configured by pages should be included in component metadata and page metadata

Translate Requirements into Project Objectives First

When receiving a request like "Help me develop a KWC page/function", first translate the requirements into the following items:

Whether a new project needs to be created or development continues in an existing project
How many components are needed and their respective responsibilities
How many page metadata files are needed and how to combine these components in the page
Which target environment to deploy to finally
Whether
```
kd debug
```
is needed for joint debugging and verification

Only when these items are clarified can the scaffolding commands have clear objectives.

Framework Development Skill Collaboration

Treat

kwc-project-scaffold

as the general entry point for the KWC workflow, but do not let it take over the responsibilities of framework development Skills.

Responsibility boundaries:

```
kwc-project-scaffold
```
is responsible for project initialization, component and page metadata generation, environment configuration, deployment, and debugging orchestration
```
kwc-react-development
```
is responsible for specific component code implementation, framework specifications, and local preview constraints for React KWC projects
```
kwc-vue-development
```
is responsible for specific component code implementation, framework specifications, and local preview constraints for Vue KWC projects
```
kwc-lwc-development
```
is responsible for specific component code implementation, framework specifications, and local preview constraints for LWC KWC projects

Collaboration agreements:

When the task is still in the stages of requirement splitting, scaffolding commands, metadata, environment,
```
deploy
```
, or
```
debug
```
, this Skill continues to lead
When the task enters the stage of "specific code development, component modification, front-end page implementation", it is recommended to load the development Skill corresponding to the current framework
Do not load three framework development Skills at the same time; only recommend one based on the framework of the current project
Do not copy the specific coding rules of the three framework Skills into this Skill; this Skill only retains the selection logic and switching timing

Recommendation rules:

For new projects, use the framework selected by the user in the
```
kd project init
```
interaction as the basis for subsequent Skill recommendations
For existing projects, use the
```
framework
```
in
```
.kd/config.json
```
as the basis for Skill recommendations
When
```
framework=react
```
, it is recommended to switch to
```
kwc-react-development
```
When
```
framework=vue
```
, it is recommended to switch to
```
kwc-vue-development
```
When
```
framework=lwc
```
, it is recommended to switch to
```
kwc-lwc-development
```
If the framework cannot be determined yet, stop and confirm with the user instead of proceeding directly to write code

Inputs that Require User Provision or Confirmation

If these inputs cannot be inferred from the existing project or context, they must be confirmed with the user:

Project name or existing project path
Framework and language
Sky application code
```
app
```
Target environment alias and URL
Authentication method, and real parameters required by OpenAPI
Page identifier, such as page name, formId, business page purpose
Page title, whether
```
bizUnit
```
is needed, whether extension and permission control are needed
Which components need to be exposed to the page and which are only internal logic components
Which parameters need to be made into configurable properties
If the user already has an environment, whether direct deployment to this environment is allowed

Do not fabricate this information without authorization, especially

app

, environment URL, authentication parameters, and the final deployment environment.

Regarding

isv

(developer identifier): It can be left blank during the development phase, and the developer identifier will be pulled from the environment when binding components to the environment, and automatically written into components and page metadata during

kd project deploy

, so users do not need to provide or maintain it manually.

The strictest rules apply to

app

(this section is the only authoritative definition in the full text and will not be repeated in subsequent sections):

```
app
```
is not a value that can be guessed or hard-coded by the Skill
```
app
```
must be explicitly provided by the user or come from the existing
```
.kd/config.json
```
in the current project
When creating a new project,
```
app
```
must be manually filled in during the interaction steps of
```
kd project init
```
If the user does not provide
```
app
```
, do not proceed with initialization, formal metadata generation, or deployment
Do not use the
```
app
```
value in examples as the default value
Do not reuse the
```
app
```
from the previous task
Do not automatically substitute it just because an application exists in the current environment

Content Automatically Decided or Generated by the Skill

These contents should be actively completed by the Skill based on user requirements, and should not be pushed back to the user for item-by-item design:

Split business requirements into component lists
Generate stable
```
PascalCase
```
names for components
Generate standardized lowercase identifiers for pages and instances
Judge whether components need to retain
```
.js-meta.kwc
```
or should be deleted to avoid being treated as deployable components by the scaffolding
Map requirements to
```
<property>
```
in component metadata
Generate
```
page-meta.kwp
```
for pages and fill in
```
<controls>
```
Generate a unique
```
name
```
for each component instance in the page
Judge whether to execute
```
init
```
,
```
create
```
,
```
deploy
```
, or
```
debug
```
currently
Increment the
```
version
```
of the metadata only when the corresponding metadata file is changed and needs to be re-uploaded
Review
```
kd env list
```
and
```
kd env info
```
after environment operations

The default strategy is: Let the user confirm key environment parameters that cannot be inferred, and the Skill is responsible for implementing requirements into project structure and metadata.

app

is an exception: Even within the scope of automatic decision-making, the

app

rules in "Inputs that Require User Provision or Confirmation" must be strictly followed.

Generate Component Metadata from Requirements

When the user wants to "develop a page function", do not wait until the end to supplement

.js-meta.kwc

. After determining component responsibilities, immediately judge how to generate component metadata.

Process in this order:

First identify whether the component will be directly referenced by page metadata.
If it will be referenced by the page, retain and improve the corresponding
```
.js-meta.kwc
```
.
If the component is only for internal reuse logic and does not need to be declared in the metadata page, the corresponding
```
.js-meta.kwc
```
can be deleted to avoid being treated as a deployable component by the scaffolding.
Refine "parameters adjustable by page configurators" into
```
<property>
```
, and do not expose all internal props.

Component metadata should focus on at least these fields:

```
version
```
: Natural number; the scaffolding template may leave it blank, and the Skill needs to fill in a valid value
```
name
```
: Usually consistent with the component name, used as the component type identifier
```
masterLabel
```
: The name of the component displayed on the page assembly side
```
isv
```
: Developer identifier, can be left blank during development, and automatically pulled from the environment and written during deploy
```
app
```
: Rules refer to the section "Inputs that Require User Provision or Confirmation"
```
framework
```
```
targets
```
```
targetConfigs
```

Property design principles:

Use
```
String
```
for text input
Use
```
Integer
```
for integer ranges
Use
```
Boolean
```
for switch-type configurations
Use
```
Combo
```
for fixed enumeration selections

Only when the page needs to pass values to component instances should

<property>

be declared in the component metadata. The property names appearing in

<propertys>

of page metadata must have corresponding definitions in component metadata.

The filling rules for

app

refer to the section "Inputs that Require User Provision or Confirmation"; if there is no credible

app

in the current project, do not generate formal deployable metadata.

If field rules, types, and examples are needed, read:

```
references/component-metadata.md
```

Generate Page Metadata from Requirements

Page metadata is not simply "listing component names", but explicitly writing out the page assembly structure required by the user.

Process in this order:

First determine the page name, title, affiliated application, business unit, and version strategy.
Split the page into one or more component instances according to requirements.
Generate
```
<control>
```
for each instance.
```
control.type
```
must be exactly consistent with the component
```
name
```
in the component metadata, including case.
```
control.name
```
is the unique instance name within the page and must comply with the page metadata naming specifications.
Only properties defined in component metadata can be written into
```
<propertys>
```
.

For example, if the

name

in the component metadata is

OverviewCard

, then

control.type

in the page metadata can only be written as

OverviewCard

. Do not arbitrarily write it as

kwc_OverviewCard

just because the component directory is under

app/kwc/

; such prefixes are not part of the component type name.

Default strategies for page fields:

```
template
```
uses
```
oneregion
```
by default
```
bizUnit
```
,
```
enableExtend
```
,
```
enablePermissionControl
```
are only filled in when explicitly required by the requirements
```
isv
```
and
```
app
```
are based on the main page information, and the control level is only filled in when overwriting is needed

The filling rules for

app

refer to the section "Inputs that Require User Provision or Confirmation". If it is found that the

app

in the page metadata is inconsistent with

.kd/config.json

, stop and check first instead of deploying directly.

If field rules, verification constraints, and examples are needed, read:

```
references/page-metadata.md
```

First Judge the Current Stage

Judge and advance in this order:

If
```
.kd
```
does not exist in the current directory, it is regarded as "KWC project not initialized yet".
If the user wants to create a new page or component, prefer using
```
kd project create
```
instead of manually constructing the directory structure.
If the user wants to deploy or debug, first check whether the environment has been configured via
```
kd env create
```
and
```
kd env auth openapi
```
.
If the user starts writing specific front-end implementation code, first judge the framework of the current project, then recommend switching to the dedicated Skill for the corresponding framework, and do not treat this Skill as the component coding specification.

Judgment order:

New project: Use the framework selected by the user in
```
kd project init
```
as the recommendation basis
Existing project: Use
```
.kd/config.json.framework
```
as the recommendation basis
```
react
```
-> It is recommended to load
```
kwc-react-development
```
```
vue
```
-> It is recommended to load
```
kwc-vue-development
```
```
lwc
```
-> It is recommended to load
```
kwc-lwc-development
```
If the framework is unknown, stop and confirm first instead of guessing by default

Perform Pre-Checks

This Skill is verified based on

kd 0.0.9

. If there are major changes in the CLI version, some workarounds may no longer be applicable.

First confirm the following prerequisites:

Treat
```
Project
```
as the local project directory.
Treat
```
Env
```
as the remote Sky environment.
Remind the user that
```
node
```
,
```
npm
```
, and
```
git
```
are required locally.
If the command requires network installation of CLI or dependencies, decide whether to set up an intranet mirror according to the environment.

Initialize the Project

When the user does not have a KWC project yet, follow this process:

Install the CLI.
Run
```
kd project init <project-name>
```
.
Select the framework and language as required by the user during the interaction process; if the user does not specify the framework and language, do not assume it arbitrarily and should actively ask the user to choose.
Enter the application identifier
```
app
```
code, which must be manually provided by the user.
After initialization is completed, enter the project directory and execute
```
npm install
```
.
Only execute
```
npm run dev
```
when local auxiliary preview of components is needed.

If the user only asks you to "create a KWC project", the default delivery should at least cover: initialization commands, framework/language selection,

app

code input, dependency installation, and how to continue creating components, page metadata, and deployment later.

If the user does not provide

app

, follow the

app

rules in "Inputs that Require User Provision or Confirmation" and stop before initialization to let the user supplement it.

Supplement:

kd project init

relies on

git clone

to download the template. If it fails, first check

git

, network connectivity, and whether the execution environment allows network access. For more actual measurement details, see

references/validation-notes.md

Create Components

When adding new components to an existing project:

Run

kd project create <ComponentName> --type kwc

Use
```
PascalCase
```
for component names.
Let the CLI generate the directory and basic files, then modify the code based on the generated results.
Immediately check the generated
```
.js-meta.kwc
```
and complete the fields and property definitions required for deployment.
If the user wants to create multiple components at the same time, execute the creation command one by one instead of manually copying and inferring the directory structure.

If the user only provides ideas for the page structure but no component names, first generate stable, reusable component names based on semantics, then create them. If the user provides complete business requirements instead of a component list, first actively split component responsibilities, then create them in batches.

Supplement: Components are generated under

app/kwc/<ComponentName>/

; the

.js-meta.kwc

generated by the scaffolding is only a template and needs to be completed according to the above rules. For more actual measurement details, see

references/validation-notes.md

Create Page Metadata

Page metadata is the core of the final delivery link. After deployment, the environment will render the components contained in the page according to the

<controls>

page-meta.kwp

, so this is not an optional step but the main entry point for page delivery.

When a new page needs to be added:

Run

kd project create <page-name> --type page

Open
```
app/pages/<page-name>.page-meta.kwp
```
.
At least check and fill in
```
name
```
,
```
masterLabel
```
,
```
app
```
, and
```
version
```
.
Associate page instances with component types in
```
<controls>
```
.
Manually increase
```
version
```
by 1 only when the page metadata file is changed and ready for re-upload.
Map the component tree, instance names, and page layout to XML instead of stopping at the step of "components have been created".

Do not ignore the following constraints:

```
type
```
is the component type name and must be exactly consistent with the component
```
name
```
in the component metadata, not just semantically corresponding or similar in name.
```
name
```
is the component instance name and must be unique within the page.
```
app
```
must be consistent with the current Sky application code.
```
isv
```
can be left blank during the development phase and will be automatically pulled from the environment and written during deploy, so no manual maintenance is needed.

If field rules, verification constraints, and examples are needed, read

references/page-metadata.md

Supplement: The newly generated

page-meta.kwp

only contains a commented-out

<control>

template by default, and the Skill must actively complete

<controls>

according to requirements. For more actual measurement details, see

references/validation-notes.md

Recommended Orchestration of Scaffold Commands

When the user wants to add a complete KWC page function, follow this order first:

If there is no project, execute
```
kd project init
```
Execute
```
kd project create <ComponentName> --type kwc
```
for each "component that will appear in the page"
Confirm the current project framework; if entering code implementation later, it is recommended to switch to the corresponding framework development Skill
Implement component code
First confirm that the
```
app
```
in the current project's
```
.kd/config.json
```
is the real value manually entered by the user, then complete the
```
.js-meta.kwc
```
of these components

Execute

kd project create <page-name> --type page

Complete the page
```
app/pages/<page-name>.page-meta.kwp
```
Confirm or create the target environment
Complete authentication
If component metadata or page metadata is changed, execute
```
kd project deploy
```
Execute
```
kd debug
```
when joint debugging is needed

If modifying an existing page:

First identify whether to modify component implementation, component metadata, page metadata, or all three
If component metadata or page metadata is changed, be sure to check the version number before deployment
If only component implementation code is changed and all metadata files are unchanged,
```
deploy
```
is usually not needed
If only component implementation code is changed, prefer executing
```
npm run build
```
; continue with
```
kd debug
```
when joint debugging is needed

Do not use the following wrong orders:

Write page metadata first, then guess component property names later
Deploy first, then supplement the version number
Create components and completely ignore checking
```
.js-meta.kwc
```
Retain metadata for all components even if they are only internal auxiliary components

Configure the Environment

Complete environment configuration before deployment:

Use
```
kd env create <env-name> --url <url>
```
to create an environment alias.
Use
```
kd env auth openapi
```
for interactive authentication.
If the user frequently switches environments, use
```
kd env set target-env <env-name>
```
to set the default environment.
Use
```
kd env list
```
and
```
kd env info
```
to check the current configuration when necessary.

Prioritize using the

openapi

authentication method; the

web

mode is not used as the default path for now.

If the target environment does not exist or the environment exists but authentication has not been completed, stop and collect these fields first:

Environment alias
Environment URL
Client ID
Client Secret
Username

Among them,

data center

is not a pre-filled field but a field that is "selected after reading":

First have the environment URL
Then enter
```
kd env auth openapi
```
The scaffolding reads the list of available data centers in the environment
Finally, let the user select from the list

Collection rules:

Environment alias, environment URL, Client ID, Client Secret, and Username must be manually provided by the user
Do not let the user freely enter
```
data center
```
; instead, let the scaffolding read the candidates before selection
Do not use credentials from historical environments to guess new environments
Do not automatically infer which environment to bind this time just because aliases like
```
dev
```
,
```
sit
```
, and
```
base
```
exist

Interaction rules:

Do not assume that pop-up windows or form-based input are currently supported
In the current regular mode, first let the user fill in the manual fields, then select the data center in the interaction of
```
kd env auth openapi
```
If the running environment clearly supports structured selection tools, the candidates can be displayed to the user for selection after reading the data center list
Even so, free-text fields like Client Secret should still be filled in manually by the user

Recommended format for requesting environment information from the user:

text

Please supplement the following environment information:
1. env name:
2. env url:
3. client id:
4. client secret:
5. username:

Note: data center does not need to be filled in first; candidates will be read by the scaffolding for selection later.

Supplement: Environment configurations are saved in

~/.kd

instead of the project directory; after creation, be sure to use

kd env list

to review whether the persistence is successful;

kd env auth openapi

will fail directly if the URL is unreachable. For more actual measurement details, see

references/validation-notes.md

Deployment and Debugging

Do not treat

kd project deploy

as a fixed step that "must be run every time code is changed". The core function of

deploy

is to upload metadata to the target environment, so

deploy

only needs to be considered when component metadata

.js-meta.kwc

or page metadata

.page-meta.kwp

changes.

Common commands:

```
kd project deploy
```
: Deploy the entire project to the default environment

kd project deploy -d app/kwc/MyComponent -e sit

: Only deploy the specified component to

sit

kd project deploy -d app/pages/MyPage -e sit

: Only deploy the specified page metadata to

sit

```
kd debug
```
: Enter debugging mode

To specify an environment or form, use

kd debug -e <env-name>

kd debug -f <formid>

Version management rules:

Only modify component implementation code, such as
```
.tsx
```
,
```
.vue
```
,
```
.js
```
,
```
.html
```
,
```
.scss
```
, and no metadata files are changed: No need for
```
deploy
```
, and no need to increment
```
version
```
Modify component metadata
```
.js-meta.kwc
```
: Increment the
```
version
```
of the component metadata, then deploy the component or the entire project
Modify page metadata
```
.page-meta.kwp
```
: Increment the
```
version
```
of the page metadata, then deploy the page metadata or the entire project
Modify both component metadata and page metadata: Increment their respective
```
version
```
s, then deploy the affected paths or the entire project
Create new component metadata or page metadata: Set the initial
```
version
```
to
```
1
```
, and execute
```
deploy
```
during the first upload

Judgment principles:

Whether
```
deploy
```
is needed depends on whether metadata files are changed, not just because "code has just been modified"
Whether
```
version
```
needs to be incremented also depends on whether the corresponding metadata file is changed, not because of build, debugging, or pure code changes
If only component code is modified, prefer executing
```
npm run build
```
; continue with
```
kd debug
```
when joint debugging is needed

When debugging across applications, first check whether the

app

code in

.kd/config.json

needs to be manually switched.

Supplement:

kd project deploy

will be directly blocked if the environment is not authenticated;

kd debug -e <env> -f <formid>

may be abnormal in some versions, and a more reliable path is to first execute

kd env set target-env <env>

and then execute

kd debug -f <formid>

. For more actual measurement details, see

references/validation-notes.md

End-to-End Execution Principles

When the user says "Help me develop a KWC page/function", follow this link by default:

Identify whether it is a new project or an existing project
Collect environment inputs that cannot be inferred
Split components and create component projects
Implement component code
Create and complete page metadata
Configure the environment and confirm the authentication status
If metadata is changed, execute
```
deploy
```
Execute
```
debug
```
when necessary

Do only complete "component creation" or "run locally" unless the user explicitly only wants a partial step.

Output Requirements

When outputting solutions or execution commands, try to provide the following at the same time:

Which key inputs the user still needs to supplement
Which stage is currently in
The next command to be executed
Whether it depends on existing environment authentication
Whether
```
page-meta.kwp
```
needs to be modified
How the page metadata will combine components
Whether
```
deploy
```
is really needed
If deployment is needed, whether
```
version
```
must be incremented due to metadata changes

Common Mistakes

Prioritize troubleshooting these issues:

Directly execute
```
kd project create
```
in a non-KWC project directory
Create a page but do not write components into
```
<controls>
```
```
type
```
is inconsistent with the real component name
```
app
```
code is inconsistent with the target application
Page metadata is uploaded repeatedly but
```
version
```
is not incremented
Only modify component code but mistakenly think that
```
deploy
```
must be done immediately
Only create components but do not write them into page metadata
Metadata has been changed but only local preview is done without continuing to
```
deploy
```
Execute
```
deploy
```
or
```
debug
```
directly without authenticating the environment

Reference Materials

When precise commands, parameter descriptions, OpenAPI field descriptions, and page-meta examples are needed, read:

```
references/cli-reference.md
```
```
references/component-metadata.md
```
```
references/env-setup.md
```
```
references/page-metadata.md
```
```
references/validation-notes.md
```

kwc-project-scaffold

NPX Install

Tags

SKILL.md Content (Chinese)