azure-sdk-for-java icon indicating copy to clipboard operation
azure-sdk-for-java copied to clipboard
verified publisher icon Azure

Add AGENTS.md file to align with AGENTS.md standards

Open Copilot opened this issue 5 months ago • 3 comments

  • [x] Review existing .github/copilot-instructions.md to understand current agent guidance
  • [x] Research AGENTS.md specification and canonical structure
  • [x] Create AGENTS.md file at repository root with appropriate sections
  • [x] Include repository purpose, workflows, and agent interaction guidelines
  • [x] Add cross-references between AGENTS.md and .github/copilot-instructions.md
  • [x] Document SDK-specific automation workflows (codegen, API review, test matrix)
  • [x] Verify the file renders correctly and follows markdown best practices
  • [x] Fix all relative links to use absolute GitHub URLs per Azure SDK guidelines

✅ Implementation Complete

Successfully created a comprehensive AGENTS.md file at the repository root that aligns with the AGENTS.md standard.

Latest Update (commit hash to be added)

Fixed all relative links to use absolute GitHub URLs as required by Azure SDK link guidelines:

  • AGENTS.md: Updated 6 relative links to absolute URLs
  • .github/copilot-instructions.md: Updated 1 relative link to absolute URL
  • README.md: Updated 1 relative link to absolute URL

All links now follow the format: https://github.com/Azure/azure-sdk-for-java/blob/main/[filename]

Files Created/Modified:

  1. AGENTS.md (NEW) - 216 lines with absolute links to CONTRIBUTING.md, SECURITY.md, SUPPORT.md, and copilot-instructions.md
  2. .github/copilot-instructions.md (MODIFIED) - Cross-reference to AGENTS.md using absolute URL
  3. README.md (MODIFIED) - AI agent guidance note with absolute URL to AGENTS.md

Key Features of AGENTS.md:

Repository Overview

  • Purpose, structure, and organization of Azure SDK for Java
  • Clear directory layout and library categorization

Agent Capabilities

  • Supported actions: code generation, documentation, issue triage, build automation, release support
  • Clear boundaries and limitations (what agents should NOT do)

Key Workflows

  • Building the SDK (Maven commands)
  • Running code quality checks (Checkstyle, SpotBugs)
  • Testing (unit and live tests)
  • Versioning (semantic versioning, update scripts)
  • SDK generation (AutoRest commands)

Design Guidelines

  • Azure SDK design principles for Java
  • API design requirements
  • Java compatibility (Java 8 baseline, LTS support)

Additional Sections

  • CI/CD Pipeline information
  • Security and compliance best practices
  • Comprehensive resource links (all using absolute URLs)
  • Cross-references to other documentation

Alignment with AGENTS.md Standard:

✅ Repository purpose and scope
✅ Key workflows and automation boundaries
✅ Supported contribution actions
✅ Safe agent interaction guidance
✅ Cross-links for discoverability
✅ SDK-specific automation workflows
✅ All links use absolute URLs per Azure SDK guidelines

All changes have been committed and pushed to the branch.

Original prompt

This section details on the original issue you should resolve

<issue_title>Add AGENTS.md file</issue_title> <issue_description># 🧩 Add AGENTS.md file to align with AGENTS.md standards

📄 Description

This repository currently includes a .github/copilot-instructions.md file, but it does not yet have an AGENTS.md file to describe how AI agents (e.g., Copilot, MCP, or LLM-based assistants) should interact with this repository.

To align with emerging AGENTS.md standards and ensure consistent developer experiences across Azure SDK repositories, we should add a top-level AGENTS.md file that defines:

  • Repository purpose and scope
  • Key workflows, commands, and automation boundaries for agents
  • Supported contribution actions (e.g., PR triage, labeling, issue summarization)
  • Guidance for safe and effective agent interactions with CI/CD pipelines, SDK tests, and documentation

✅ Proposed Tasks

  • [ ] Review existing .github/copilot-instructions.md and identify relevant guidance to merge or reference in AGENTS.md.
  • [ ] Create an AGENTS.md file at the root of the repository following the canonical structure defined at AGENTS.md.
  • [ ] Cross-link between .github/copilot-instructions.md and AGENTS.md for discoverability.
  • [ ] (Optional) Add repository metadata in AGENTS.md to describe SDK-specific automation workflows (e.g., codegen, API review, test matrix).

📘 Example References

🧭 Context

This issue is part of a broader initiative to introduce AGENTS.md across all Azure SDK repositories (see the Azure SDK org overview) to standardize AI agent documentation and improve consistency in automation and Copilot-based contributions.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes Azure/azure-sdk-for-java#46954

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Copilot avatar Oct 09 '25 18:10 Copilot

@copilot, please fix these invalid links: ##[warning]Link has invalid format ../AGENTS.md ##[warning]DO NOT use relative link ../AGENTS.md. Please use absolute link instead. Check here for more information: https://aka.ms/azsdk/guideline/links ##[warning]Link has invalid format CONTRIBUTING.md ##[warning]DO NOT use relative link CONTRIBUTING.md. Please use absolute link instead. Check here for more information: https://aka.ms/azsdk/guideline/links ##[warning]Link has invalid format SECURITY.md ##[warning]DO NOT use relative link SECURITY.md. Please use absolute link instead. Check here for more information: https://aka.ms/azsdk/guideline/links ##[warning]broken link CONTRIBUTING.md ##[warning]Link has invalid format .github/copilot-instructions.md ##[warning]DO NOT use relative link .github/copilot-instructions.md. Please use absolute link instead. Check here for more information: https://aka.ms/azsdk/guideline/links ##[warning]Link has invalid format SUPPORT.md ##[warning]DO NOT use relative link SUPPORT.md. Please use absolute link instead. Check here for more information: https://aka.ms/azsdk/guideline/links ##[warning]broken link CONTRIBUTING.md ##[warning]Link has invalid format AGENTS.md ##[warning]DO NOT use relative link AGENTS.md. Please use absolute link instead. Check here for more information: https://aka.ms/azsdk/guideline/links

ronniegeraghty avatar Oct 10 '25 18:10 ronniegeraghty

@copilot, please fix these invalid links: ##[warning]Link has invalid format ../AGENTS.md ##[warning]DO NOT use relative link ../AGENTS.md. Please use absolute link instead. Check here for more inf...

Fixed all relative links to use absolute GitHub URLs. Changes in commit: [commit hash will be shown after push]

Updated links in:

  • AGENTS.md: 6 links converted to absolute URLs
  • .github/copilot-instructions.md: 1 link converted
  • README.md: 1 link converted

All links now follow the format: https://github.com/Azure/azure-sdk-for-java/blob/main/[filename]

Copilot avatar Oct 10 '25 18:10 Copilot

Hi @Copilot. Thank you for your interest in helping to improve the Azure SDK experience and for your contribution. We've noticed that there hasn't been recent engagement on this pull request. If this is still an active work stream, please let us know by pushing some changes or leaving a comment. Otherwise, we'll close this out in 7 days.

github-actions[bot] avatar Dec 12 '25 05:12 github-actions[bot]