docs(ai): Add initial AI instruction files #15772
Conversation
There was a problem hiding this comment.
Pull request overview
Adds initial agent-facing documentation and skill placeholders to support AI-assisted workflows in the Azure Linux repo (phase 1 of the AI repo tooling plan), including a root entrypoint guide and directory-specific guidance.
Changes:
- Introduces root and per-directory
AGENTS.mdguides (repo, components, distro config). - Adds initial
.github/copilot-instructions.mdwith repo layout, concepts, and CLI reference. - Adds placeholder skill files for common tasks (
azl-add-component,azl-build-component,azl-fix-overlay).
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 |
|---|---|
AGENTS.md |
Root agent guide linking to skills and directory-specific guidance. |
base/comps/AGENTS.md |
Component-management rules and links to relevant skills/schema. |
distro/AGENTS.md |
Distro config guidance and build-default pointers. |
.github/copilot-instructions.md |
Main Copilot instruction doc: layout, concepts, CLI reference, hygiene rules. |
.github/skills/azl-add-component/SKILL.md |
Placeholder skill definition for adding components. |
.github/skills/azl-build-component/SKILL.md |
Placeholder skill definition for building/debugging components. |
.github/skills/azl-fix-overlay/SKILL.md |
Placeholder skill definition for diagnosing overlay issues. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Task | Skill | | ||
| |------|-------| | ||
| | Build a component, debug build failures | [`azl-build-component`](.github/skills/azl-build-component/SKILL.md) | | ||
| | Add a new component to the distro | [`azl-add-component`](.github/skills/azl-add-component/SKILL.md) | | ||
| | Diagnose and fix overlay issues | [`azl-fix-overlay`](.github/skills/azl-fix-overlay/SKILL.md) | |
There was a problem hiding this comment.
The markdown table is using double leading pipes (|| ... |), which GitHub Markdown does not treat as a normal table header and will render incorrectly (extra empty column / malformed table). Use standard table syntax with single pipes (e.g., | Task | Skill | and matching separator row).
| | Task | Command | | ||
| |------|---------| | ||
| | List all components | `azldev comp list -a` | | ||
| | Query a component | `azldev comp query -p <name>` | | ||
| | Add a component | `azldev comp add` | |
There was a problem hiding this comment.
This command table uses || at the start of each row, which breaks standard GitHub Markdown table rendering. Switch to single-pipe table syntax so the CLI reference formats correctly.
| "overlay error", "fix overlay", "overlay not applying", "spec-search-replace | ||
| failed", "overlay debug". |
There was a problem hiding this comment.
The trigger phrase "spec-search-replace failed" is split across a line break inside the description block, which hurts readability and may impact any downstream trigger matching. Keep each trigger on one line (or format triggers as a bullet list) so phrases aren’t broken mid-word.
| "overlay error", "fix overlay", "overlay not applying", "spec-search-replace | |
| failed", "overlay debug". | |
| "overlay error", "fix overlay", "overlay not applying", "spec-search-replace failed", "overlay debug". |
|
@dmcilvaney What feedback are you looking for? Are these really placeholders? And if so, does that mean corrections / clarifications aren't useful? |
2 participants
Implement phase 1 of #15628