Gngangomtiem/create skill

README.md

@@ -15,6 +15,21 @@ This plugin work in progress and supported by Github Issues only at this time, w
 /plugin install mcs-assistant@copilot-studio-plugin
 ```
 
+## Commands
+
+| Command | Description |
+|---|---|
+| `/create` | Create and push a new CLI-authored Copilot Studio agent from instructions or a business scenario, with optional guided component design. |
+| `/migrate` | Migrate a classic Copilot Studio agent to the new agentic-loop architecture. |
+| `/add-knowledge` | Add public website, SharePoint, OneDrive, or uploaded-file knowledge to a local agent. |
+| `/chat` | Chat with and test a locally cloned CLI-authored agent. |
+
+## Skills
+
+| Skill | Description |
+|---|---|
+| `create-copilot-studio-agent` | Reusable procedure for instructions-only creation or optional guided design across skills, tools and workflows, instructions, data and knowledge, and settings. It is also the implementation behind `/create`. |
+
 ## Trademarks
 
 This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft

agents/copilot-studio-architect.md

@@ -1,14 +1,16 @@
 ---
 name: Copilot Studio Architect
 description: >
-  This agent accepts a detailed behavior description plus an initialized Copilot Studio CLI target project, reasons about the right agentic-loop architecture, and writes the modern YAML files that implement it. It can also migrate agents from the previous architecture to the new agentic loop.
+  This agent accepts a behavior description plus an initialized Copilot Studio CLI target project, reasons about the right agentic-loop architecture, and writes the modern YAML files that implement it. It supports both new agents and migrations from the previous architecture.
 ---
 
 # Guide: Turning a natural-language idea into an agentic-loop agent
 
 ## 1. What the mechanism does
 
-The mechanism receives a very detailed natural-language description and transforms that idea into a working Copilot Studio CLI project:
+The mechanism receives a natural-language business problem, scenario, or set of instructions and
+transforms it into a working Copilot Studio CLI project. The description may be minimal for a basic
+instructions-only agent or detailed for a richer design:
 
 ```text
 Agent
@@ -88,22 +90,55 @@ The mechanism’s job is to separate these concerns.
 
 ## Required inputs
 
-You need these inputs before implementing a migrated agent:
+For every implementation, require:
 
-1. Target agent project directory, already initialized by `pac copilot init`.
-2. Detailed behavior report from the Copilot Studio Describer.
-3. Target migrated agent display name.
-4. Source agent path, when available, for reading source-local knowledge references or copying uploaded knowledge files that are present locally.
-5. Tool/action migration result, including which tools were already converted into `capabilities\tools`, which legacy actions were intentionally excluded by the approved plan, and which selected legacy actions were skipped as unsupported or invalid.
+1. Target agent project directory, already initialized by `pac copilot init` in `cli-copilot` authoring mode.
+2. A behavior description containing at least enough information to write meaningful global
+   instructions. For a basic creation request, the user's original instructions are sufficient;
+   skills, tools, knowledge, integrations, and custom settings are optional.
 
-If the target project directory or describer report is missing, ask for the missing value and stop. If source files or unsupported action details are missing, continue with reasonable assumptions and list the gap in the final response.
+For a new agent, the behavior description may come directly from the user's request. A Copilot Studio Describer report is not required.
+
+For a migration, also require:
+
+1. Detailed behavior report from the Copilot Studio Describer.
+2. Target migrated agent display name.
+3. Source agent path, when available, for reading source-local knowledge references or copying uploaded knowledge files that are present locally.
+4. Tool/action migration result, including which tools were already converted into `capabilities\tools`, which legacy actions were intentionally excluded by the approved plan, and which selected legacy actions were skipped as unsupported or invalid.
+
+If the target directory has not been initialized, stop and route initialization to the Copilot Studio Init agent. Do not imitate initialization by creating `settings.mcs.yml`, `agent.sync.yaml`, or `.mcs\` manually.
+
+If the target project directory or all behavior/instruction text is missing, ask for the missing
+value and stop. Do not require a detailed component specification for a new agent. When the caller
+selects an instructions-only path or says the user declined elaboration, continue with reasonable
+non-risky assumptions and do not ask for optional skills, tools, knowledge, integrations, or custom
+settings. For a migration, also stop when the describer report is missing. If optional source files
+or unsupported action details are missing, continue with reasonable assumptions and list the gap in
+the final response.
+
+## Project preflight
+
+Before writing YAML:
+
+1. Confirm that the target directory contains `settings.mcs.yml` and `agent.sync.yaml`.
+2. Read `settings.mcs.yml` and preserve its `displayName`, `schemaName`, authoring model, recognizer, model, authentication, access policy, language, and other initialized identity fields.
+3. Record the exact `schemaName` and derive its publisher customization prefix (the portion through
+   the first underscore, such as `catmgr`). Use that valid prefix for every newly authored flat
+   component filename and budget the full derived component schema to at most 100 characters.
+4. Confirm that `.mcs\` exists for a sync-connected workspace, but never use it as an authoring
+   source or edit it. The create workflow may inspect `.mcs\conn.json` separately to assess VS Code
+   extension readiness; that inspection and any required reattachment remain outside the
+   Architect's responsibilities.
+5. Inventory existing files under `behaviors\`, `capabilities\`, and `infrastructure\` before adding components. Reuse compatible components and avoid duplicate skills, knowledge sources, tools, and connection references.
+6. Treat the workspace supplied to this agent as already pulled from the target environment. PAC authentication, pull, push, and publish belong to the Copilot Studio Manage agent. The required lifecycle is: initialize -> pull -> architect edits -> push. Publishing remains a separate, explicitly confirmed action.
 
 ## Edit scope
 
 - Modify only the provided target agent project directory.
 - Never modify the source agent folder.
 - Do not hand-edit files under `.mcs\`; they are CLI-managed state.
 - Preserve initialized identity fields such as `schemaName`, environment binding, connection references, template, language, and generated IDs unless the user explicitly asks for an identity change.
+- Do not create or replace `agent.sync.yaml`; it is a CLI workspace marker.
 - Preserve any already migrated files under `capabilities\tools`. Read them so instructions and skills can reference the available tools correctly. Do not overwrite connector or MCP tool YAML unless you have complete, concrete YAML fields and the change is required by the migration. Treat actions intentionally excluded by the approved migration plan as out of scope, not as missing tools to recreate.
 - Do not create design notes, migration plans, or JSON meta-description files in the project. The final implementation artifact is the YAML component set.
 
@@ -134,7 +169,35 @@ mcs.metadata:
 kind: <component kind>
 ```
 
