New "Azd best practices" skill

[massimobonanni]

Pull Request Checklist

• I have read and followed the CONTRIBUTING.md guidelines.
• I have read and followed the Guidance for submissions involving paid services.
• My contribution adds a new instruction, prompt, agent, skill, workflow, or canvas extension file in the correct directory.
• The file follows the required naming convention.
• The content is clearly structured and follows the example format.
• I have tested my instructions, prompt, agent, skill, workflow, or canvas extension with GitHub Copilot.
• I have run npm start and verified that README.md is up to date.
• I am targeting the main branch for this pull request.

---

Description

This pull request adds a new "Azure Developer CLI" skill to the repository, including comprehensive documentation, best practices, reference materials, and an example configuration. The changes provide clear guidance for designing, creating, and managing Azure Developer CLI (azd) projects, as well as references to official Microsoft documentation and practical examples.

New Azure Developer CLI skill and documentation:

• docs/README.skills.md: Registered the new azure-developer-cli skill with a summary of its capabilities and relevant reference files.
• skills/azure-developer-cli/SKILL.md: Added a detailed best practices guide for using Azure Developer CLI, covering repository discovery, safety guardrails, defaults, workflows, validation steps, and reporting.

Reference materials and examples:

• skills/azure-developer-cli/references/iac-and-environments.md: Introduced a reference on infrastructure as code (Bicep and Terraform) and environment management strategies for azd projects.
• skills/azure-developer-cli/references/official-docs.md: Added a curated list of official Microsoft documentation links for Azure Developer CLI concepts, infrastructure, environments, and advanced features.
• skills/azure-developer-cli/examples/azure.yaml: Provided an example azure.yaml manifest demonstrating recommended project structure, service definitions, hooks, and best practices.

---

Type of Contribution

• New instruction file.
• New prompt file.
• New agent file.
• New plugin.
• New skill file.
• New agentic workflow.
• New canvas extension.
• Update to existing instruction, prompt, agent, plugin, skill, workflow, or canvas extension.
• Other (please specify):

---

Additional Notes

Nothing

---

By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.

[github-actions]

🔒 PR Risk Scan Results

Scanned 6 changed file(s).

Severity	Count
🔴 High	0
🟠 Medium	0
ℹ️ Info	0

✅ No matching risk patterns were detected in changed files.

This is an automated soft-gate report. Findings indicate review targets and do not block merge by themselves.

[github-actions]

🔍 Vally Lint Results

✅ All checks passed

Scope	Checked
Skills	1
Agents	0
Total	1

Severity	Count
❌ Errors	0
⚠️ Warnings	0
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	✅ azure-developer-cli (2/2 checks passed)
ℹ️	✓ [spec-compliance] All 1 skill(s) are spec-compliant.
ℹ️	✓ spec-compliance: All spec checks passed.
ℹ️	✓ [valid-refs] All file references across 1 skill(s) are valid.
ℹ️	✓ valid-refs: All file references resolve to existing files within the skill directory.
ℹ️	1 skill(s) linted, 1 passed

Full linter output

### Linting skills/azure-developer-cli
✅ azure-developer-cli (2/2 checks passed)
    ✓ [spec-compliance] All 1 skill(s) are spec-compliant.
        ✓ spec-compliance: All spec checks passed.
    ✓ [valid-refs] All file references across 1 skill(s) are valid.
        ✓ valid-refs: All file references resolve to existing files within the skill directory.

1 skill(s) linted, 1 passed

[Copilot]

Pull request overview

Adds an Azure Developer CLI skill covering project structure, infrastructure, environments, security, CI/CD, and operations.

Changes:

• Adds AZD best-practice instructions and references.
• Includes an example azure.yaml.
• Registers the skill in generated documentation.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
skills/azure-developer-cli/SKILL.md	Defines the skill workflow and guardrails.
references/security-cicd-operations.md	Documents security, hooks, pipelines, and operations.
references/project-structure.md	Describes recommended AZD project layouts.
references/official-docs.md	Lists official documentation sources.
references/iac-and-environments.md	Covers Bicep, Terraform, and environments.
examples/azure.yaml	Provides an example AZD manifest.
docs/README.skills.md	Registers the new skill.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (2)

skills/azure-developer-cli/SKILL.md:23

• The bundled examples/azure.yaml is not referenced anywhere in the skill instructions, so an agent loading SKILL.md has no path to discover or use this example. Add it to this resource list, as other skills do for bundled examples (for example, skills/appinsights-instrumentation/SKILL.md:39).

5. Read the relevant reference:
   - Repository layout or `azure.yaml`: [references/project-structure.md](references/project-structure.md)
   - Bicep, Terraform, parameters, outputs, or environments: [references/iac-and-environments.md](references/iac-and-environments.md)
   - Secrets, hooks, CI/CD, deployment, or troubleshooting: [references/security-cicd-operations.md](references/security-cicd-operations.md)
   - Product details that may have changed: [references/official-docs.md](references/official-docs.md)

skills/azure-developer-cli/references/security-cicd-operations.md:134

• This generalizes an outdated authentication limitation to every Terraform pipeline flow. Current azd pipeline config supports federated/OIDC authentication for Terraform on GitHub Actions; the documented OIDC limitation applies to Azure Pipelines. As written, the skill may steer GitHub users toward unnecessary long-lived credentials.

For GitHub Actions, AZD configures OIDC/federated credentials by default for supported scenarios. Current documentation says the AZD Terraform pipeline flow does not support OIDC, so evaluate the authentication tradeoff explicitly rather than silently falling back to a long-lived credential.