Azure · kaylieee · Apr 30, 2026 · dargilco · May 1, 2026
@@ -22,4 +22,6 @@ you already know the package well.
 
 | Package                    | Path                                                                                              |
 | -------------------------- | ------------------------------------------------------------------------------------------------- |
+| `azure-ai-agents`          | `sdk/ai/azure-ai-agents/.github/skills/azure-ai-agents/SKILL.md`                                  |
+| `azure-ai-projects`        | `sdk/ai/azure-ai-projects/.github/skills/azure-ai-projects/SKILL.md`                              |
 | `azure-search-documents`   | `sdk/search/azure-search-documents/.github/skills/azure-search-documents/SKILL.md`                |
@@ -0,0 +1,171 @@
+---
+name: api-diff
+description: 'Diff the Java SDK to identify new API features added between commits or branches. Buckets new additions by functionality (e.g. agents, toolboxes, sessions, memory, skills). WHEN: what is new in the API; diff API changes; compare API between branches; see what changed in the SDK; new API additions.'
+---
+
+# API Diff — Identify New Features
+
+Diff the generated Java SDK source to identify new public API additions (methods, models, clients) and bucket them by functionality area.
+
+## Preconditions
+
+- You must be in `sdk/ai/azure-ai-agents` or `sdk/ai/azure-ai-projects`.
+- The user must provide a **base reference** to diff against: a commit hash, branch name, or tag. If not provided, ask for it (e.g. `main`, `HEAD~1`, a specific commit).
+
+## Workflow
+
+### 1. Determine the diff range
+
+Ask for or infer:
+- **Base**: the starting point (e.g. `main`, a commit hash, a tag)
+- **Head**: the current state (defaults to working tree / `HEAD`)
+
+### 2. Get the raw diff of public API files
+
+Diff only the public-facing source files (exclude implementation, tests, samples):
+
+```bash
+# For azure-ai-agents
+git diff <base> -- \
+  src/main/java/com/azure/ai/agents/*Client.java \
+  src/main/java/com/azure/ai/agents/*AsyncClient.java \
+  src/main/java/com/azure/ai/agents/models/
+
+# For azure-ai-projects
+git diff <base> -- \
+  src/main/java/com/azure/ai/projects/*Client.java \
+  src/main/java/com/azure/ai/projects/*AsyncClient.java \
+  src/main/java/com/azure/ai/projects/models/
+```
+
+To see only new files:
+```bash
+git diff <base> --name-status --diff-filter=A -- src/main/java/
+```
+
+To see only modified files:
+```bash
+git diff <base> --name-status --diff-filter=M -- src/main/java/
+```
+
+### 3. Extract new public methods
+
+For each client class, find newly added public methods:
+
+```bash
+git diff <base> -- src/main/java/com/azure/ai/agents/*Client.java | grep "^+" | grep "public "
+```
+
+Focus on convenience methods (skip `*WithResponse` protocol methods unless they have no convenience equivalent).
+
+### 4. Extract new models
+
+Find newly added model classes:
+
+```bash
+git diff <base> --name-status --diff-filter=A -- src/main/java/com/azure/ai/agents/models/
+```
+
+For modified models, find new fields/getters:
+
+```bash
+git diff <base> -- src/main/java/com/azure/ai/agents/models/<Model>.java | grep "^+" | grep "public \|private "
+```
+
+### 5. Bucket by functionality
+
+Categorize each new addition into a functionality area. Use **two sources** for bucket names: the known-buckets table below and dynamic discovery from the diff itself.
+
+#### 5a. Discover buckets dynamically
+
+Scan the current client classes to find all feature areas — don't rely solely on the table:
+
+```bash
+# List all client class names (each maps to a bucket)
+ls src/main/java/com/azure/ai/agents/*Client.java 2>/dev/null | sed 's/.*\///' | sed 's/Client.java//' | sort -u
+ls src/main/java/com/azure/ai/projects/*Client.java 2>/dev/null | sed 's/.*\///' | sed 's/Client.java//' | sort -u
+```
+
+Each `*Client.java` defines a top-level bucket. Methods within `AgentsClient` that share a resource prefix (e.g., `createSession`, `getSession`, `deleteSession`) form sub-buckets.
+
+For new models without a clear client, bucket by the model's package or the client method that references it.
+
+#### 5b. Known buckets (reference, may be incomplete)
+
+This table is a **starting point** — new feature areas may exist that aren't listed here. If you discover a new bucket during the diff, add it to this table and note it in your output.
+
+| Bucket | Client class | Method/model indicators |
+|--------|-------------|------------------------|
+| **Agents** | `AgentsClient` | `createAgent`, `deleteAgent`, `getAgent`, `listAgents`, `AgentVersionDetails`, `PromptAgentDefinition` |
+| **Hosted Agents** | `AgentsClient` | `HostedAgentDefinition`, `AgentProtocol`, `ProtocolVersionRecord`, methods with `HOSTED_AGENTS_V1_PREVIEW` |
+| **Sessions** | `AgentsClient` | `createSession`, `getSession`, `deleteSession`, `listSessions`, `AgentSessionResource` |
+| **Agent Endpoints** | `AgentsClient` | `patchAgentObject`, `AgentEndpoint`, `VersionSelector`, methods with `AGENT_ENDPOINT_V1_PREVIEW` |
+| **Toolboxes** | `ToolboxesClient` | `createToolboxVersion`, `getToolbox`, `updateToolbox`, `deleteToolbox`, `ToolboxDetails`, `ToolboxVersionDetails` |
+| **Memory** | `MemoryStoresClient` | `createMemoryStore`, `getMemoryStore`, `deleteMemoryStore`, `MemoryStoreDetails` |
+| **Conversations** | `AgentsClient` | `createConversation`, `getConversation`, `deleteConversation`, `ConversationDetails` |
+| **Responses** | `ResponsesClient` | `createResponse`, response-related models |
+| **Session Files** | `AgentSessionFilesClient` | `uploadFile`, `listFiles`, `getFile`, `deleteFile` |
+| **Tools** | models package | `McpTool`, `CodeInterpreterTool`, `FileSearchTool`, `AzureAISearchTool`, `OpenApiTool`, `Tool` subclasses |
+| **Skills** | `SkillsClient` | `createSkill`, `getSkill`, `deleteSkill`, `listSkills`, `SkillDetails` |
+| **Connections** | `ConnectionsClient` | `getConnection`, `listConnections`, `ConnectionDetails` |
+| **Datasets** | `DatasetsClient` | dataset operations |
+| **Deployments** | `DeploymentsClient` | deployment operations |
+| **Indexes** | `IndexesClient` | index operations |
+| **Evaluations** | `EvaluatorsClient`, `EvaluationRulesClient` | evaluation operations |
+
+#### 5c. Keeping this table current
+
+If you created a new bucket during this diff, **update this SKILL.md** to add it to the table above. This keeps the table useful for future runs. Add a row with the bucket name, the client class, and a few representative method/model indicators.
+
+```bash
+# Path to this skill file (for self-update)
+# sdk/ai/.github/skills/api-diff/SKILL.md
+```
+
+### 6. Output the summary
+
+Present findings as a structured summary:
+
+```
+## New API Additions (<base> → <head>)
+
+### Agents
+- New method: `AgentsClient.createAgentFromManifest(...)` 
+- New model: `CreateAgentFromManifestInput`
+
+### Toolboxes
+- New client: `ToolboxesClient` (entirely new)
+- New methods: createToolboxVersion, getToolbox, updateToolbox, ...
+- New models: ToolboxDetails, ToolboxVersionDetails, ToolboxPolicies
+
+### Memory
+- New method: `MemoryStoresClient.searchMemoryStore(...)`
+- New model: `MemorySearchResult`
+
+### Models (cross-cutting)
+- New field on `AgentVersionDetails`: `containerProtocolVersions`
+- Modified: `FixedRatioVersionSelectionRule.trafficPercentage` type changed int → Integer
+```
+
+## Tips
+
+- Use `git diff --stat` for a quick overview of what changed
+- Use `git log --oneline <base>..HEAD -- src/main/java/` to see commits that touched the source
+- For large diffs, focus on client classes first (they define the public API surface), then drill into models
+- New clients (entirely new `*Client.java` files) indicate a major new feature area
+- New `*OptInKeys` or `Foundry-Features` values indicate preview features
+
+## Example Usage
+
+User: "What's new since the last release?"
+```bash
+# Find the last release tag
+git tag --list "azure-ai-agents_*" --sort=-version:refname | head -1
+# Diff against it
+git diff <tag> -- src/main/java/com/azure/ai/agents/
+```
+
+User: "What changed in this PR branch?"
+```bash
+git diff main -- src/main/java/
+```
@@ -0,0 +1,50 @@
+---
+name: codegen-survival-rules
+description: 'Rules for making manual edits survive TypeSpec Java codegen re-generation. Covers @Generated removal, marker comment placement, and javadoc preservation. WHEN: edit generated code; survive codegen; @Generated annotation; marker comment placement; manual edits to generated files.'
+---
+
+# Codegen Survival Rules
+
+The TypeSpec Java codegen (`tsp-client update` / `tsp-client generate`) re-generates files on every run. Methods **without** `@Generated` are preserved (body intact), but everything **above** the method signature (javadoc, comments) is regenerated. Follow these rules so your manual edits survive.
+
+## Rules
+
+1. **Remove `@Generated`** from any method you modify. The codegen will not overwrite the method body.
+2. **Place marker comments inside the method body**, not above the signature. The codegen rewrites the javadoc block above the signature but does not touch the body.
+3. **Place javadoc above the method** normally. Since the method lacks `@Generated`, the codegen preserves the javadoc you wrote.
+4. **For field declarations**, place marker comments on the same line (trailing), not on the line above. The codegen regenerates the comment block above the field.
+
+## Examples
+
+```java
+// ✅ SURVIVES codegen: javadoc above, marker inside body
+/**
+ * Gets the reasoning configuration.
+ * @return the reasoning, or null if not set.
+ */
+public com.openai.models.Reasoning getReasoning() {
+    // AI Tooling: openai-java de-dup  ← inside body, survives
+    return this.reasoning;
+}
+
+// ❌ WIPED by codegen: marker above signature
+// AI Tooling: openai-java de-dup  ← above signature, gets wiped
+public com.openai.models.Reasoning getReasoning() {
+    return this.reasoning;
+}
+
+// ✅ SURVIVES codegen: field marker on same line
+private com.openai.models.Reasoning reasoning; // AI Tooling: openai-java de-dup
+
+// ❌ WIPED by codegen: field marker on line above
+// AI Tooling: openai-java de-dup
+private com.openai.models.Reasoning reasoning;
+```
+
+## When to apply
+
+These rules apply whenever you hand-edit a generated model class, including:
+- De-duplicating against openai-java types (see `dedup-openai` skill)
+- Overriding TypeSpec types with Java-native types (see `tsp-type-override` skill)
+- Adding typed union wrappers over `BinaryData` properties (see `union-type-wrappers` skill)
+- Any other manual customization of generated `toJson`/`fromJson` methods
@@ -0,0 +1,61 @@
+---
+name: codegen
+description: 'Generate code from TypeSpec via tsp-client (update, sync, generate). Requires a tsp-location.yaml in the current working directory. Supports updating the commit hash before running. WHEN: generate code from TypeSpec; run tsp-client; update TypeSpec commit; sync TypeSpec; regenerate SDK.'
+---
+
+# TypeSpec Code Generation (tsp-client)
+
+Use this skill to run `tsp-client` workflows for projects that include a `tsp-location.yaml` file.
+
+## Preconditions
+- You must be in the directory that contains `tsp-location.yaml`.
+- If the file is missing, warn the user and ask for the correct directory (do not run commands).
+
+## Commit hash update
+If the user provides a commit hash, update the `commit:` field in `tsp-location.yaml` **before** running tsp-client.
+- Read the file and locate the `commit:` line.
+- Replace the value with the provided hash (keep the same key name and formatting).
+- Example:
+  - Before: `commit: 6267b6...`
+  - After:  `commit: <new_hash>`
+
+## Commands
+
+### `tsp-client update`
+Pull the latest codegen tooling or definitions (default action when the user is vague).
+```bash
+tsp-client update
+```
+
+### `tsp-client sync`
+Fetch/sync TypeSpec inputs for the project.
+```bash
+tsp-client sync
+```
+
+### `tsp-client generate`
+Generate code from TypeSpec inputs.
+```bash
+tsp-client generate
+```
+
+Keep the synced TypeSpec inputs:
+```bash
+tsp-client generate --save-inputs
+```
+
+## Steps
+1. Verify `tsp-location.yaml` exists in the current directory. If not, stop and ask for the correct location.
+2. If the user provided a commit hash, update the `commit:` value in `tsp-location.yaml`.
+3. Determine the user intent:
+   - **Refresh/update/ingest changes from a commit**: run `tsp-client update`.
+   - **Fetch/sync spec from the current commit**: run `tsp-client sync`.
+   - **Generate from fetched spec**: run `tsp-client generate` (use `--save-inputs` only if the user asks to keep inputs).
+   - **Generate (no fetch requested)**: run `tsp-client generate`.
+4. If the user doesn’t specify, default to `tsp-client update`.
+5. If the project defines or creates a `TempTypeSpecFiles` folder and the user wants code generation, run `tsp-client generate` (with `--save-inputs` if requested).
+6. If a tsp-client command fails, report the error output and suggest checking the TypeSpec repo/commit referenced in `tsp-location.yaml`. Build a GitHub URL from `repo:` and `directory:` (and include the `commit:` as the ref), e.g.:
+   - Repo: `Azure/azure-rest-api-specs`
+   - Commit: `6267b6...`
+   - Directory: `specification/cognitiveservices/OpenAI.Inference`
+   - URL: `https://github.com/Azure/azure-rest-api-specs/tree/6267b6.../specification/cognitiveservices/OpenAI.Inference`