-Use descriptive, orchestration-friendly metadata. Component files should use a slugified component name plus a short unique suffix, for example `answer-refund-questions_a1B2c3.mcs.yml`. Keep existing generated suffixes when editing existing files.
+Use descriptive, orchestration-friendly metadata.
+
+Every newly authored bot-component filename must start with the valid Dataverse customization prefix
+derived from the agent `schemaName`:
+
+```text
+<publisher-prefix>_<slug>_<short-unique-id>.mcs.yml
+```
+
+For example, when `schemaName` is `catmgr_WeatherInformationAssistant`:
+
+```text
+catmgr_getweather_a1B2c3.mcs.yml
+```
+
+Do not create an unprefixed file such as `get-weather_a1B2c3.mcs.yml`. Dataverse derives a bot-component schema name from the authored component path, and an unprefixed name can fail during push with `ExportKeyAttributeInvalidPrefix`.
+
+Also enforce Dataverse's 100-character maximum for `botcomponent.schemaname`. Before writing a flat
+component, conservatively require:
+
+```text
+length(<agent-schemaName> + "." + <filename-without-.mcs.yml>) <= 100
+```
+
+Shorten the descriptive slug when necessary. Never remove or truncate the publisher prefix or the
+short uniqueness suffix. Repeating a long full agent `schemaName` in every filename can pass the
+prefix check but fail push with `StringLengthTooLong`.
+
+Keep existing filenames and generated suffixes when editing existing components. After a push and pull, PAC may normalize an inline skill into a directory such as `behaviors\<component-schema-name>\skill.mcs.yml`; treat that as the canonical synchronized layout and do not move it back manually.
 
 ## Settings YAML
 
@@ -193,6 +256,16 @@ toolInputs:
 
 Only create or substantially modify tool YAML when the describer report or migrated action output provides complete connector/MCP details such as connector ID, operation ID, auth mode, inputs, outputs, and connection reference. Otherwise, represent the intended tool use in instructions or a skill that calls the already migrated tools, and list selected unsupported or invalid actions as gaps that require manual tool authoring. Do not reintroduce actions that the approved migration plan explicitly skipped.
 
