Azure / Azure/azure-sdk-tools

Audit and deduplicate instruction files / skills between azsdk-cli and SDK language repos

Open
#15,665 0 comments 0 reactions 0 assignees View on GitHub
AzSDK Tools Agent
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 2h
Merged PRs (30d)
130

Description

## Problem

The Azure SDK Tools Agent (`azsdk-cli`) provides a set of skills/instructions, and the SDK language repos it's enabled in also have their own instruction files and skills (AGENTS.md, copilot-instructions, repo-local skills). These two layers can collide:

- The same workflow described differently between the agent skill and the repo skill
- Overlapping skills that give the agent conflicting information about what process to follow
- Cases where the repo's skill is ahead/behind the agent's skill

When these collide, the agent gets contradictory guidance and either picks one inconsistently or blends them in confusing ways.

## What we want

1. An audit of every skill / instruction file in:
- `azsdk-cli` (the agent itself)
- Each SDK language repo (Python, .NET, Java, JS/TS, Go, Rust, C++)
2. A map of where content overlaps or conflicts.
3. A deduplication plan that:
- Removes duplicated content (one source of truth per workflow)
- Keeps each layer focused on what only it can own (agent layer = cross-language workflow; repo layer = language-specific specifics)
- Leaves room for service teams and our team to work in the way they need to
4. Recommended layout for how repos should structure their skills vs. relying on the agent's skills.

## Notes

- Originally captured as a brain-dump draft during the SDK team → evals team handoff. Promoted to a real issue because this is a real risk to agent reliability and worth tracking.
- Related: the "common skill entry point" issue — these two together define how the skill surface should be organized.

/label "AzSDK Tools Agent"

Contributor guide

Open the contributing guide

Research direction

Start by inventorying skills and instruction files in azsdk-cli and the Python, .NET, Java, JS/TS, Go, Rust, and C++ SDK repositories, including AGENTS.md, copilot-instructions, and repo-local skills. Compare their workflows for overlap and conflicts, then document a source-of-truth and repository layout plan. Done means every listed repository is covered by an overlap map and deduplication recommendations.

Written by the indexing model from the issue text.

Assessment

Domain
developer-experience, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.