Skip to content

Commit d0c3e6a

Browse files
Python: Add installable Agent Framework builder skill (#9374)
* Python: Add Agent Framework consumer skill * Address consumer skill review feedback * Add Agent Skills validation workflow * Expand skill extension and deployment guidance * Document custom ContextProvider guidance * Add Agent Framework extensibility guide * Link volatile guidance to authoritative docs * Align consumer skill detail with documentation * Clarify provider settings resolution * Address Agent Skills review feedback * Address remaining Agent Skills review feedback Co-authored-by: Copilot App <[email protected]> Copilot-Session: 842af08a-f886-4564-b30a-9e7e9ebe324b * Keep consumer skill guidance repository-scoped Co-authored-by: Copilot App <[email protected]> Copilot-Session: 842af08a-f886-4564-b30a-9e7e9ebe324b * Address latest Agent Skills review feedback Co-authored-by: Copilot App <[email protected]> Copilot-Session: 842af08a-f886-4564-b30a-9e7e9ebe324b --------- Co-authored-by: Copilot App <[email protected]> Copilot-Session: 842af08a-f886-4564-b30a-9e7e9ebe324b
1 parent 1263843 commit d0c3e6a

17 files changed

Lines changed: 999 additions & 0 deletions

‎.github/CODEOWNERS‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,6 @@
1212

1313
# .NET owners
1414
/dotnet/ @eavanvalkenburg @SergeyMenshykh @rogerbarreto @westey-m @moonbox3 @baywet @peibekwe
15+
16+
# Public Python consumer skill
17+
/skills/agent-framework-builder-python/ @eavanvalkenburg @SergeyMenshykh @rogerbarreto @westey-m @moonbox3 @jpalvarezl @sophia-ramsey @TaoChenOSU @giles17

‎.github/copilot-instructions.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,19 @@ Microsoft Agent Framework - a multi-language framework for building, orchestrati
77
- `python/` - Python implementation → see [python/AGENTS.md](../python/AGENTS.md)
88
- `dotnet/` - C#/.NET implementation → see [dotnet/AGENTS.md](../dotnet/AGENTS.md)
99
- `docs/` - Design documents and architectural decision records
10+
- `skills/` - Public, installable Agent Skills for developers using Agent Framework
11+
12+
## Public Consumer Skills
13+
14+
The skills under `skills/` are distribution artifacts for developers building Agent Framework applications. They are
15+
not project skills for contributors working in this repository:
16+
17+
- Do not load or invoke them as instructions for normal Agent Framework repository work.
18+
- Keep them outside `.github/skills`, `.agents/skills`, and `.claude/skills` so coding agents do not auto-discover them.
19+
- When a change affects public APIs, packages, samples, configuration, evaluation, integrations, or hosting guidance,
20+
review and update the corresponding consumer skill as maintained product documentation.
21+
- Read a consumer skill during repository work only when that maintenance check is relevant; do not let its standalone
22+
application defaults override repository-specific instructions.
1023

1124
## Architectural Decision Records (ADRs)
1225

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
#!/usr/bin/env python3
2+
# Copyright (c) Microsoft. All rights reserved.
3+
"""Validate local Markdown resources bundled with public Agent Skills."""
4+
5+
from __future__ import annotations
6+
7+
import re
8+
import stat
9+
import sys
10+
from pathlib import Path
11+
from urllib.parse import urlsplit
12+
13+
INLINE_LINK_PATTERN = re.compile(r"!?\[[^\]\n]*\]\(\s*(<[^>\n]+>|[^)\s]+)")
14+
REFERENCE_DEFINITION_PATTERN = re.compile(r"(?m)^[ \t]{0,3}\[(?!\^)[^\]\n]+\]:[ \t]*(?:<([^>\n]+)>|(\S+))")
15+
REMOTE_SCHEMES = frozenset({"http", "https", "mailto"})
16+
17+
18+
def _markdown_targets(markdown: str) -> list[str]:
19+
targets = [match.group(1).removeprefix("<").removesuffix(">") for match in INLINE_LINK_PATTERN.finditer(markdown)]
20+
targets.extend(
21+
next(group for group in match.groups() if group is not None)
22+
for match in REFERENCE_DEFINITION_PATTERN.finditer(markdown)
23+
)
24+
return targets
25+
26+
27+
def validate_agent_skill_links(skills_directory: Path) -> list[str]:
28+
"""Return validation errors for local Markdown links in public Agent Skills."""
29+
errors: list[str] = []
30+
skill_roots = sorted(path.parent for path in skills_directory.rglob("SKILL.md"))
31+
32+
if not skill_roots:
33+
return [f"No Agent Skills found under {skills_directory}."]
34+
35+
for skill_root in skill_roots:
36+
resolved_root = skill_root.resolve(strict=True)
37+
for markdown_path in skill_root.rglob("*.md"):
38+
markdown = markdown_path.read_text(encoding="utf-8")
39+
for target in _markdown_targets(markdown):
40+
if target.startswith("#"):
41+
continue
42+
43+
target_path = Path(target)
44+
if target_path.is_absolute():
45+
errors.append(f"{markdown_path}: absolute local link is not allowed: {target}")
46+
continue
47+
48+
parsed_target = urlsplit(target)
49+
if parsed_target.scheme:
50+
if parsed_target.scheme.lower() in REMOTE_SCHEMES:
51+
continue
52+
errors.append(f"{markdown_path}: unsupported URI scheme: {target}")
53+
continue
54+
55+
relative_target = parsed_target.path
56+
if not relative_target:
57+
continue
58+
59+
target_path = Path(relative_target)
60+
candidate = markdown_path.parent / target_path
61+
try:
62+
resolved_candidate = candidate.resolve(strict=True)
63+
except FileNotFoundError:
64+
errors.append(f"{markdown_path}: missing local resource: {target}")
65+
continue
66+
67+
try:
68+
resolved_candidate.relative_to(resolved_root)
69+
except ValueError:
70+
errors.append(f"{markdown_path}: local resource escapes skill root: {target}")
71+
continue
72+
73+
if not stat.S_ISREG(candidate.lstat().st_mode):
74+
errors.append(f"{markdown_path}: local resource is not a regular file: {target}")
75+
76+
return errors
77+
78+
79+
def main() -> None:
80+
skills_directory = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("skills")
81+
errors = validate_agent_skill_links(skills_directory)
82+
if errors:
83+
raise SystemExit("\n".join(errors))
84+
85+
86+
if __name__ == "__main__":
87+
main()
Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Copyright (c) Microsoft. All rights reserved.
2+
3+
# ruff:file-ignore[implicit-namespace-package, undocumented-public-class, undocumented-public-method]
4+
5+
from __future__ import annotations
6+
7+
import sys
8+
import tempfile
9+
import unittest
10+
from pathlib import Path
11+
12+
sys.path.insert(0, str(Path(__file__).parents[1] / "scripts"))
13+
14+
from validate_agent_skill_links import validate_agent_skill_links
15+
16+
17+
class ValidateAgentSkillLinksTests(unittest.TestCase):
18+
def setUp(self) -> None:
19+
self.temp_dir = tempfile.TemporaryDirectory()
20+
self.root = Path(self.temp_dir.name)
21+
self.skills = self.root / "skills"
22+
self.skill = self.skills / "example-skill"
23+
self.skill.mkdir(parents=True)
24+
25+
def tearDown(self) -> None:
26+
self.temp_dir.cleanup()
27+
28+
def write_skill(self, body: str) -> None:
29+
(self.skill / "SKILL.md").write_text(body, encoding="utf-8")
30+
31+
def test_accepts_regular_file_inside_skill(self) -> None:
32+
(self.skill / "references").mkdir()
33+
(self.skill / "references" / "details.md").write_text("# Details\n", encoding="utf-8")
34+
self.write_skill("[Details](references/details.md)\n")
35+
36+
self.assertEqual([], validate_agent_skill_links(self.skills))
37+
38+
def test_accepts_reference_style_file_inside_skill(self) -> None:
39+
(self.skill / "references").mkdir()
40+
(self.skill / "references" / "details.md").write_text("# Details\n", encoding="utf-8")
41+
self.write_skill("[Details][resource]\n\n[resource]: references/details.md\n")
42+
43+
self.assertEqual([], validate_agent_skill_links(self.skills))
44+
45+
def test_accepts_remote_links_mailto_and_anchors(self) -> None:
46+
self.write_skill(
47+
"[HTTP](http://example.com)\n"
48+
"[HTTPS][secure]\n"
49+
"[Email](mailto:[email protected])\n"
50+
"[Section](#section)\n"
51+
"\n"
52+
"[secure]: https://example.com\n"
53+
)
54+
55+
self.assertEqual([], validate_agent_skill_links(self.skills))
56+
57+
def test_rejects_parent_traversal(self) -> None:
58+
(self.skills / "outside.md").write_text("# Outside\n", encoding="utf-8")
59+
self.write_skill("[Outside](../outside.md)\n")
60+
61+
errors = validate_agent_skill_links(self.skills)
62+
63+
self.assertTrue(any("escapes skill root" in error for error in errors))
64+
65+
def test_rejects_reference_style_parent_traversal(self) -> None:
66+
(self.skills / "outside.md").write_text("# Outside\n", encoding="utf-8")
67+
self.write_skill("[Outside][resource]\n\n[resource]: ../outside.md\n")
68+
69+
errors = validate_agent_skill_links(self.skills)
70+
71+
self.assertTrue(any("escapes skill root" in error for error in errors))
72+
73+
def test_rejects_absolute_path(self) -> None:
74+
absolute_file = self.root / "outside.md"
75+
absolute_file.write_text("# Outside\n", encoding="utf-8")
76+
self.write_skill(f"[Outside]({absolute_file})\n")
77+
78+
errors = validate_agent_skill_links(self.skills)
79+
80+
self.assertTrue(any("absolute local link" in error for error in errors))
81+
82+
def test_rejects_directory_target(self) -> None:
83+
(self.skill / "references").mkdir()
84+
self.write_skill("[References](references)\n")
85+
86+
errors = validate_agent_skill_links(self.skills)
87+
88+
self.assertTrue(any("not a regular file" in error for error in errors))
89+
90+
def test_rejects_symlink_target(self) -> None:
91+
target = self.skill / "details.md"
92+
target.write_text("# Details\n", encoding="utf-8")
93+
(self.skill / "linked.md").symlink_to(target)
94+
self.write_skill("[Details](linked.md)\n")
95+
96+
errors = validate_agent_skill_links(self.skills)
97+
98+
self.assertTrue(any("not a regular file" in error for error in errors))
99+
100+
def test_rejects_file_uri(self) -> None:
101+
self.write_skill("[Outside](file:///tmp/outside.md)\n")
102+
103+
errors = validate_agent_skill_links(self.skills)
104+
105+
self.assertTrue(any("unsupported URI scheme" in error for error in errors))
106+
107+
def test_rejects_unknown_uri_scheme(self) -> None:
108+
self.write_skill("[Outside](custom://example/resource)\n")
109+
110+
errors = validate_agent_skill_links(self.skills)
111+
112+
self.assertTrue(any("unsupported URI scheme" in error for error in errors))
113+
114+
def test_rejects_missing_target(self) -> None:
115+
self.write_skill("[Missing](references/missing.md)\n")
116+
117+
errors = validate_agent_skill_links(self.skills)
118+
119+
self.assertTrue(any("missing local resource" in error for error in errors))
120+
121+
122+
if __name__ == "__main__":
123+
unittest.main()

‎.github/workflows/agent-skills.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Validate Agent Skills
2+
3+
on:
4+
workflow_dispatch:
5+
pull_request:
6+
paths:
7+
- "skills/**"
8+
- ".github/scripts/validate_agent_skill_links.py"
9+
- ".github/tests/test_validate_agent_skill_links.py"
10+
- ".github/workflows/agent-skills.yml"
11+
push:
12+
branches: ["main"]
13+
paths:
14+
- "skills/**"
15+
- ".github/scripts/validate_agent_skill_links.py"
16+
- ".github/tests/test_validate_agent_skill_links.py"
17+
- ".github/workflows/agent-skills.yml"
18+
19+
permissions:
20+
contents: read
21+
22+
jobs:
23+
validate:
24+
runs-on: ubuntu-latest
25+
timeout-minutes: 10
26+
steps:
27+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
28+
29+
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
30+
with:
31+
python-version: "3.13"
32+
33+
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
34+
with:
35+
version-file: "python/pyproject.toml"
36+
37+
- name: Validate Agent Skills specification
38+
shell: bash
39+
run: |
40+
set -euo pipefail
41+
42+
found_skill=0
43+
while IFS= read -r skill_file; do
44+
[[ -z "$skill_file" ]] && continue
45+
found_skill=1
46+
uvx --from "skills-ref==0.1.1" agentskills validate "$(dirname "$skill_file")"
47+
done < <(find skills -mindepth 2 -maxdepth 2 -name SKILL.md -print | sort)
48+
49+
if (( found_skill == 0 )); then
50+
echo "No public Agent Skills found under skills/." >&2
51+
exit 1
52+
fi
53+
54+
- name: Validate relative resource links
55+
run: |
56+
python .github/tests/test_validate_agent_skill_links.py
57+
python .github/scripts/validate_agent_skill_links.py skills
58+
59+
- name: Validate GitHub skill publishing
60+
env:
61+
GH_TOKEN: ${{ github.token }}
62+
run: gh skill publish skills --dry-run

‎README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ Explore new MAF capabilities and real implementation patterns on the [official b
7070
- [Quickstart](#quickstart)
7171
- [Basic Agent - Python](#basic-agent---python)
7272
- [Basic Agent - .NET](#basic-agent---net)
73+
- [Agent Skills for Coding Agents](#agent-skills-for-coding-agents)
7374
- [More Examples & Samples](#more-examples--samples)
7475
- [Community & Feedback](#community--feedback)
7576
- [Troubleshooting](#troubleshooting)
@@ -161,6 +162,25 @@ AIAgent agent =
161162
Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
162163
```
163164

165+
## Agent Skills for Coding Agents
166+
167+
Install the Python Agent Framework builder skill to give a compatible coding agent current guidance for choosing and
168+
building agents, harnesses, workflows, evaluations, integrations, and hosting:
169+
170+
```bash
171+
gh skill install microsoft/agent-framework agent-framework-builder-python@main
172+
```
173+
174+
The explicit `@main` ref is required until a tagged Agent Framework release includes the skill.
175+
176+
The cross-agent `skills` CLI is also supported:
177+
178+
```bash
179+
npx skills add microsoft/agent-framework --skill agent-framework-builder-python
180+
```
181+
182+
See the [consumer skills catalog](./skills/) for details.
183+
164184
## More Examples & Samples
165185

166186
### Python

‎skills/README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Microsoft Agent Framework consumer skills
2+
3+
This directory contains installable Agent Skills for developers building applications with Microsoft Agent Framework.
4+
These are public distribution artifacts, not contributor instructions for working on the Agent Framework repository.
5+
6+
## Available skills
7+
8+
| Skill | Purpose |
9+
| --- | --- |
10+
| `agent-framework-builder-python` | Build, modify, evaluate, integrate, and host Python Agent Framework applications. |
11+
12+
## Install
13+
14+
Preview and install the default-branch version with GitHub CLI:
15+
16+
```bash
17+
gh skill preview microsoft/agent-framework agent-framework-builder-python@main
18+
gh skill install microsoft/agent-framework agent-framework-builder-python@main
19+
```
20+
21+
The explicit `@main` ref is required until a tagged Agent Framework release includes the skill. Until then,
22+
unqualified `gh skill` installs and search discovery can resolve an older release that does not contain it.
23+
24+
Or use the cross-agent skills CLI:
25+
26+
```bash
27+
npx skills add microsoft/agent-framework --skill agent-framework-builder-python
28+
```
29+
30+
## Repository maintenance contract
31+
32+
- Coding agents working on Agent Framework itself must not treat the skills in this directory as repository
33+
instructions or automatically load them for normal framework development.
34+
- Keep the skills outside `.github/skills`, `.agents/skills`, and `.claude/skills` so repository agents do not
35+
discover them as project skills.
36+
- Review the Python consumer skill whenever a change affects public APIs, package names or maturity, canonical samples,
37+
configuration, evaluation, integrations, or hosting guidance.
38+
- Update only the affected guidance. Do not copy internal contributor conventions into the consumer skill.

0 commit comments

Comments
 (0)