Restructure AI development assets for cross-tool support and improved agent performance

[jeremydhoover-blip]

Summary

This PR restructures the AI development assets in the .ai/ folder to follow industry-standard skill packaging patterns, support multiple AI development tools, and significantly improve agent performance through deduplication and on-demand content loading.

Motivation

The existing AI asset structure had several issues that reduced agent effectiveness:

• Duplication: Architecture rules, component patterns, and OneLake patterns were repeated across multiple files, consuming context window tokens with redundant content
• Verbose, AI-unfriendly content: Prose-heavy descriptions, nested "Key Features" bullet lists, and AI-meta phrasing made instructions harder for agents to parse efficiently
• Aspirational content: ~2,755 lines of placeholder commands (fabric deploy staging, fabric.cert.security, etc.) that referenced features that do not exist in the repository
• Monolithic loading: Context files (~8,958 tokens) were configured as default context for every session, with no mechanism to load content on demand based on the task
• Single-tool support: Only GitHub Copilot was supported; no configuration for Claude Code or Cursor users

What changed

New structure: platform-agnostic skills

Reorganized .ai/ into a skills-based structure following the Claude Code SKILL.md pattern and Agent Skills open standard:

.ai/
├── references/ # Shared knowledge (loaded on demand)
│ ├── fabric-platform.md
│ └── markdown-formatting.md
└── skills/
├── fabric-items/ # Item development skill
│ ├── SKILL.md # Entry point with architecture rules
│ ├── examples.md # Code templates for all item files
│ └── references/ # Detailed component APIs and procedures
└── fabric-workloads/ # Workload lifecycle skill
├── SKILL.md # Entry point with run/deploy/publish/update/clean
├── examples.md # Config and deployment examples
└── references/ # Detailed procedures

Multi-tool entry points

• CLAUDE.md (new): Claude Code project entry point with @ imports to shared references
• AGENTS.md (new): Cursor project entry point (self-contained since Cursor cannot import)
• .github/copilot-instructions.md (updated): References new skill paths
• .github/copilot/ (updated): Agent configuration files updated with new paths and corrected file patterns

Content improvements

• Rewrote all AI instruction content following Microsoft Style Guide principles: active voice, concise language, direct action-oriented prose. Removed verbose AI-meta phrasing (e.g., "This guide provides step-by-step instructions for AI tools to safely delete an item from the Microsoft Fabric Extensibility Toolkit") in favor of direct procedural language that agents can parse efficiently
• Eliminated ~1,000 lines of duplicated architecture rules, component patterns, and styling constraints that appeared across 2-4 files. Each pattern now exists in a single canonical location, reducing ambiguity when agents encounter conflicting or repeated instructions
• Removed ~2,755 lines of aspirational instruction content that referenced non-existent commands (e.g., fabric deploy staging, fabric.cert.security). Verified: zero matches for any of these commands exist in the codebase. This content consumed context tokens without providing actionable guidance
• Applied title case headings consistently across all .ai/ files for predictable document structure and navigation
• Removed emojis from all AI instruction files to improve parseability and reduce token waste on non-semantic characters
• Replaced nested "Key Features" bullet lists and repetitive summary sections with concise inline descriptions, reducing prose overhead while preserving all technical information
• Corrected file path references throughout (config/Manifest/ did not exist in the repository; updated to Workload/Manifest/)
• Expanded the README AI Assistance section to document all three supported tools with setup instructions

Files deleted

• .ai/commands/ (8 files) -- content migrated to skill SKILL.md files and references
• .ai/context/ (3 files) -- content split into skill-specific references and shared references
• .github/instructions/ (5 files) -- replaced by platform-agnostic skills

Verification

Test	Result
Content coverage (key concepts from originals found in new structure)	33/33 (100%)
Internal link integrity (markdown links resolve to real files)	36/36 (100%)
Old path references remaining (.ai/commands/, .ai/context/)	0 matches
Emoji characters in .ai/ and .github/ files	0 matches
Procedure steps preserved (create, delete, rename, run, deploy, publish, clean)	All steps verified against originals

Performance impact

Metric	Before	After	Change
Content duplication	Patterns repeated across 2-4 files	Single canonical location per pattern	Eliminated
Content quality	Verbose prose, AI-meta phrasing, emojis	Concise, action-oriented, Microsoft Style Guide	Rewritten
Aspirational/placeholder content	~2,755 lines	0 lines	Eliminated
Default-loaded context	~8,958 tokens	~3,142 tokens	-65%
AI tools supported	1 (Copilot)	3 (Copilot, Claude Code, Cursor)	+2 tools

The new structure loads lean SKILL.md entry points (~3,142 tokens) initially and pulls specific references, examples, and procedures on demand based on the task. This means the agent has more context budget available for actual code and conversation.

No content was removed

Every procedure step, component API, code template, troubleshooting guide, and verification checklist from the original files exists in the new structure. Content was reorganized and deduplicated, not deleted. The only content removed was:

• Duplicated definitions (now exist once in a canonical location)
• Aspirational commands that do not exist in the repository
• AI-meta "Best Practices for AI Tools" sections that instructed AI about itself

[jeremydhoover-blip]

@gsaurer Could you review this PR? It restructures the .ai/ assets to follow industry-standard skill packaging patterns, improves agent performance through deduplication and on-demand loading, and adds support for Claude Code and Cursor alongside GitHub Copilot.