refactor: improve azd sample selection guidance and agent creation workflow in foundry skill

plugins/azure-skills/skills/microsoft-foundry/foundry-agent/azd-guidance/azd-guidance.md

@@ -18,4 +18,5 @@ Set it inline only (as shown above). Never persist it into code or committed con
 
 2. If an azd command or flag is unclear, run the relevant `azd ... --help` command and follow its output.
 3. Unless the user explicitly asks to open a client, run `azd ai agent run --no-client`.
-4. If the needed azd guidance is not covered here or remains unclear, read [azd ai CLI Reference](references/azd-ai-cli.md).
+4. Run project-scoped `azd` commands inside the project folder, not from its parent folder.
+5. If the needed azd guidance is not covered here or remains unclear, read [azd ai CLI Reference](references/azd-ai-cli.md).

plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/create-hosted.md

@@ -15,7 +15,7 @@ Scaffold a hosted Foundry agent project with the Azure Developer CLI (`azd`) and
 | Scaffold command | `azd ai agent init -m <manifestUrl> --deploy-mode code --runtime python_3_13 --entry-point main.py`, pass `--runtime dotnet_10 --entry-point MyAgent.dll` for .NET project (or `--src <dir>` when onboarding existing code) |
 | Local run | Follow [local-run](references/local-run.md) for the service's protocol-specific invocation path |
 | Deploy handoff | [deploy/deploy.md](../deploy/deploy.md) |
-| Sample catalog | `azd ai agent sample list --featured-only --output json` |
+| Sample catalog | `azd ai agent sample list --output json` |
 | Reference docs | [azd-ai-cli](../azd-guidance/references/azd-ai-cli.md), [local-run](references/local-run.md), [toolbox.md](../toolbox/toolbox.md) |
 
 ## When to Use This Skill
