{"id":51593312,"url":"https://github.com/leestott/learnskill-agent-foundrylocal","last_synced_at":"2026-07-11T16:30:54.910Z","repository":{"id":337838640,"uuid":"1154961743","full_name":"leestott/learnskill-agent-foundrylocal","owner":"leestott","description":"Generate comprehensive onboarding documentation for any repository using a hybrid AI approach:  Foundry Local for privacy-sensitive local inference (no data leaves your machine) Microsoft Foundry for cloud-hosted models with higher quality and faster inference Copilot SDK patterns for orchestration and multi-step workflows Agent Skills for reusable","archived":false,"fork":false,"pushed_at":"2026-02-11T15:50:06.000Z","size":2387,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-11T22:41:47.033Z","etag":null,"topics":["docs-generator","foundry","foundry-local","github","github-copilot-sdk","llm","slm"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leestott.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-11T00:58:54.000Z","updated_at":"2026-02-11T15:50:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/leestott/learnskill-agent-foundrylocal","commit_stats":null,"previous_names":["leestott/learnskill-agent-foundrylocal"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/leestott/learnskill-agent-foundrylocal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leestott%2Flearnskill-agent-foundrylocal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leestott%2Flearnskill-agent-foundrylocal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leestott%2Flearnskill-agent-foundrylocal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leestott%2Flearnskill-agent-foundrylocal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leestott","download_url":"https://codeload.github.com/leestott/learnskill-agent-foundrylocal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leestott%2Flearnskill-agent-foundrylocal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35368766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs-generator","foundry","foundry-local","github","github-copilot-sdk","llm","slm"],"created_at":"2026-07-11T16:30:53.982Z","updated_at":"2026-07-11T16:30:54.896Z","avatar_url":"https://github.com/leestott.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Repo Onboarding Pack Generator\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)\n[![Foundry Local](https://img.shields.io/badge/Foundry%20Local-Compatible-purple.svg)](https://github.com/microsoft/foundry)\n[![Microsoft Foundry](https://img.shields.io/badge/Microsoft%20Foundry-Cloud%20Ready-0078D4.svg)](https://ai.azure.com/)\n[![GitHub Copilot](https://img.shields.io/badge/Copilot-Agent%20Skill-orange.svg)](https://github.com/features/copilot)\n[![Copilot SDK](https://img.shields.io/badge/Copilot_SDK-0.1.23-6f42c1.svg)](https://github.com/github/copilot-sdk)\n[![Microsoft Learn MCP](https://img.shields.io/badge/Learn_MCP-Integrated-0078D4?logo=microsoft)](https://github.com/MicrosoftDocs/mcp)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/🚀_Hybrid_AI-Documentation_Generator-blueviolet?style=for-the-badge\" alt=\"Hybrid AI Documentation Generator\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eGenerate comprehensive onboarding documentation for any repository using hybrid AI\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#web-ui\"\u003eWeb UI\u003c/a\u003e •\n  \u003ca href=\"#cli-usage\"\u003eCLI\u003c/a\u003e •\n  \u003ca href=\"#agent-skill\"\u003eAgent Skill\u003c/a\u003e •\n  \u003ca href=\"#using-with-vs-code-copilot-chat\"\u003eCopilot Chat\u003c/a\u003e •\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Features\n\nGenerate comprehensive onboarding documentation for any repository using a hybrid AI approach:\n- **Foundry Local** for privacy-sensitive local inference (no data leaves your machine)\n- **Microsoft Foundry** for cloud-hosted models with higher quality and faster inference\n- **GitHub Copilot SDK** (`@github/copilot-sdk`) for agentic workflows via the Copilot CLI\n- **Agent Skills** for reusable, teachable AI behaviors\n\n## Quick Start\n\n```bash\n# One-command setup (checks Node.js, Git, installs deps, verifies TypeScript, configures .env)\nnpm run setup\n\n# Or on Windows directly:  .\\setup.ps1\n# Or on Linux/macOS:       chmod +x setup.sh \u0026\u0026 ./setup.sh\n```\n\nOnce setup completes, pick a mode:\n\n```bash\n# Run with Foundry Local (privacy-preserving)\nnpm run onboard -- https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator\n\n# Run with Microsoft Foundry (cloud   higher quality)\nnpm run onboard -- https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator \\\n  --cloud-endpoint https://your-resource.cognitiveservices.azure.com/openai/deployments/ \\\n  --cloud-api-key YOUR_API_KEY \\\n  --cloud-model gpt-4o-mini\n\n# Run with GitHub Copilot SDK (requires Copilot CLI)\nnpm run onboard -- https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator \\\n  --copilot-sdk --copilot-model claude-sonnet-4\n```\n\n## What It Generates\n\n| File | Purpose |\n|------|---------|\n| `ONBOARDING.md` | Architecture overview, key flows, dependency map, **instructor section** with learning outcomes and session plan |\n| `RUNBOOK.md` | Build, run, test commands + troubleshooting |\n| `TASKS.md` | 10 starter tasks with acceptance criteria, hints, and **learning objectives** per task |\n| `AGENTS.md` | Agent skills, MCP servers, workflows (incl. code-review), and **GitHub Copilot usage guide** |\n| `VALIDATION.md` | Microsoft Learn validation queries \u0026 checklist (when MS tech detected) |\n| `diagram.mmd` | Mermaid component diagram |\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│  Interfaces                                                      │\n│  ┌──────────────────────┐    ┌──────────────────────┐           │\n│  │    CLI (index.ts)     │    │  Web UI (server.ts)  │           │\n│  │  Commander parsing    │    │  HTTP + SSE progress │           │\n│  └──────────┬───────────┘    └──────────┬───────────┘           │\n│             └────────────┬──────────────┘                        │\n│                          ▼                                       │\n│  ┌──────────────────────────────────────────────────────┐       │\n│  │              Orchestrator (orchestrator.ts)           │       │\n│  │  9-step pipeline · tool-calling pattern · progress CB│       │\n│  ├───────┬──────────────┬───────────────┬───────────────┤       │\n│  │       ▼              ▼               ▼               │       │\n│  │ RepoScanner    LocalModelClient  CopilotSdkClient    │       │\n│  │ (repoScanner   (localModelClient (copilotSdkClient   │       │\n│  │   .ts)           .ts)              .ts)               │       │\n│  │ · Languages    · Foundry Local   · @github/copilot   │       │\n│  │ · Build sys    · Azure Foundry     -sdk (v0.1.23)    │       │\n│  │ · Deps         · OpenAI-compat   · BYOK providers    │       │\n│  │ · Structure    · File summary    · Session mgmt      │       │\n│  └───────┴──────────────┴───────────────┴───────────────┘       │\n│                                                                  │\n│  Shared: types.ts (interfaces) · validation.ts (input safety)   │\n└──────────────────────────────────────────────────────────────────┘\n                          │\n          ┌───────────────┼───────────────┐\n          ▼               ▼               ▼\n   Foundry Local    Microsoft Foundry   Copilot CLI\n   localhost:PORT   *.cognitiveservices  JSON-RPC\n   (on-device GPU)  .azure.com (cloud)  (GitHub auth)\n```\n\nThe project has **8 source files** in `src/`:\n\n| File | Role |\n|------|------|\n| `index.ts` | CLI entry point   Commander argument parsing |\n| `server.ts` | Web UI   HTTP server with SSE progress streaming |\n| `orchestrator.ts` | 9-step generation pipeline with tool-calling pattern |\n| `localModelClient.ts` | LLM client for Foundry Local and Microsoft Foundry (OpenAI-compatible) |\n| `copilotSdkClient.ts` | LLM client for GitHub Copilot SDK (`@github/copilot-sdk`) |\n| `repoScanner.ts` | Repository analysis   languages, deps, build systems, structure |\n| `types.ts` | Shared TypeScript interfaces |\n| `validation.ts` | Input validation and security checks |\n\n## Hybrid AI Approach\n\nThis tool supports three inference backends   use whichever fits your needs:\n\n### Foundry Local (Privacy-First)\n\nAll processing stays on your machine:\n\n- **File summarization**: Analyze source code content locally\n- **Config pattern extraction**: Identify configuration without exposing secrets\n- **Dependency inventory**: Generate descriptions for packages\n- **Architecture inference**: Determine patterns from structure\n\n\u003e Install: `winget install Microsoft.FoundryLocal`   see [Starting Foundry Local](#starting-foundry-local)\n\n### Microsoft Foundry (Cloud)\n\nHigher-quality output using cloud-hosted models:\n\n- **Larger models**: Access GPT-4o, Phi-4, DeepSeek-R1, and more\n- **Faster inference**: No GPU required on your machine\n- **Same workflow**: Identical 9-step pipeline, just a different backend\n- **OpenAI-compatible**: Works with any Microsoft Foundry deployment\n\n\u003e Get started at [ai.azure.com](https://ai.azure.com/)   see [Cloud Usage](#cloud-usage)\n\n### GitHub Copilot SDK\n\nAgentic workflows using the official [`@github/copilot-sdk`](https://github.com/github/copilot-sdk):\n\n- **Session-based**: Stateful conversations with plan/execute capabilities\n- **BYOK support**: Connect to Foundry Local, Azure OpenAI, or other OpenAI-compatible endpoints\n- **Tool-calling**: Define custom tools the agent can invoke during generation\n- **Multiple models**: Access GPT-4o, Claude Sonnet, and more via GitHub Copilot\n\n\u003e Requires: `npm install -g @github/copilot`   see [Copilot SDK Usage](#copilot-sdk-usage)\n\n### What the Copilot Agent Does\n\nOrchestration and coordination (same for both backends):\n\n- **Workflow planning**: Sequence the analysis steps\n- **File operations**: Write generated documentation\n- **Command execution**: Run build/test verification\n- **Cross-file analysis**: Understand relationships\n\n## GitHub Copilot SDK Integration\n\nThis project uses the official [`@github/copilot-sdk`](https://github.com/github/copilot-sdk) (v0.1.23) for agentic AI workflows. The SDK communicates with the Copilot CLI via JSON-RPC, providing session management, tool-calling, and BYOK (Bring Your Own Key) support.\n\n### Copilot Tool-Calling Pattern\n\nThe orchestrator (`src/orchestrator.ts`) implements the Copilot Extensions **tool-calling pattern**   each capability is defined as a discrete tool with a name, description, typed parameters, and an async handler:\n\n```typescript\n// OrchestratorTool interface mirrors the Copilot Extensions tool schema\ninterface OrchestratorTool {\n  name: string;\n  description: string;\n  parameters: Record\u003cstring, ToolParameter\u003e;\n  handler: (params: Record\u003cstring, unknown\u003e) =\u003e Promise\u003cunknown\u003e;\n}\n```\n\nSeven tools are registered for the orchestration session:\n\n| Tool | Purpose |\n|------|---------|\n| `scanRepo` | Scan repository structure, languages, and dependencies |\n| `localSummarize` | Summarize a file using the local/cloud model |\n| `localAnalyzeArchitecture` | Generate architecture overview from key files |\n| `localGenerateTasks` | Create starter tasks for new contributors |\n| `localGenerateDiagram` | Generate a Mermaid component diagram |\n| `writeDoc` | Write a documentation file to the output directory |\n| `runCommand` | Execute a shell command in the repository context |\n\nThis mirrors how Copilot Extensions expose capabilities to the LLM   each tool is self-describing and independently invocable, enabling the agent to compose multi-step workflows.\n\n### Agent Skill Structure\n\nThe project ships as a set of **GitHub Copilot Agent Skills** in `.github/skills/`. Each skill follows the [Copilot custom instructions format](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) with YAML frontmatter and trigger phrases:\n\n```yaml\n---\nname: repo-onboarding-pack\ndescription: Generate comprehensive engineering onboarding documentation...\ncompatibility: Works with any Git repository...\n---\n```\n\nSkills are activated by natural-language trigger phrases (e.g., *\"Create onboarding pack for this repo\"*) and include quality gates, prompt templates, and validation checklists   so Copilot can autonomously generate and verify output.\n\n### Workflow Session\n\nThe 9-step generation pipeline runs as a **Copilot SDK-style session**   a stateful sequence of tool invocations with progress tracking, error recovery, and structured output:\n\n1. Check inference endpoint → 2. Scan repo → 3. Analyze files → 4. Architecture → 5. Tasks → 6. Diagram → 7. Compile → 8. Microsoft Learn validation → 9. Write files\n\nEach step reports progress via a callback (`ProgressCallback`), enabling real-time UI updates in both the CLI and web interface.\n\n### Copilot Instructions\n\nThe project includes `.github/copilot-instructions.md` which configures GitHub Copilot's behavior when working in this repository   linking to skills, defining workflows, and setting up the Microsoft Learn MCP integration.\n\n## CLI Usage\n\n### Foundry Local (Default)\n\n```bash\n# Basic usage   any GitHub URL or local path\nnpx onboard https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator\n\n# With options\nnpx onboard https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator \\\n  --output ./onboarding-docs \\\n  --model phi-4 \\\n  --verbose\n```\n\n### Cloud Usage\n\n```bash\n# Using Microsoft Foundry cloud models\nnpx onboard https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator \\\n  --cloud-endpoint https://your-project.services.ai.azure.com \\\n  --cloud-api-key YOUR_API_KEY \\\n  --cloud-model gpt-4o-mini \\\n  --verbose\n\n# Using environment variable for API key\nexport FOUNDRY_CLOUD_API_KEY=your-key-here\nnpx onboard https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator \\\n  --cloud-endpoint https://your-project.services.ai.azure.com \\\n  --cloud-model gpt-4o\n```\n\n### Copilot SDK Usage\n\n```bash\n# Use GitHub Copilot SDK (requires Copilot CLI: npm install -g @github/copilot)\nnpx onboard https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator --copilot-sdk\n\n# Specify a Copilot model\nnpx onboard https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator \\\n  --copilot-sdk --copilot-model gpt-4o\n```\n\n### Other Commands\n\n```bash\n# Check Foundry Local status\nnpx onboard --check-status\n\n# Skip AI entirely (use fallback generation)\nnpx onboard https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator --skip-local\n```\n\n## Web UI\n\nLaunch the graphical interface for a browser-based experience:\n\n```bash\n# Start the web server\nnpm run web\n\n# Or with custom port\nPORT=8080 npm run web\n```\n\nThen open [http://localhost:3000](http://localhost:3000) in your browser.\n\n### Keyboard Shortcuts\n\n| Key | Action |\n|-----|--------|\n| `R` | Refresh Foundry status |\n| `Esc` | Close preview modal |\n| `Ctrl+C` | Copy file content (in modal) |\n\n### Screenshots\n\n**Home   Foundry Local provider with model selection and live status:**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/web-ui-home.png\" alt=\"Web UI   Foundry Local selected with model dropdown and status panel\" width=\"700\"\u003e\n\u003c/p\u003e\n\n**Cloud provider   Microsoft Foundry with endpoint, model, and API key status:**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/web-ui-cloud.png\" alt=\"Web UI   Microsoft Foundry Cloud provider with gpt-5.2 status\" width=\"700\"\u003e\n\u003c/p\u003e\n\n**Form filled   ready to generate onboarding docs for a GitHub repository:**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/web-ui-form-filled.png\" alt=\"Web UI   form filled with Azure-Samples repo URL and model selected\" width=\"700\"\u003e\n\u003c/p\u003e\n\n**Step-by-step progress   real-time tracking of the 9-step generation pipeline:**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/web-ui-progress.png\" alt=\"Web UI   progress tracker showing steps 1-3 completed, step 4 running\" width=\"700\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/web-ui-progress-mid.png\" alt=\"Web UI   mid-progress with 6 steps completed\" width=\"700\"\u003e\n\u003c/p\u003e\n\n**Generation complete   all steps done with generated files listed for preview/download:**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/web-ui-complete.png\" alt=\"Web UI   all 9 steps completed with generated files\" width=\"700\"\u003e\n\u003c/p\u003e\n\n**Web UI Features:**\n- 🔌 Real-time Foundry Local connection status with model details\n- ☁️ Microsoft Foundry cloud support with provider toggle\n- 📂 Support for local paths and GitHub URLs\n- 🕒 Recent repositories dropdown (stored locally)\n- 📊 Step-by-step progress tracking with per-step details and cancel support\n- 👁️ Preview generated files with syntax highlighting\n- 📋 Copy to clipboard and download buttons\n- ⌨️ Keyboard shortcuts (Esc to close, R to refresh)\n- ♿ Full accessibility support (ARIA labels, focus management)\n- 🌙 Automatic dark mode support\n\n### Options\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `-o, --output \u003cdir\u003e` | Output directory | `./docs` in repo |\n| `-e, --endpoint \u003curl\u003e` | Foundry Local endpoint | Auto-detected |\n| `-m, --model \u003cname\u003e` | Local model to use | `phi-4` |\n| `-v, --verbose` | Show detailed progress | `false` |\n| `--skip-local` | Skip AI calls (use fallback) | `false` |\n| `--check-status` | Check Foundry status and exit | - |\n| `--cloud-endpoint \u003curl\u003e` | Microsoft Foundry endpoint URL | - |\n| `--cloud-api-key \u003ckey\u003e` | Cloud API key | `$FOUNDRY_CLOUD_API_KEY` |\n| `--cloud-model \u003cname\u003e` | Cloud model deployment name | `gpt-4o-mini` |\n| `--copilot-sdk` | Use GitHub Copilot SDK for inference | `false` |\n| `--copilot-model \u003cname\u003e` | Copilot SDK model name | `claude-sonnet-4` |\n\n## Demo \u0026 Benchmarking\n\nAll demo output lives in [`docs/demos/`](docs/demos/) and was generated from a single repository: [Azure-Samples/chat-with-your-data-solution-accelerator](https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator)   a popular RAG pattern accelerator with 1.2k+ stars, Python backend, TypeScript frontend, Bicep infrastructure, and 34+ contributors.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/sample-repo-github.png\" alt=\"Azure-Samples/chat-with-your-data-solution-accelerator on GitHub\" width=\"700\"\u003e\n\u003c/p\u003e\n\nWe ran the generator **four times** against this repository   once per provider/interface combination   to compare output quality, size, and content.\n\n### Generated Demo Folders\n\n| Folder | Interface | Provider | Model | Command |\n|--------|-----------|----------|-------|---------|\n| [`docscli-local/`](docs/demos/docscli-local/) | CLI | Foundry Local | qwen2.5-coder-1.5b | `npx tsx src/index.ts \u003curl\u003e --output docs/demos/docscli-local` |\n| [`docsweblocal/`](docs/demos/docsweblocal/) | Web UI | Foundry Local | qwen2.5-coder-1.5b | Web UI → Foundry Local provider |\n| [`docswebcloud/`](docs/demos/docswebcloud/) | Web UI | Microsoft Foundry | gpt-5.2 | Web UI → Cloud provider |\n| [`docswebgithub/`](docs/demos/docswebgithub/) | Web UI | GitHub Copilot SDK | Copilot model | Web UI → Copilot SDK provider |\n\n### Benchmark: Output Size by Provider\n\nFile sizes in **bytes**   larger LLM-generated files generally indicate richer, more detailed content.\n\n| File | CLI + Local | Web + Local | Web + Cloud (gpt-5.2) | Web + Copilot SDK |\n|------|------------:|------------:|----------------------:|------------------:|\n| ONBOARDING.md | 3,937 | 3,937 | **6,020** | **6,874** |\n| RUNBOOK.md | 2,358 | 2,358 | 2,358 | 2,358 |\n| TASKS.md | 8,158 | 8,158 | **10,078** | **9,714** |\n| AGENTS.md | 2,323 | 2,323 | 2,323 | 2,323 |\n| diagram.mmd | 285 | 285 | 733 | **1,393** |\n| VALIDATION.md | 2,549 | 2,549 | 2,549 | 2,549 |\n| **Total (bytes)** | **19,610** | **19,610** | **24,061** | **25,211** |\n\n#### What each file measures\n\n| File | What it tells you |\n|------|-------------------|\n| **ONBOARDING.md** | Architecture depth   how well the LLM understands the repo's structure, components, and key flows |\n| **RUNBOOK.md** | Build/run/test commands   deterministic (not LLM-generated), so identical across providers |\n| **TASKS.md** | Starter-task quality   repo-specific acceptance criteria, hints, and learning objectives |\n| **AGENTS.md** | Agent config   deterministic skills, MCP servers, and workflows extracted from repo metadata |\n| **diagram.mmd** | Diagram complexity   number of Mermaid nodes, subgraphs, and labeled edges |\n| **VALIDATION.md** | Microsoft Learn queries   deterministic, generated from detected Microsoft technologies |\n\n\u003e **Key insight:** AGENTS.md, RUNBOOK.md, and VALIDATION.md are identical across all providers   they are generated deterministically from repo metadata, not by the LLM. The LLM-generated files (ONBOARDING.md, TASKS.md, diagram.mmd) show the real quality differences. Cloud and Copilot SDK produce **23–29% more content** than the local 1.5B model.\n\n### Quality Review\n\n#### Architecture Recognition (ONBOARDING.md)\n\nEach provider identified the same repo differently:\n\n| Dimension | Foundry Local (1.5B) | Microsoft Foundry (gpt-5.2) | GitHub Copilot SDK |\n|-----------|---------------------|---------------------------|-------------------|\n| **Pattern detected** | \"Monolithic\" | \"Monorepo\" | \"Serverless\" |\n| **Component count** | 5 (generic names) | 10 (directory-mapped table) | 14 (directory-mapped table with purpose) |\n| **Key interactions** | 3 bullet points, generic | 3 numbered items with exact file paths | Detailed multi-tier description with orchestration strategies |\n| **Architecture depth** | High-level only | Component table with subgraphs | Full multi-tier breakdown: UI layer, processing layer, infra, data |\n\n**Verbatim   Foundry Local** classified the architecture as:\n\u003e *\"The project is structured as a monolithic application, where all components are tightly coupled and reside in a single codebase.\"*\n\n**Verbatim   Microsoft Foundry** identified it as a monorepo:\n\u003e *\"This project is a single repository that contains multiple deployable parts: a Python backend (including an Azure Functions batch/ingestion workload and an admin UI), a separate TypeScript/Vite frontend web app, and an optional Microsoft Teams extension.\"*\n\n**Verbatim   GitHub Copilot SDK** went deepest:\n\u003e *\"This is an Azure-native RAG (Retrieval Augmented Generation) solution accelerator using a serverless architecture. The system enables conversational search over user documents by combining Azure OpenAI for LLM capabilities with Azure AI Search for vector retrieval.\"*\n\n#### Component Diagram Quality (diagram.mmd)\n\n| Provider | Nodes | Subgraphs | Edge Labels | Size |\n|----------|------:|----------:|:-----------:|-----:|\n| Foundry Local | 10 | 0 | No | 285 B |\n| Microsoft Foundry | 12 | 3 | No | 733 B |\n| GitHub Copilot SDK | 14 | 5 | Yes | 1,393 B |\n\n**Verbatim   Foundry Local** produced a flat graph with raw directory/language names:\n```mermaid\ngraph TD\n    code --\u003e data\n    code --\u003e scripts\n    Python --\u003e tests\n    TypeScript --\u003e tests\n    Bicep --\u003e tests\n```\n\n**Verbatim   Microsoft Foundry** added meaningful subgraphs:\n```mermaid\ngraph TD\n  subgraph DevelopmentEnvironment[Development Environment]\n    DevContainerDir --\u003e DockerDir\n    DevContainerDir --\u003e ExtensionsDir\n  end\n  subgraph ApplicationAndData[Application \u0026 Data]\n    CodeDir --\u003e DataDir\n    TestsDir --\u003e CodeDir\n  end\n```\n\n**Verbatim   GitHub Copilot SDK** produced the richest diagram with labeled edges and component-level detail:\n```mermaid\ngraph TD\n    subgraph UserInterface[\"User Interface Layer\"]\n        Frontend[\"code/frontend\u003cbr/\u003eReact Chat UI\"]\n        Admin[\"code/backend\u003cbr/\u003eStreamlit Admin\"]\n        Teams[\"extensions/teams\u003cbr/\u003eTeams Bot\"]\n    end\n    Frontend --\u003e|API Calls| Flask\n    Admin --\u003e|Ingestion| Batch\n    Teams --\u003e|Bot Framework| Flask\n```\n\n#### Starter Task Quality (TASKS.md)\n\nEvery provider generated 10 tasks with learning objectives. The depth difference is dramatic:\n\n**Verbatim   Foundry Local** tasks are generic templates:\n\u003e 🟡 **Task 1: Review Code Structure** \\\n\u003e *Learning: Understand file organization and directory structure* \\\n\u003e Criteria: \"Know the location of the `api`, `database`, and `orchestrator` directories\"\n\nNote: The local model also produced **parsing artifacts**   field labels bled into content (e.g., `Skills: File navigation` appearing inside related-files lists).\n\n**Verbatim   Microsoft Foundry** tasks reference exact files and real workflows:\n\u003e 🟢 **Task 1: Trace the Chat Request Path (Frontend → Backend)** \\\n\u003e *Learning: Code navigation in a monorepo; understanding API boundaries between TypeScript frontend and Python backend* \\\n\u003e Criteria: \"Identifies the exact frontend function(s) that issue the chat request\" \\\n\u003e Hints: \"Search for the chat endpoint path in `code/frontend/src/api/*`\"\n\n**Verbatim   GitHub Copilot SDK** tasks tie to real engineering concepts:\n\u003e 🟢 **Task 1: Explore the RAG Architecture Documentation** \\\n\u003e *Learning: Understanding RAG (Retrieval Augmented Generation) patterns and Azure service integration* \\\n\u003e Criteria: \"Can explain the role of Azure OpenAI and Azure AI Search\" \\\n\u003e Related files: `README.md`, `docs/integrated_vectorization.md`, `docs/conversation_flow_options.md`\n\n#### Task Difficulty Distribution\n\n| Difficulty | Foundry Local | Microsoft Foundry | GitHub Copilot SDK |\n|------------|:------------:|:----------------:|:------------------:|\n| 🟢 Easy | 5 | 3 | 3 |\n| 🟡 Medium | 3 | 4 | 4 |\n| 🔴 Hard | 2 | 3 | 3 |\n\nCloud and Copilot providers produced a more balanced difficulty curve with harder tasks that involve real cross-component work (e.g., \"Refactor Backend App Initialization for Clearer Dependency Injection\", \"Extend Infrastructure with New Bicep Module\").\n\n#### Summary Scorecard\n\n| Dimension | Foundry Local (1.5B) | Microsoft Foundry (gpt-5.2) | GitHub Copilot SDK |\n|-----------|:-------------------:|:-------------------------:|:-----------------:|\n| Architecture accuracy | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |\n| Task specificity | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |\n| Learning objectives | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |\n| Diagram quality | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |\n| Parsing cleanliness | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |\n| Privacy | ✅ On-device | ❌ Cloud | ❌ Cloud |\n| Cost | Free | Pay-per-token | Copilot subscription |\n| GPU required | Yes (local) | No | No |\n\n### Which Provider Should You Use?\n\n| Use Case | Recommended Provider |\n|----------|---------------------|\n| Proprietary code, air-gapped environments | **Foundry Local**   no data leaves your machine |\n| Best output quality, team documentation | **Microsoft Foundry** or **GitHub Copilot SDK** |\n| Students with Copilot access, no API keys | **GitHub Copilot SDK** |\n| Quick drafts to refine manually | **Foundry Local** (fastest setup, zero cost) |\n| Classroom with mixed setups | Start with **Foundry Local**, upgrade output with cloud if allowed |\n\n### Sample CLI Output\n\n```\n🚀 Repo Onboarding Pack Generator v1.0.0\n\n📥 Cloning: https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator\n   Using cached clone...\n\n[1/9] Checking LLM provider...\n✓ Foundry Local available at http://127.0.0.1:65503\n  Active model: qwen2.5-coder-1.5b-instruct-cuda-gpu:4\n\n[2/9] Scanning repository...\n✓ Found 6 languages   Primary: Python\n\n[3/9] Analyzing key files...\n  Summarized: README.md, package.json, Makefile, pyproject.toml\n\n[4/9] Generating architecture overview...\n[5/9] Generating starter tasks...\n[6/9] Generating component diagram...\n[7/9] Compiling onboarding pack...\n[8/9] Validating Microsoft technologies...\n  Found: TypeScript, Bicep\n[9/9] Writing output files...\n\n✓ Onboarding pack generated successfully!\n📦 Generated: ONBOARDING.md, RUNBOOK.md, TASKS.md, AGENTS.md, diagram.mmd, VALIDATION.md\n```\n\n## Agent Skill\n\nThis project includes reusable agent skills at `.github/skills/`.\n\n### Available Skills\n\n| Skill | Purpose |\n|-------|---------|\n| [`repo-onboarding-pack`](.github/skills/repo-onboarding-pack/SKILL.md) | Generate onboarding documentation for repositories || [`repo-agents-pack`](.github/skills/repo-agents-pack/SKILL.md) | Generate AGENTS.md with skills, MCP servers, and workflows || [`microsoft-skill-creator`](.github/skills/microsoft-skill-creator/SKILL.md) | Create new agent skills for Microsoft technologies |\n| [`microsoft-docs`](.github/skills/microsoft-docs/SKILL.md) | Query Microsoft documentation for concepts \u0026 tutorials |\n| [`microsoft-code-reference`](.github/skills/microsoft-code-reference/SKILL.md) | API lookups, code samples, error troubleshooting |\n\n### Installing the Skills\n\n1. Copy all skills to your target repo:\n   ```bash\n   cp -r .github/skills/* /path/to/repo/.github/skills/\n   ```\n\n2. The `repo-onboarding-pack` skill triggers on phrases like:\n   - \"Create onboarding pack for this repo\"\n   - \"Generate runbook for the project\"\n   - \"New engineer onboarding docs\"\n   - \"Help me understand this repo quickly\"\n\n### Skill Structure\n\n```\n.github/skills/\n├── repo-onboarding-pack/\n│   ├── SKILL.md                    # Main onboarding skill\n│   └── references/\n│       ├── checklist.md            # Quality verification\n│       ├── mermaid-patterns.md     # Diagram templates\n│       └── microsoft-tech-verification.md\n├── repo-agents-pack/\n│   └── SKILL.md                    # AGENTS.md generation skill\n├── microsoft-skill-creator/\n│   ├── SKILL.md                    # Create skills for Microsoft tech\n│   └── references/\n│       └── skill-templates.md      # SDK, Azure, Framework, API templates\n├── microsoft-docs/\n│   └── SKILL.md                    # Microsoft documentation queries\n└── microsoft-code-reference/\n    └── SKILL.md                    # API/SDK verification\n```\n\n## Using with VS Code GitHub Copilot Chat\n\nThis project ships with **agent skills** and **MCP server configuration** that work directly inside [GitHub Copilot Chat](https://docs.github.com/en/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide) in VS Code. No CLI or web UI needed   just open the repo and start chatting.\n\n### Setup (One-Time)\n\n1. **Open this repo in VS Code**\n   ```\n   code learnskill-agent-foundrylocal\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Enable Agent Mode**   In Copilot Chat, click the mode dropdown (top of chat panel) and select **Agent**. This lets Copilot use the skills, MCP tools, and terminal commands defined in this project.\n\n4. **MCP server auto-configures**   The `.mcp.json` file at the project root registers the Microsoft Learn MCP server automatically. VS Code picks this up when you open the workspace. You should see `microsoft-learn` listed when you click the **Tools** icon (🔧) in the chat panel.\n\n### Talking to the Agent Skills\n\nOnce in Agent Mode, type natural-language prompts in Copilot Chat. The skills in `.github/skills/` are loaded via `.github/copilot-instructions.md` and activate based on your request:\n\n#### Generate Onboarding Docs\n\n```\nCreate onboarding pack for this repo\n```\n```\nGenerate runbook for the project\n```\n```\nHelp me understand this repo quickly\n```\n```\nCreate architecture documentation\n```\n```\nGenerate starter tasks for new contributors\n```\n\nCopilot will analyze the repo structure, call the LLM, and produce ONBOARDING.md, RUNBOOK.md, TASKS.md, AGENTS.md, diagram.mmd, and VALIDATION.md.\n\n#### Generate Agent Configuration\n\n```\nGenerate AGENTS.md for this project\n```\n```\nConfigure Copilot skills for this repo\n```\n```\nWhat MCP servers should this repo use?\n```\n\n#### Query Microsoft Documentation\n\n```\nSearch Microsoft Learn for Azure Functions Python v2 triggers\n```\n```\nFind the quickstart for Azure AI Search\n```\n```\nWhat are the limits for Cosmos DB?\n```\n\nThese queries use the `microsoft_docs_search` and `microsoft_docs_fetch` tools from the Microsoft Learn MCP server.\n\n#### Look Up API References \u0026 Code Samples\n\n```\nFind a code sample for uploading blobs with managed identity in Python\n```\n```\nWhat's the correct signature for BlobClient.UploadAsync?\n```\n```\nShow me how to use Semantic Kernel in C#\n```\n\n#### Create New Skills for Microsoft Technologies\n\n```\nCreate a skill for Azure Container Apps\n```\n```\nBuild an agent skill that teaches about Bicep\n```\n\n### What Happens Behind the Scenes\n\nWhen you type a prompt in Copilot Chat (Agent Mode):\n\n1. **Copilot reads** `.github/copilot-instructions.md`   this tells it about the project, available skills, and MCP tools\n2. **Skills activate** based on your prompt   each skill in `.github/skills/` has trigger phrases and step-by-step instructions Copilot follows\n3. **MCP tools fire** when Copilot needs external data   e.g., `microsoft_docs_search` queries learn.microsoft.com in real-time\n4. **Copilot uses the terminal** to run commands like `npx tsx src/index.ts` or `npm run build` when the skill requires it\n5. **Files are created/edited** directly in your workspace   you can review changes in the source control panel\n\n### Tips\n\n- **Be specific**   \"Create onboarding pack for `https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator`\" works better than \"make docs\"\n- **Check the Tools icon** (🔧) in Chat to verify `microsoft-learn` MCP server is connected\n- **Use Agent Mode**, not Ask or Edit mode   skills and MCP tools only work in Agent Mode\n- **Review generated files** before committing   AI output should always be verified\n- **Combine skills**   ask Copilot to generate an onboarding pack and then validate it against Microsoft Learn in the same conversation\n\n## Microsoft Learn MCP Server\n\nThis project integrates with the [Microsoft Learn MCP Server](https://github.com/MicrosoftDocs/mcp) for verifying Microsoft technology details.\n\n### Quick Setup\n\n**VS Code (one-click):**\n\n[![Install in VS Code](https://img.shields.io/badge/Install_Microsoft_Learn_MCP-0098FF?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://vscode.dev/redirect/mcp/install?name=microsoft-learn\u0026config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Flearn.microsoft.com%2Fapi%2Fmcp%22%7D)\n\n**Manual Configuration (`.mcp.json`):**\n\nThis project includes a `.mcp.json` file that auto-configures the MCP server:\n\n```json\n{\n  \"mcpServers\": {\n    \"microsoft-learn\": {\n      \"type\": \"http\",\n      \"url\": \"https://learn.microsoft.com/api/mcp\"\n    }\n  }\n}\n```\n\n### MCP Tools Available\n\n| Tool | Use For |\n|------|---------|\n| `microsoft_docs_search` | Search official documentation |\n| `microsoft_docs_fetch` | Get full page content |\n| `microsoft_code_sample_search` | Find code examples |\n\n### Example Usage\n\n```\n# Search for Azure Functions documentation\nmicrosoft_docs_search(query=\"azure functions triggers bindings\")\n\n# Get full tutorial content\nmicrosoft_docs_fetch(url=\"https://learn.microsoft.com/azure/azure-functions/...\")\n\n# Find code samples in specific language\nmicrosoft_code_sample_search(query=\"semantic kernel\", language=\"csharp\")\n```\n\nSee [microsoft-tech-verification.md](.github/skills/repo-onboarding-pack/references/microsoft-tech-verification.md) for detailed guidance.\n\n## Development\n\n### Prerequisites\n\n- Node.js 20+\n- **Foundry Local** (for local inference), **Microsoft Foundry** (for cloud), or **GitHub Copilot CLI** (for SDK mode)\n\n### Setup\n\nUse the automated setup script to verify prerequisites, install dependencies, and configure your environment:\n\n```bash\n# Windows (PowerShell)\n.\\setup.ps1\n\n# Linux / macOS\nchmod +x setup.sh \u0026\u0026 ./setup.sh\n\n# Or via npm (auto-detects OS)\nnpm run setup\n```\n\nThe setup script checks Node.js 20+, Git, installs npm packages, verifies TypeScript compilation, creates `.env` from `.env.example`, checks Foundry Local status, and validates cloud configuration.\n\nAlternatively, set up manually:\n\n```bash\n# Clone\ngit clone \u003crepo-url\u003e\ncd repo-onboarding-pack\n\n# Install\nnpm install\n\n# Build\nnpm run build\n\n# Run in dev mode\nnpm run dev -- --help\n```\n\n### Starting Foundry Local\n\n```bash\n# Install Foundry Local\nwinget install Microsoft.FoundryLocal\n\n# Start the server\nfoundry service start\n\n# Check status (shows dynamic port)\nfoundry service status\n\n# Verify API (port is auto-discovered)\ncurl http://127.0.0.1:\u003cport\u003e/v1/models\n```\n\n\u003e **Note:** Foundry Local uses dynamic ports. This tool auto-discovers the port via `foundry service status`. Model aliases (e.g., `phi-4`) are automatically resolved to full model IDs (e.g., `Phi-4-cuda-gpu:1`).\n\n### Setting Up Microsoft Foundry (Cloud)\n\n1. Go to [ai.azure.com](https://ai.azure.com/) and create a project\n2. Deploy a model (e.g., `gpt-4o-mini`, `Phi-4`, `DeepSeek-R1`)\n3. Copy the **endpoint URL** and **API key** from the deployment page\n4. Use them with the `--cloud-endpoint` and `--cloud-api-key` flags:\n\n```bash\nnpx onboard https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator \\\n  --cloud-endpoint https://your-project.services.ai.azure.com \\\n  --cloud-api-key YOUR_KEY \\\n  --cloud-model gpt-4o-mini\n```\n\nAlternatively, set the API key as an environment variable:\n\n```bash\n# Windows\nset FOUNDRY_CLOUD_API_KEY=your-key-here\n\n# Linux/macOS\nexport FOUNDRY_CLOUD_API_KEY=your-key-here\n```\n\n### Project Structure\n\n```\nsrc/\n├── index.ts             # CLI entry point\n├── server.ts            # Web UI server\n├── orchestrator.ts      # Workflow coordination\n├── localModelClient.ts  # Foundry Local / Azure OpenAI client\n├── copilotSdkClient.ts  # GitHub Copilot SDK client\n├── repoScanner.ts       # Repository analysis\n├── validation.ts        # Security input validation\n└── types.ts             # TypeScript interfaces\n```\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# .env\n\n# Foundry Local settings\nFOUNDRY_LOCAL_ENDPOINT=http://localhost:5273\nFOUNDRY_LOCAL_MODEL=phi-4\nOUTPUT_DIR=./docs\n\n# Microsoft Foundry cloud settings\nFOUNDRY_CLOUD_ENDPOINT=https://your-resource.cognitiveservices.azure.com/openai/deployments/\nFOUNDRY_CLOUD_API_KEY=your-api-key-here\nFOUNDRY_CLOUD_MODEL=gpt-4o-mini\n\n# GitHub Copilot SDK settings\nGITHUB_TOKEN=your-github-token-here  # or GH_TOKEN\nCOPILOT_MODEL=claude-sonnet-4\n```\n\n### Copilot Instructions\n\nAdd to `.github/copilot-instructions.md`:\n\n```markdown\n## Onboarding Documentation\n\nWhen asked to create onboarding documentation:\n1. Use the repo-onboarding-pack skill\n2. Verify Microsoft tech details via Learn MCP tools\n3. Follow the quality checklist before completing\n```\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nCheck [TASKS.md](docs/demos/docswebcloud/TASKS.md) for example starter tasks generated by the tool.\n\n## Security\n\nPlease report security vulnerabilities according to our [Security Policy](SECURITY.md).\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleestott%2Flearnskill-agent-foundrylocal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleestott%2Flearnskill-agent-foundrylocal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleestott%2Flearnskill-agent-foundrylocal/lists"}