joslatjoslat/maf-doctor/.github/skills/maf-from-semantic-kernel/SKILL.md

maf-from-semantic-kernel

Skill14 starsChanged 3 months agoMITView on GitHub

Cross-framework migration map: Semantic Kernel (C#) → Microsoft Agent Framework. Load this skill when porting an SK app to MAF (NOT a MAF version bump). It is the smart index over docs/migration/from-semantic-kernel-to-maf.md — it tells you each SK construct's MAF target and its migration strategy (🌉 bridge / 🔁 rewrite / 🏗 re-architect), so you migrate construct-by-construct, side-by-side, non-destructively.

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
With the MCP server: run MafDetectSourceFramework(repoPath) (CLI: maf-doctor migrate-scan) for the inventory + EASY/MEDIUM/HARD verdict, …
line 79
Very specific:
Skills + agents only (no MCP): read the construct table above, then the matching section of docs/migration/from-semantic-kernel-to-maf.md, …
line 80

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Semantic Kernel → MAF — Migration Navigator

The full mapping is at docs/migration/from-semantic-kernel-to-maf.md (also served at maf://migrate-from?source=semantic-kernel when the MCP server is running).

This SKILL.md is the index — find the construct you're porting, read its strategy, then read that section of the guide. Migrate side-by-side: build a new MAF project beside the original SK project; never edit the SK code until the user switches over.

This is a cross-framework migration, not a version upgrade. For "upgrade MAF 1.x → 1.y" use maf-migration-guide instead.

Strategy legend

Tag	Meaning	Do this
🌉 bridge	Reuse the SK code as-is via an interop shim.	Lowest risk — prefer it. Keep the SK asset, wrap it.
🔁 rewrite	Mechanical SK→MAF API swap (1:1 target).	Follow the guide's before/after.
🏗 re-architect	No 1:1 mapping — redesign onto MAF workflows / providers.	Needs judgment — propose, confirm, then build.

Construct → MAF target → strategy (the lookup)

SK construct	MAF target	Strategy	Guide §
`Kernel` / `IKernelBuilder`	removed — create the agent straight from the chat client	🔁	2
`ChatCompletionAgent`	`chatClient.AsAIAgent(instructions:, tools:)` → `ChatClientAgent`	🔁	2
`AzureAIAgent` / `OpenAIAssistantAgent`	`aiProjectClient.AsAIAgent(...)` / `assistantClient.CreateAIAgentAsync(...)`	🔁	2
`IChatCompletionService`	bridge `.AsChatClient()` → `IChatClient`, or a provider `IChatClient`	🌉	11
`[KernelFunction]` plugin	bridge `KernelFunction.AsAIFunction()`, or a plain `[Description]` method in `tools:`	🌉	5 / 8
`KernelPlugin` / `KernelPluginFactory`	no plugin concept — pass methods to `tools:`	🌉 / 🔁	5
`AgentThread` / `*AgentThread`	`await agent.CreateSessionAsync()` → `AgentSession`	🔁	3 / 4
`InvokeAsync` / `InvokeStreamingAsync` (agent)	`RunAsync` / `RunStreamingAsync` → `AgentResponse` / `AgentResponseUpdate`	🔁	6 / 7
`kernel.InvokeAsync(fn)` (function)	call the tool directly, or rely on automatic function-calling	🔁	5
`KernelArguments` / `AgentInvokeOptions` / `*PromptExecutionSettings`	`ChatOptions` / `ChatClientAgentRunOptions`	🔁	9
Structured output (`responseFormat`)	`ChatResponseFormat.ForJsonSchema<T>()` or typed `RunAsync<T>`	🔁	"Beyond the official page"
`ChatHistory`	`ChatHistoryProvider` / `InMemoryChatHistoryProvider` / `await agent.SerializeSessionAsync(session)` (async — the sync `SerializeSession` is gone on 1.3.0+)	🔁	"Beyond the official page"
Function-invocation filters (`IFunctionInvocationFilter`, …)	agent middleware via `.AsBuilder().Use(...)`	🔁	"Beyond the official page"
`AddOpenTelemetry` (kernel-level)	`.UseOpenTelemetry()` on the `IChatClient` chain	🔁	"Beyond the official page"
`AgentGroupChat`	a MAF group-chat workflow (`AgentWorkflowBuilder.CreateGroupChatBuilderWith`)	🏗	"Multi-agent"
Planners (`FunctionCallingStepwisePlanner`, `HandlebarsPlanner`, …)	removed — automatic function-calling loop	🏗	"Multi-agent"
Prompt templates (`KernelPromptTemplate`, Handlebars/Liquid, `KernelFunctionFromPrompt`)	render externally → pass as `instructions`, or a Context Provider	🏗	"Beyond the official page"
Vector stores / RAG (`IVectorStore`, `ITextSearch`, …)	`TextSearchProvider` via `AIContextProviders`	🏗	"Beyond the official page"
Hand-rolled memory injection	an `AIContextProvider` (no SK type — find it by reading the code)	🏗	"Beyond the official page"

Interop bridges (the gradual / side-by-side enabler)

There is no SK→MAF converter. The official aid is a set of C# interop bridges that let MAF reuse SK assets as-is (so SK + MAF can run side by side):

IChatCompletionService.AsChatClient() → IChatClient (reverse: IChatClient.AsChatCompletionService()).
KernelFunction.AsAIFunction(Kernel?) → AIFunction (reverse: AIFunction.AsKernelFunction()).
Bulk: kernel.Plugins.SelectMany(p => p).Select(f => f.AsAIFunction()).

Bridge first, rewrite when ready. See the guide's "Interop bridges" section for the exact namespaces.

Recommended order (for the plan)

Packages & namespaces — swap Microsoft.SemanticKernel* for Microsoft.Agents.AI + Microsoft.Extensions.AI (+ provider client).
Tools first — [KernelFunction] → plain methods (AIFunctionFactory.Create) — agents depend on them.
Agents — …Agent { Kernel = … } → client.AsAIAgent(instructions:, tools:); drop the Kernel.
Threads → sessions — new …AgentThread() → await agent.CreateSessionAsync().
Invocation — Invoke*Async → Run*Async.
Options & DI — KernelArguments / execution-settings → ChatClientAgentRunOptions / ChatOptions; AddKernel → AddKeyedSingleton<AIAgent>.
Multi-agent / planners / memory / filters — re-architect onto MAF workflows + middleware + Context Providers.
Validate — maf-doctor doctor on the migrated project; it should be anti-pattern clean.

How to drive this

With the MCP server: run MafDetectSourceFramework(repoPath) (CLI: maf-doctor migrate-scan) for the inventory + EASY/MEDIUM/HARD verdict, then the maf-migrate-from prompt to plan → scaffold → port.
Skills + agents only (no MCP): read the construct table above, then the matching section of docs/migration/from-semantic-kernel-to-maf.md, and port one construct at a time. dotnet build the new project after each — green before moving on.

⚠ The two "no type signature" rows (hand-rolled memory, multi-agent beyond group chat) won't appear in the scan — review the code for them by hand.

Download now (ZIP)

In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- cs0618-hunterSkill
- dotnet-inspectSkill
- maf-anti-pattern-scannerSkill
- maf-doctor-self-evolutionSkill
- maf-fan-out-validatorSkill
- maf-issue-reporterSkill
- maf-migration-guideSkill
- maf-migration-plan-creatorSkill
- maf-migration-retrospectiveSkill
- maf-obsolete-api-registrySkill
- maf-release-watcherSkill
- maf-remediation-playbookSkill
- maf-workflow-smoke-testerSkill
- nuget-diff-analyzerSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free