@@ -36,6 +36,20 @@ For prompt agents (LLM + instructions, no container), use [create-prompt.md](cre
 | Local debugging | `azd ai agent run --no-client` | Limited |
 | Output | New immutable agent version per `azd deploy` | `agent_update` via MCP / SDK |
 
+## azd Sample Selection Guidance
+
+Use this azd sample selection guidance when the workflow refers to azd sample selection guidance.
+
+List the curated catalog (filter by language if known):
+
+```bash
+azd ai agent sample list --language python --output json
+```
+
+Capture the selected sample's `manifestUrl`.
+
+> **Important:** Always select the best-matching sample from `azd ai agent sample list` for the capabilities the user explicitly requested. Use advanced tool samples only when the user explicitly asks for external actions, APIs, tools, connectors, or data lookup. Starting with the right sample helps ensure that the implementation follows the established code patterns and best practices for that type of Foundry hosted agent. If `azd ai agent sample list` does not return a suitable sample, choose one from the official [Foundry samples repository](https://github.com/microsoft-foundry/foundry-samples) and construct the manifest URL from its exact `azure.yaml` path, following the URL format returned by `azd ai agent sample list`.
+
 ## Workflow
 
 ### Step 1 -- Verify the environment
@@ -95,22 +109,14 @@ If unsure, inspect the workspace and user intent. Do not invent a manifest URL o
 
 ### Step 4a -- New agent: scaffold from a sample
 
-List the curated catalog (filter by language if known):
-
-```bash
-azd ai agent sample list --featured-only --language python --output json
-```
-
-Each entry has a `manifestUrl` and an `initCommand`. Prefer code deployment. `azd ai agent init` defaults to code deployment.
-
-For a generic new hosted agent request, start from the basic sample. Use tool/function-calling samples only when the user explicitly asks for external actions, APIs, tools, connectors, or data lookup.
-
-If `azd ai agent sample list --featured-only` does not return a suitable sample, remove `--featured-only` and rerun `azd ai agent sample list`. If that still does not return a suitable sample, choose one from the official [Foundry samples repository](https://github.com/microsoft-foundry/foundry-samples) and construct the manifest URL from its exact `azure.yaml` path, following the URL format returned by `azd ai agent sample list`.
+Follow [azd Sample Selection Guidance](#azd-sample-selection-guidance) and use the captured `manifestUrl` to scaffold the agent.
 
 Run `azd ai agent init`. `azd ai agent init` is sufficient to create new Foundry projects (or reuse an existing one) and create new Foundry agents. By default, you do not need to run `azd init` unless the user has specific initialization requirements.
 
 Python Example (add `--project-id "<resourceId>"` for an existing Foundry project; add `--agent-name <name>` if the user wants a custom name -- omit otherwise to keep the sample default):
 
+Pass `--deploy-mode code` by default to use the direct code deployment.
+
 ```bash
 azd ai agent init --no-prompt \
   -m "<manifestUrl>" \
@@ -119,7 +125,7 @@ azd ai agent init --no-prompt \
   --entry-point main.py
 ```
 
-Immediately after init, set the collected subscription and location on the active azd environment:
+After the `azd ai agent init` completes, go to the project folder and set the collected subscription and location on the active azd environment:
 
 ```bash
 azd env set \
@@ -183,7 +189,7 @@ Use when the workspace already contains an agent project or source code.
 
 First determine whether the workspace is already a Foundry hosted agent project.
 
-- **Existing Foundry hosted agent** -- preserve its project structure, make the requested changes, and continue. For Foundry-specific features, run `azd ai agent sample list` to browse available samples for code reference.
+- **Existing Foundry hosted agent** -- preserve its project structure, make the requested changes, and continue. For Foundry-specific features, use `azd ai agent sample list` and follow the [azd Sample Selection Guidance](#azd-sample-selection-guidance) to choose a sample for code reference.
 - **Other existing agent** -- infer whether the user wants to re-host it on Foundry and ask only when the intended outcome is unclear. If re-hosting, follow the Re-host steps below.
 
 #### Re-host: collect information
@@ -197,7 +203,7 @@ Infer these choices from the user's request and current code. Ask only for infor
 
 #### Re-host: adapt and initialize
 
-Use `azd ai agent sample list --language <language> --output json` to find the closest relevant sample for adapter, protocol, and deployment guidance. Treat samples as boundary patterns, not replacement applications.
+Use `azd ai agent sample list --language <language> --output json` and follow the [azd Sample Selection Guidance](#azd-sample-selection-guidance) to find the closest relevant sample for adapter, protocol, and deployment guidance. Treat samples as boundary patterns, not replacement applications.
 
 After resolving the choices, run:
 
@@ -283,7 +289,7 @@ See the canonical env-var registry: [azure-dev/cli/azd/docs/environment-variable
 
 ## Common Guidelines
 
-1. **Sample-first** -- always get `manifestUrl` from `azd ai agent sample list`.
+1. **Sample-first** -- select the sample and capture its `manifestUrl` according to the [azd Sample Selection Guidance](#azd-sample-selection-guidance).
 2. **Prefer azd over az** -- fall back to `az` only as a last resort, with explicit consent.
 3. **Don't auto-login** -- `az login` and `azd auth login` are user-owned browser flows; ask the user and stop.
 4. **JSON output** -- add `--output json` only to read-only `azd ai agent` commands such as `show`. Do not add it to `azd ai agent invoke`; invoke supports `default` and `raw`, not `json`.
@@ -296,7 +302,7 @@ See the canonical env-var registry: [azure-dev/cli/azd/docs/environment-variable
 > - **Project:** if the user named a project or asked to create one, go ahead; otherwise stop and ask before provisioning.
 > - **Toolbox/connection:** create it only when the user asked you to; otherwise leave the configs as placeholders and ask.
 
-Defaults when unspecified: greenfield + Python + `azd ai agent sample list --featured-only --language python`, choose the simplest recommended sample that matches the request, plus `--no-prompt` on every write. Always set the subscription and location after init as shown in Step 4a. If creating a new project and the user did not provide a project name, auto-generate one using the pattern `ai-project-<random>` (6-8 lowercase alphanumeric characters). Show the generated name to the user but do not block on confirmation. If using an existing project, ensure `azd ai agent init` receives `--project-id`: use the supplied ARM ID, or run the Step 2 resolve script for the supplied Foundry project endpoint and pass the returned `id`. If the user did not ask to create a new project and did not supply an existing one (ARM ID / endpoint), stop and ask which to use before provisioning. If `az` or `azd` is missing, ask before installing in interactive mode; install directly in non-interactive mode. In any mode, never run `az login` or `azd auth login`; stop and ask the user to log in manually before re-running Step 1. If the manifest declares secret parameters, collect them with `ask_user` and set them via `azd env set PARAM_...` before init -- keep `--no-prompt` (do not fall into azd's interactive prompts).
+Defaults when unspecified: greenfield + Python + `azd ai agent sample list --language python --output json`, choose the simplest recommended sample that matches the request, plus `--no-prompt` on every write. Always set the subscription and location after init as shown in Step 4a. If creating a new project and the user did not provide a project name, auto-generate one using the pattern `ai-project-<random>` (6-8 lowercase alphanumeric characters). Show the generated name to the user but do not block on confirmation. If using an existing project, ensure `azd ai agent init` receives `--project-id`: use the supplied ARM ID, or run the Step 2 resolve script for the supplied Foundry project endpoint and pass the returned `id`. If the user did not ask to create a new project and did not supply an existing one (ARM ID / endpoint), stop and ask which to use before provisioning. If `az` or `azd` is missing, ask before installing in interactive mode; install directly in non-interactive mode. In any mode, never run `az login` or `azd auth login`; stop and ask the user to log in manually before re-running Step 1. If the manifest declares secret parameters, collect them with `ask_user` and set them via `azd env set PARAM_...` before init -- keep `--no-prompt` (do not fall into azd's interactive prompts).
 
 ## Error Handling