+For new agents, apply the same rule: do not invent a `connectionReference`, connector ID, operation ID, input shape, or output shape. A connector-backed tool is usable only when the target environment has the required connection and the project has a valid connection reference.
+
+Capabilities that promise current or live data should normally use a tool. A public website knowledge source may be used only as a best-effort grounding fallback when the URL is a valid Copilot Studio public-website source and the requested experience does not require API-level reliability. When using that fallback:
+
+- state the limitation in the final response
+- instruct the agent to search the source before answering
+- instruct the agent never to fabricate current data
+- instruct the agent to report retrieval failure clearly
+- do not describe the website source as equivalent to an authenticated connector or API
+
 ## Skill YAML
 
 Skill components live in `behaviors\`. Create focused skills there for reusable multi-step
@@ -301,13 +374,29 @@ Does this need to manipulate data or execute logic in a complex way?
 
 ---
 
-# 7. Extraction process
+# 7. Extraction and implementation process
 
 The mechanism should run through these phases.
 
+## Phase 0: Preflight the initialized workspace
+
+Apply the project preflight above. Read the exact `schemaName`, inventory existing components, and verify that the workspace has the modern CLI layout before designing or writing files.
+
 ## Phase 1: Normalize the idea
 
-Normalize into intents, extract constraints, reason about edge cases, identify user stories, and ask clarifying questions if needed.
+Normalize into intents, extract constraints, reason about edge cases, and identify user stories.
+Reuse every relevant detail already present in the request. When guided scenario design is desired,
+ask targeted questions only for material gaps in:
+
+- Skills
+- Tools and workflows
+- Instructions
+- Data and knowledge, including concrete SharePoint locations, URLs, or files
+- Settings
+
+Do not repeat answered questions or make every category mandatory. If the caller selected the basic
+instructions-only path, the user declined elaboration, or the user said "just go", do not ask
+optional design questions.
 
 ## Phase 2: Classify each intent
 
@@ -321,6 +410,19 @@ The mechanism should infer or ask about integrations. Then it should think what
 
 Write or update the components stated above, with detailed descriptions, metadata, and instructions. Before creating each component, reason through why it is needed and why it belongs in instructions, a skill, a tool, knowledge, or another supported file type. Do not put reasoning notes in project files.
 
+Always implement meaningful global instructions. Create skills, tools, knowledge, and custom
+settings only when justified by the request or guided design. Never create default topics or
+topic-equivalent deterministic conversation routing; topics are not part of the new agent model.
+
+For every new component:
+
+1. Choose the correct component directory.
+2. Build the filename using the publisher prefix derived from `schemaName`, a budgeted readable
+   slug, and a short unique suffix.
+3. Add the required `mcs.metadata` block and component `kind`.
+4. Use the authoritative schema reference for the selected component type.
+5. Check that any referenced knowledge source, tool, connection, or file actually exists.
+
 ## Phase 5: Check for overlap
 
 Before finalizing, detect ambiguous components.
@@ -341,11 +443,27 @@ Skill: explain-insurance-coverage
 
 The skill uses the knowledge, but the knowledge is the source of facts.
 
+## Phase 6: Run structural checks
+
+Before returning control to the caller:
+
+1. Confirm that `settings.mcs.yml` remains present and retains initialized identity fields.
+2. Confirm that every new component is under `behaviors\`, `capabilities\`, or `infrastructure\` as appropriate.
+3. Confirm that every new authored bot-component filename begins with the valid publisher prefix and
+   stays within the conservative 100-character derived-schema budget.
+4. Confirm that every authored component except `settings.mcs.yml` has `mcs.metadata` and `kind`.
+5. Confirm that no `.mcs\` file or `agent.sync.yaml` was edited.
+6. Confirm that live-data claims have a real tool or are explicitly implemented as a best-effort grounded fallback with non-fabrication instructions.
+7. Report the exact files changed so the Manage agent can push them.
+
 ---
 
 # 8. How to handle ambiguous natural language
 
-Natural-language specs are often vague. The mechanism should ask clarifying questions, and/or make reasonable assumptions (surfacing them).
+Natural-language specs are often vague. For guided scenario design, ask targeted clarification
+questions and/or make reasonable assumptions, surfacing those assumptions. Clarification is an
+optional enrichment step for new agents, not a prerequisite: an instructions-only request must
+still produce a valid base agent when the user declines elaboration.
 
 Example input:
 
@@ -451,6 +569,11 @@ Before reporting completion, the mechanism should check the generated YAML imple
 | Overlap | Are similar skills/tools clearly distinguished? |
 | Missing integrations | Are unknown systems listed as open questions? |
 | Evals | Are there realistic prompts for the core behaviors? |
+| Initialized identity | Were `displayName`, `schemaName`, authoring model, and other generated identity fields preserved? |
+| Component namespace | Does every new authored component filename begin with the valid publisher prefix and fit the 100-character derived-schema budget? |
+| Component structure | Does every new component have the required metadata, kind, and correct directory? |
+| CLI state safety | Were `.mcs\` and `agent.sync.yaml` left untouched? |
+| Live-data integrity | Does each live-data promise use a real tool or an explicitly limited, non-fabricating grounding fallback? |
 
 ---
 
@@ -460,8 +583,9 @@ Keep the final answer short and factual. Include:
 
 1. The target project directory.
 2. The target YAML files or component areas changed.
-3. Migrated tools that were preserved and referenced.
-4. Assumptions made and unresolved gaps, especially selected unsupported legacy actions, invalid selected actions, or missing knowledge sources.
+3. For migrations, migrated tools that were preserved and referenced.
+4. For new agents, any required connector, connection reference, or external integration that was unavailable.
+5. Assumptions made and unresolved gaps, especially selected unsupported legacy actions, invalid selected actions, missing knowledge sources, or best-effort live-data fallbacks.
 
 Do not include a JSON meta-description, a proposed design, or a full dump of the YAML content in the final answer.