Add agent-guide: teach AI agents how to use APM#516
Merged
danielmeppiel merged 2 commits intomicrosoft:mainfrom Mar 31, 2026
Merged
Add agent-guide: teach AI agents how to use APM#516danielmeppiel merged 2 commits intomicrosoft:mainfrom
danielmeppiel merged 2 commits intomicrosoft:mainfrom
Conversation
Add a new agent-guide/ directory at the repo root containing two files that teach AI agents (and humans) how to install, use, and create APM packages: - SKILL.md: lightweight activation triggers and key rules for when an AI agent should reach for APM - apm-expert.agent.md: deep reference covering installation on all platforms (Linux, macOS, Windows, WSL), the full command reference, package authoring with all primitive formats, org-wide patterns, plugin development, and troubleshooting Placed at the repo root for immediate visibility to anyone cloning the repo or browsing on github.com. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
Author
|
@microsoft-github-policy-service agree company="Microsoft" |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an agent-guide/ directory intended to teach AI agents (and humans) how to install, use, and author APM packages, complementing the existing developer-focused guidance in .github/.
Changes:
- Added an activation skill (
agent-guide/SKILL.md) describing when to use APM and key usage rules. - Added a long-form "APM expert" agent persona (
agent-guide/apm-expert.agent.md) covering installation, workflows, CLI reference, and package authoring.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| agent-guide/SKILL.md | New skill file describing activation triggers and rules for using APM. |
| agent-guide/apm-expert.agent.md | New long-form agent persona / reference guide for APM usage, commands, and package authoring. |
Reorganize agent-guide/ into packages/apm-guide/ -- a proper APM subdirectory package that users can install with: apm install microsoft/apm/packages/apm-guide Architecture: skill-centric with bundled resources - SKILL.md index with activation triggers and key rules - 8 focused resource files (~40-150 lines each) for progressive disclosure: installation, workflow, commands, dependencies, authentication, governance, package-authoring, troubleshooting - Thin agent persona (~50 lines) linking to the skill for depth PROSE compliance: - Progressive Disclosure: SKILL.md loads first; resources on demand - Reduced Scope: each resource covers one domain - Orchestrated Composition: composable skill + agent + resources - Explicit Hierarchy: SKILL.md -> resources -> sections Content additions beyond original PR: - Authentication: token precedence, per-org, GHE, ADO, Artifactory - Governance: policy schema, enforcement, inheritance, audit - Dependencies: all 13+ ref formats, version pinning, MCP deps - Package authoring: all 7 primitive types with examples - Troubleshooting: error-to-fix lookup table Also extends doc-sync instruction (Rule 4) to keep skill resources synchronized when CLI commands, auth, policy, or formats change. Co-authored-by: Chris Bird <cabird@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This adds an
agent-guide/directory at the repo root with two files that teach AI agents (and humans) how to install, use, and create APM packages.What's included
SKILL.md-- Lightweight activation triggers and key rules. Tells an AI agent when to reach for APM (e.g., user asks about agent setup, project hasapm.yml, team needs reproducible agent config).apm-expert.agent.md-- Deep reference persona covering:Why
The existing
.github/skills/and.github/agents/files teach how to develop APM itself (auth patterns, CLI logging, Python architecture). There was nothing teaching an AI agent how to actually use APM as a tool -- install it, create packages, manage dependencies, etc.Placement
I placed this at the repo root (
agent-guide/) so it's immediately visible to anyone cloning the repo or browsing on github.com. Happy to move it elsewhere if the maintainers prefer a different location.