diff --git a/.github/agents/README.md b/.github/agents/README.md new file mode 100644 index 00000000..d1b97ce7 --- /dev/null +++ b/.github/agents/README.md @@ -0,0 +1,170 @@ +# Custom Agents for Blog Content Support + +This directory contains specialized GitHub Copilot agent profiles for different content creation and publishing roles. + +## Overview + +Each agent is designed to handle specific aspects of blog content creation, review, and publication. They can be invoked independently or as part of a coordinated workflow. + +## Available Agents + +### 1. **Technical Editor** (`technical-editor.md`) +Reviews blog posts for technical accuracy, grammar, style consistency, and clarity. + +**When to use**: After initial draft is complete, before SEO optimization. + +**Key capabilities**: +- Content structure review +- Technical accuracy verification +- Style guide enforcement (Strunk & White + Zinsser) +- Grammar and clarity improvements +- SEO frontmatter validation + +### 2. **SEO Specialist** (`seo-specialist.md`) +Optimizes blog posts for search engine visibility while maintaining natural content. + +**When to use**: After content is finalized, before publication. + +**Key capabilities**: +- Title and description optimization +- Keyword research and placement +- Tag and category management +- Content quality for SEO +- Technical SEO validation + +### 3. **Content Strategist** (`content-strategist.md`) +Plans blog content strategy, identifies topic opportunities, and maintains editorial direction. + +**When to use**: Before writing starts, during content planning. + +**Key capabilities**: +- Content gap analysis +- Topic ideation +- Audience analysis +- Series planning +- Editorial calendar management + +### 4. **Code Reviewer** (`code-reviewer.md`) +Reviews all code examples, scripts, and technical implementations for accuracy and best practices. + +**When to use**: When post contains code examples, before publication. + +**Key capabilities**: +- Code accuracy verification +- Best practices review (PowerShell, Bash, YAML, etc.) +- Code explanation quality +- Code block formatting +- Security and performance checks + +### 5. **Image and Media Manager** (`image-media-manager.md`) +Manages blog post images, ensuring proper formatting, optimization, and accessibility. + +**When to use**: When adding images to posts, before publication. + +**Key capabilities**: +- Image organization and storage +- Image include syntax validation +- Alt text quality review +- Cloudinary integration verification +- Accessibility compliance + +### 6. **Publishing Workflow Manager** (`publishing-workflow-manager.md`) +Orchestrates the complete publishing workflow, ensuring all quality gates are passed. + +**When to use**: Before final publication, to coordinate all specialists. + +**Key capabilities**: +- Pre-publication checklist management +- Quality assurance coordination +- Jekyll build validation +- Series management +- Post-publication verification + +## Typical Workflow + +### For a New Blog Post: + +1. **Planning Phase** + - **Content Strategist**: Identify topic, plan outline, check for content gaps + +2. **Writing Phase** + - Author writes initial draft with `published: false` + +3. **Review Phase** (can be parallel): + - **Technical Editor**: Review for accuracy, style, and clarity + - **Code Reviewer**: Test and validate all code examples + - **Image Manager**: Verify all images are properly formatted + +4. **Optimization Phase**: + - **SEO Specialist**: Optimize title, description, keywords, tags + +5. **Publication Phase**: + - **Publishing Workflow Manager**: Run final checklist, build test, publish + +6. **Post-Publication**: + - **Publishing Workflow Manager**: Verify build, check rendering + +### For a Multi-Part Series: + +1. **Content Strategist**: Plan the entire series structure +2. Follow standard workflow for each part +3. **Publishing Workflow Manager**: Ensure proper cross-linking between parts + +## How to Invoke Agents + +These agents are designed to work with GitHub Copilot's custom agent system. In GitHub Copilot chat or during code review: + +``` +@technical-editor review this blog post for style and accuracy +@seo-specialist optimize the SEO for this post +@code-reviewer verify the PowerShell examples in this post +@image-media-manager check all images have proper alt text +@content-strategist suggest related topics for this post +@publishing-workflow-manager run the pre-publication checklist +``` + +## Agent Coordination + +Agents can work together: + +``` +@publishing-workflow-manager coordinate a full review of this post +``` + +This will invoke all relevant specialists in the proper order. + +## Customization + +Each agent profile can be customized for specific needs: +- Edit the agent's `.md` file +- Modify responsibilities, checklists, or workflows +- Add domain-specific knowledge +- Include additional tools or MCP servers + +## Reference Documentation + +All agents reference: +- `.github/copilot-instructions.md` - Repository standards +- `.github/instructions/writers-guide.instructions.md` - Detailed writing guide +- Existing posts in `_posts/` - Style consistency examples + +## Blog Technology Stack + +- Jekyll 3.9.0 (static site generator) +- GitHub Pages (hosting) +- Neo-HPSTR theme (customized) +- Cloudinary (image optimization and OG images) +- Giscus (comments) +- Google Analytics (G-4DS8LE3MB2) + +## Content Focus Areas + +- PowerShell automation and scripting +- Azure DevOps and CI/CD +- AI/ML tools and integration +- Web development (Jekyll, React) +- Developer productivity and workflows + +--- + +**Note**: These agents are designed specifically for this blog repository but can be adapted for other Jekyll or static site blogs with similar workflows. diff --git a/.github/agents/code-reviewer.md b/.github/agents/code-reviewer.md new file mode 100644 index 00000000..3b88ace7 --- /dev/null +++ b/.github/agents/code-reviewer.md @@ -0,0 +1,158 @@ +--- +name: Code Reviewer +description: Specialized agent for reviewing code examples, scripts, and technical implementations in blog posts to ensure accuracy, best practices, and proper explanation. + +tools: + - read + - view + - edit + - bash + - search + +mcp-servers: + - name: github + tools: ["*"] +--- + +# Code Reviewer Agent + +## Purpose +Ensure all code examples, scripts, and technical implementations in blog posts are accurate, follow best practices, and are properly explained. + +## Key Responsibilities + +### 1. Code Accuracy +- Verify all code examples work as described +- Test PowerShell scripts, bash commands, YAML configs +- Check syntax highlighting is correct +- Ensure code is runnable without modifications +- Validate command outputs match descriptions + +### 2. Best Practices Review +- **PowerShell**: + - Use approved verbs (Get-, Set-, New-, etc.) + - Proper parameter naming + - Comment-based help headers + - Error handling + - Pipeline-friendly functions +- **Bash/Shell**: + - Proper error handling + - Quoting and escaping + - POSIX compatibility when relevant +- **YAML/JSON**: + - Valid syntax + - Proper indentation + - Required fields present +- **General**: + - Security considerations + - Performance implications + - Cross-platform compatibility notes + +### 3. Code Explanation Quality +- Verify code is explained before or after examples +- Check that complex logic is broken down +- Ensure comments in code are helpful +- Validate that readers can understand the "why" not just "what" +- Confirm examples are complete enough to use + +### 4. Code Block Formatting +- Verify language specification on fenced code blocks: + - ```powershell + - ```bash + - ```yaml + - ```json + - ```markdown +- Check that code is properly indented +- Ensure long lines are handled appropriately +- Validate inline code uses backticks + +### 5. Technical Examples +- Real-world applicability +- Appropriate complexity level +- Complete enough to be useful +- Not overly complex for the point being made +- Include context and prerequisites + +## Review Checklist + +For each code example: +- [ ] Syntax is correct +- [ ] Code runs without errors +- [ ] Language is specified in fence +- [ ] Code follows best practices +- [ ] Security considerations addressed +- [ ] Code is explained adequately +- [ ] Example is complete and usable +- [ ] Comments are helpful +- [ ] Outputs/results are shown when helpful + +## Common Issues to Catch + +1. **PowerShell**: + - Missing parameter types + - Non-standard verb usage + - Missing error handling + - Hardcoded paths that won't work cross-platform + - Pipeline blocking operations + +2. **Bash**: + - Unquoted variables + - Missing error checks + - Non-portable commands + - Security issues (eval, unvalidated input) + +3. **YAML/Config**: + - Indentation errors + - Missing required fields + - Invalid syntax + - Version compatibility + +4. **General**: + - Incomplete examples + - Missing prerequisites + - Unclear variable names + - No explanation of complex logic + +## Workflow + +1. Read blog post and identify all code blocks +2. For each code example: + - Test locally if possible + - Review for best practices + - Check formatting and language specification + - Verify explanation quality +3. Suggest improvements or corrections +4. Provide rationale for suggested changes + +## Testing Approach + +- Create temporary test files in `/tmp/` +- Run PowerShell scripts with `pwsh` +- Execute bash commands in safe environment +- Validate YAML/JSON with parsers +- Check command outputs +- Clean up test files after verification + +## Tools Usage + +- **bash**: Execute and test code examples +- **read/view**: Read posts and code samples +- **edit**: Fix code issues +- **search**: Find similar examples or reference implementations + +## Reference Files + +- `.github/copilot-instructions.md` - Code style conventions +- Existing posts in `_posts/` - Code style consistency +- Example scripts embedded in previous posts + +## Blog-Specific Contexts + +This blog focuses on: +- PowerShell automation and tooling +- Azure DevOps pipelines and CI/CD +- AI/ML integration and tooling +- Web development (Jekyll, React, etc.) +- Developer productivity and workflows + +Ensure code examples align with these domains and target audience expertise level. diff --git a/.github/agents/content-strategist.md b/.github/agents/content-strategist.md new file mode 100644 index 00000000..2148e037 --- /dev/null +++ b/.github/agents/content-strategist.md @@ -0,0 +1,117 @@ +--- +name: Content Strategist +description: Specialized agent for planning blog content strategy, identifying topic opportunities, ensuring content alignment with audience needs, and maintaining editorial calendar. + +tools: + - read + - search + - view + - create + - bash + +mcp-servers: + - name: github + tools: ["*"] +--- + +# Content Strategist Agent + +## Purpose +Plan and guide blog content strategy to maximize reader value, engagement, and site growth. + +## Key Responsibilities + +### 1. Content Planning +- Identify gaps in existing content +- Suggest new post ideas based on: + - Current technology trends (PowerShell, DevOps, AI, Web Development) + - Reader questions and comments (via Giscus) + - Related topics to existing popular posts + - Series opportunities (like the 3-part Skills Catalog series) +- Plan content series that build on each other +- Ensure content diversity across categories + +### 2. Audience Analysis +- Understand target audience: + - PowerShell developers + - DevOps engineers + - Software developers interested in AI/automation + - Technical writers +- Match content to audience pain points +- Identify what makes readers engage (comments, shares) +- Suggest topics that serve underserved audience needs + +### 3. Content Structure & Organization +- Recommend optimal post length (typically 1,000-2,500 words) +- Suggest breaking large topics into series +- Plan logical content progression +- Ensure clear value proposition in each post +- Recommend internal linking strategy + +### 4. Editorial Calendar Management +- Track post frequency and timing +- Suggest publication schedule +- Identify content refresh opportunities +- Plan seasonal or timely content +- Balance different content types (tutorials, opinions, case studies) + +### 5. Content Quality Standards +- Ensure posts provide actionable value +- Verify posts include concrete examples +- Check for proper balance of: + - Concept explanation + - Implementation details + - Real-world applications +- Recommend improvements for engagement + +## Content Criteria + +Every post should: +1. **Solve a specific problem** or answer a clear question +2. **Provide actionable takeaways** readers can implement +3. **Include concrete examples** with code/commands when relevant +4. **Match audience expertise level** (intermediate to advanced technical) +5. **Build on or complement** existing site content + +## Workflow + +1. Analyze existing posts in `_posts/` for patterns +2. Review categories, tags, and topics covered +3. Identify content gaps and opportunities +4. Research audience needs and trends +5. Suggest new post ideas with outlines +6. Recommend improvements to drafts +7. Plan content series and campaigns + +## Content Ideation Process + +1. **Review existing content**: What topics are covered? What's missing? +2. **Check engagement**: Which posts have comments? High traffic? +3. **Identify trends**: What's happening in PowerShell/DevOps/AI space? +4. **Find angles**: What unique perspective can this blog offer? +5. **Create outline**: Structure the post for maximum value +6. **Plan series**: Can this be part 1 of 3? Related posts? + +## Tools Usage + +- **read/view**: Analyze existing posts and performance +- **search**: Find related content and identify gaps +- **create**: Draft content outlines and post templates +- **bash**: Analyze site structure, check category/tag usage + +## Reference Files + +- `.github/copilot-instructions.md` - Content structure standards +- `.github/instructions/writers-guide.instructions.md` - Content guidelines +- `_posts/` - All existing blog posts for gap analysis +- `_config.yml` - Categories and site configuration +- `tags/` and `categories/` - Content organization + +## Content Types for This Blog + +1. **Technical Tutorials**: Step-by-step guides with code +2. **Problem-Solution Posts**: Real-world challenges and fixes +3. **Concept Explainers**: Mental models and architecture (like Skills Catalog) +4. **Tools & Productivity**: Reviews and how-tos +5. **Opinion & Commentary**: Industry insights (like AI humility post) +6. **Series**: Multi-part deep dives (like Skills Catalog 1-3) diff --git a/.github/agents/image-media-manager.md b/.github/agents/image-media-manager.md new file mode 100644 index 00000000..d6b6d124 --- /dev/null +++ b/.github/agents/image-media-manager.md @@ -0,0 +1,149 @@ +--- +name: Image and Media Manager +description: Specialized agent for managing blog post images, ensuring proper formatting, optimization, alt text, and Cloudinary integration. + +tools: + - read + - view + - edit + - bash + - search + +mcp-servers: + - name: github + tools: ["*"] +--- + +# Image and Media Manager Agent + +## Purpose +Ensure all images and media in blog posts are properly formatted, accessible, optimized, and integrated with Cloudinary. + +## Key Responsibilities + +### 1. Image Organization +- Verify images are stored in `images/[post-slug]/` directory +- Check file naming is descriptive (no generic names like "image1.png") +- Ensure image formats are appropriate (PNG for diagrams, JPG for photos) +- Keep image directories organized and clean + +### 2. Image References in Posts +- Verify correct usage of image include: + ```liquid + {% include image.html path="filename.ext" alt="description" %} + ``` +- Check path is filename only (not full URL or folder path) +- Ensure no direct markdown image syntax (`![alt](path)`) is used +- Validate all image includes are properly formatted + +### 3. Alt Text Quality +- Every image must have descriptive alt text +- Alt text should describe the content, not just repeat the filename +- Alt text should be concise but informative +- For code screenshots, alt text should summarize what the code does +- For diagrams, alt text should explain the concept + +### 4. Cloudinary Integration +- Understand that Cloudinary handles: + - Automatic optimization + - Social media image generation (OG images) + - Responsive image delivery +- Verify OG image background is set: `/images/Black.jpg` +- Check that social media previews will work correctly + +### 5. Accessibility +- All images need meaningful alt text +- Decorative images should have empty alt text (`alt=""`) +- Complex diagrams should have detailed descriptions +- Color contrast considerations for text in images +- Avoid text-heavy images when possible + +### 6. Media Best Practices +- Compress images before adding to repo +- Avoid unnecessarily large images (optimize for web) +- Use appropriate dimensions (not oversized) +- Consider mobile viewing experience +- Test image loading and rendering + +## Image Checklist + +For each image: +- [ ] Stored in `images/[post-slug]/` directory +- [ ] Descriptive filename +- [ ] Referenced using `{% include image.html %}` +- [ ] Path is filename only +- [ ] Has meaningful alt text +- [ ] Appropriate format (PNG/JPG) +- [ ] Optimized for web (reasonable file size) +- [ ] Loads correctly + +## Common Issues to Catch + +1. **Incorrect image include syntax**: + - ❌ `{% include image.html path="images/post-slug/file.png" %}` + - ✅ `{% include image.html path="file.png" %}` + +2. **Missing or poor alt text**: + - ❌ `alt="image"` + - ❌ `alt="screenshot.png"` + - ✅ `alt="Azure pipeline configuration showing monorepo path filters"` + +3. **Wrong image format**: + - Diagrams/screenshots → PNG + - Photos → JPG + - Icons/logos → PNG or SVG + +4. **Missing images**: + - Post references image but file doesn't exist + - Typo in filename + - Image in wrong directory + +## Workflow + +1. Read blog post and find all image references +2. For each image: + - Verify file exists in correct location + - Check include syntax + - Review alt text quality + - Validate file format and size +3. Check social media image configuration +4. Suggest improvements or corrections + +## Alt Text Guidelines + +**Good alt text examples**: +- "PowerShell console showing successful module installation" +- "Diagram illustrating Skills Catalog hierarchical structure" +- "GitHub Actions workflow YAML file with monorepo triggers" +- "VS Code workspace configuration for org-skills repository" + +**Poor alt text examples**: +- "image" +- "screenshot" +- "diagram.png" +- "click here" + +## Tools Usage + +- **bash**: Check if image files exist, list images in directories +- **read/view**: Read posts and check image references +- **edit**: Fix image includes and alt text +- **search**: Find posts with missing images or poor alt text + +## Reference Files + +- `.github/copilot-instructions.md` - Image management section +- `_config.yml` - Cloudinary configuration (ogImageBackground) +- `_includes/image.html` - Image include template +- Existing posts for image usage examples + +## Blog-Specific Image Types + +Common images in this blog: +1. **Code screenshots**: Terminal outputs, editor views +2. **Diagrams**: Architecture, workflows, concepts +3. **UI screenshots**: Application interfaces, dashboards +4. **Charts/graphs**: Analytics, comparisons +5. **Social media**: Auto-generated OG images via Cloudinary + +Ensure all images serve a purpose and enhance the content rather than just decorating it. diff --git a/.github/agents/publishing-workflow-manager.md b/.github/agents/publishing-workflow-manager.md new file mode 100644 index 00000000..36d87799 --- /dev/null +++ b/.github/agents/publishing-workflow-manager.md @@ -0,0 +1,201 @@ +--- +name: Publishing Workflow Manager +description: Specialized agent for managing the complete blog post publishing workflow, from draft to publication, ensuring all quality checks are completed. + +tools: + - read + - view + - edit + - bash + - report_progress + +mcp-servers: + - name: github + tools: ["*"] +--- + +# Publishing Workflow Manager Agent + +## Purpose +Orchestrate the complete publishing workflow for blog posts, ensuring all quality gates are passed before publication. + +## Key Responsibilities + +### 1. Pre-Publication Checklist +Run through complete quality assurance before setting `published: true`: + +**Content Quality**: +- [ ] Post follows standard structure (Hook → Problem → Solution → Conclusion) +- [ ] Writing follows Strunk & White + Zinsser principles +- [ ] Technical accuracy verified +- [ ] Code examples tested and working +- [ ] All links are valid and working + +**SEO Optimization**: +- [ ] Title is 50-60 characters +- [ ] Description is 150-160 characters +- [ ] Primary keyword in title, description, first paragraph +- [ ] 2-5 relevant tags selected +- [ ] Appropriate category chosen + +**Technical Requirements**: +- [ ] File naming: `YYYY-MM-DD-title-slug.md` +- [ ] Frontmatter complete and valid +- [ ] Images properly referenced +- [ ] All images have alt text +- [ ] Code blocks have language specification +- [ ] Markdown formatting correct + +**Cross-References**: +- [ ] Internal links to related posts +- [ ] Series posts are properly linked +- [ ] External links are authoritative and current + +### 2. Publication Workflow + +**Stage 1: Draft Creation** +- File created with `published: false` +- Basic structure in place +- Initial content written + +**Stage 2: Content Review** +- Technical editor reviews for accuracy and style +- Code reviewer tests all examples +- SEO specialist optimizes metadata +- Image manager verifies media + +**Stage 3: Quality Assurance** +- All checklist items verified +- Build test passes locally +- Links validated +- Final proofreading complete + +**Stage 4: Publication** +- Set `published: true` +- Set `modified` date to publication date +- Commit with clear message +- Push to trigger GitHub Pages build + +**Stage 5: Post-Publication** +- Verify site builds successfully +- Check post renders correctly +- Test social media preview +- Monitor for any issues + +### 3. Series Management + +For multi-part series (like Skills Catalog): +- Ensure consistent naming pattern +- Add series indicator in each post (e.g., "Part 1 of 3") +- Cross-link between parts +- Publish in order with proper timing +- Update earlier parts with links to later parts + +### 4. Jekyll Build Validation + +Before publication: +```bash +# Test local build +bundle exec jekyll build + +# Check for errors in output +# Verify no broken links +# Ensure images load correctly +``` + +### 5. Frontmatter Validation + +Ensure all required fields are present and correctly formatted: +```yaml +--- +published: true # boolean +layout: post # always "post" for blog posts +title: "Title Here" # 50-60 chars +description: "..." # 150-160 chars +modified: 2025-11-02 # YYYY-MM-DD format +tags: # 2-5 tags + - Tag1 + - Tag2 +categories: # single category + - Category Name +--- +``` + +## Publication Timeline + +**Typical workflow**: +1. **Day 1**: Draft created, initial content written +2. **Day 2-3**: Review cycle (technical, code, SEO, images) +3. **Day 4**: Revisions and quality assurance +4. **Day 5**: Final checks and publication + +**Fast-track workflow** (for time-sensitive content): +1. **Hour 1**: Draft written +2. **Hour 2**: All reviews completed in parallel +3. **Hour 3**: Revisions and publication + +## Common Publication Issues + +1. **Build failures**: + - Invalid frontmatter YAML + - Malformed liquid tags + - Missing images + - Syntax errors in HTML/markdown + +2. **Rendering issues**: + - Images not loading + - Code blocks not highlighting + - Broken internal links + - Social media preview not working + +3. **SEO problems**: + - Title/description too long + - Missing or duplicate metadata + - Poor keyword targeting + - No internal linking + +## Workflow Coordination + +**When to involve each specialist**: + +1. **Content Strategist**: Before writing starts (planning) +2. **Technical Editor**: After draft complete (review) +3. **Code Reviewer**: After technical content complete (validation) +4. **SEO Specialist**: After content finalized (optimization) +5. **Image Manager**: When images are added (formatting) +6. **Publishing Manager**: Before publication (final QA) + +## Tools Usage + +- **bash**: Run Jekyll builds, validate files +- **read/view**: Review posts and check status +- **edit**: Update publication status and dates +- **report_progress**: Commit and push publication +- **search**: Find related posts, check for duplicates + +## Reference Files + +- `.github/copilot-instructions.md` - Complete workflow documentation +- `.github/instructions/writers-guide.instructions.md` - Detailed checklist +- `_config.yml` - Site configuration and permalink structure +- `Gemfile` - Jekyll dependencies + +## Quality Gates + +No post should be published without: +1. ✅ Technical accuracy verified +2. ✅ Code examples tested +3. ✅ SEO optimized +4. ✅ Images properly formatted +5. ✅ Local build successful +6. ✅ All checklist items complete + +## Post-Publication Monitoring + +After publication: +- Check GitHub Pages build status +- Visit live post URL +- Test social media preview +- Verify in site search +- Check category/tag pages +- Monitor analytics for initial traffic diff --git a/.github/agents/seo-specialist.md b/.github/agents/seo-specialist.md new file mode 100644 index 00000000..8b024012 --- /dev/null +++ b/.github/agents/seo-specialist.md @@ -0,0 +1,113 @@ +--- +name: SEO Specialist +description: Specialized agent for optimizing blog posts for search engines, managing keywords, meta descriptions, and ensuring maximum discoverability. + +tools: + - read + - search + - view + - edit + - bash + +mcp-servers: + - name: github + tools: ["*"] +--- + +# SEO Specialist Agent + +## Purpose +Optimize blog posts for search engine visibility while maintaining natural, reader-friendly content. + +## Key Responsibilities + +### 1. Frontmatter SEO Optimization +- **Title optimization**: + - 50-60 characters (6-10 words ideal) + - Place primary keyword at the beginning if natural + - Use action words and emotional hooks + - Ensure accuracy to content +- **Description optimization**: + - 150-160 characters maximum + - Expand on title with additional context + - Include primary keyword and value proposition + - Match searcher intent +- **Tags management**: + - 2-5 relevant tags maximum + - Use existing tags from `tags/` directory when possible + - Avoid tag spam +- **Category selection**: + - Choose from existing categories: `AI and Technology`, `DevOps`, `Web Development`, `Documentation` + - Create new category only when necessary + +### 2. Keyword Strategy +- Research keywords the target audience uses +- Place primary keyword in: + - Title + - Description + - First paragraph + - At least one H2 heading + - Naturally throughout content +- Use 2-3 relevant keywords maximum per post +- Focus on long-tail keyword variations +- Avoid keyword stuffing + +### 3. Content Quality for SEO +- Ensure content matches the intent suggested by title +- Verify content provides genuine value and actionable insights +- Check that paragraphs are short and scannable +- Ensure proper heading hierarchy (H1 → H2 → H3) +- Verify internal links to related posts +- Check for descriptive link text (no "click here") + +### 4. Technical SEO +- Verify permalink structure: `/:categories/:title/` +- Check that images have alt text +- Ensure code blocks have language specification +- Verify proper markdown formatting +- Check that meta tags will be generated correctly + +### 5. Analytics & Performance +- Monitor which keywords drive traffic (reference: Google Analytics G-4DS8LE3MB2) +- Suggest content updates based on search trends +- Identify opportunities for internal linking +- Track SEO improvements over time + +## Workflow + +1. Read the blog post from `_posts/` +2. Analyze frontmatter for SEO compliance +3. Research relevant keywords +4. Check keyword placement and density +5. Verify content quality and value +6. Ensure technical SEO elements +7. Provide optimization suggestions or make edits + +## SEO Checklist + +- [ ] Title is 50-60 characters +- [ ] Description is 150-160 characters +- [ ] Primary keyword in title +- [ ] Primary keyword in description +- [ ] Primary keyword in first paragraph +- [ ] 2-5 relevant tags +- [ ] Appropriate category selected +- [ ] Images have alt text +- [ ] Internal links to related posts +- [ ] Descriptive link text used +- [ ] Proper heading hierarchy +- [ ] Content matches title intent + +## Tools Usage + +- **read/view**: Read posts and analyze SEO elements +- **search**: Find related posts for internal linking +- **edit**: Optimize frontmatter and content +- **bash**: Check permalink generation, analyze site structure + +## Reference Files + +- `.github/copilot-instructions.md` - SEO requirements section +- `.github/instructions/writers-guide.instructions.md` - SEO optimization details +- `_config.yml` - Permalink structure and site configuration +- Existing posts for tag/category consistency diff --git a/.github/agents/technical-editor.md b/.github/agents/technical-editor.md new file mode 100644 index 00000000..eafbecbc --- /dev/null +++ b/.github/agents/technical-editor.md @@ -0,0 +1,79 @@ +--- +name: Technical Editor +description: Specialized agent for reviewing technical blog content, verifying accuracy, checking grammar and style consistency, and ensuring documentation clarity. + +tools: + - read + - search + - view + - edit + - bash + +mcp-servers: + - name: github + tools: ["*"] +--- + +# Technical Editor Agent + +## Purpose +Review and refine technical writing for accuracy, clarity, grammar, and consistency with the blog's style guide (Strunk & White + Zinsser). + +## Key Responsibilities + +### 1. Content Review +- Analyze blog posts in `_posts/` for structure and flow +- Ensure posts follow the standard structure: Hook → Problem/Context → Solution → Conclusion +- Verify proper use of headings, paragraphs, and formatting +- Check that posts are scannable with short paragraphs + +### 2. Accuracy Verification +- Cross-reference technical claims against source code examples +- Verify command-line examples and code snippets work as described +- Check links to external documentation and resources +- Ensure technical terminology is used correctly + +### 3. Style Consistency +- Enforce Strunk & White + Zinsser writing principles: + - Clarity over cleverness + - Omit needless words (aim to delete 10% each pass) + - Active voice: "Who does what?" structure + - Unity of design: One paragraph = one topic + - Personal, conversational tone +- Check for consistent terminology across posts +- Ensure proper markdown formatting + +### 4. Grammar & Clarity +- Identify ambiguities, run-on sentences, passive voice +- Fix typos, punctuation errors, and awkward phrasing +- Improve readability scores +- Test by reading aloud for logic jumps and rhythm + +### 5. SEO Compliance +- Verify title is 50-60 characters +- Verify description is 150-160 characters +- Check that 2-5 relevant tags are used +- Ensure primary keyword appears naturally in title, description, and content + +## Workflow + +1. Read the blog post from `_posts/` +2. Check frontmatter for SEO compliance +3. Review content structure and flow +4. Verify technical accuracy +5. Apply style guide corrections +6. Check grammar and clarity +7. Provide edit suggestions or make direct edits + +## Tools Usage + +- **read/view**: Read blog posts, style guides, and reference materials +- **search**: Find related posts or style guide references +- **edit**: Make corrections directly to posts +- **bash**: Test code snippets and commands mentioned in posts + +## Reference Files + +- `.github/copilot-instructions.md` - Repository standards +- `.github/instructions/writers-guide.instructions.md` - Detailed writing guide +- Existing posts in `_posts/` for style consistency diff --git a/_posts/2025-11-02-skills-catalog-part-1-indexing-ai-context.md b/_posts/2025-11-02-skills-catalog-part-1-indexing-ai-context.md new file mode 100644 index 00000000..32894e81 --- /dev/null +++ b/_posts/2025-11-02-skills-catalog-part-1-indexing-ai-context.md @@ -0,0 +1,271 @@ +--- +published: true +layout: post +title: "The Catalog Model: Indexing AI Context Like a Library" +description: "Stop shoving your entire library into context. Learn to build a Dewey Decimal-style index that lets AI discover and load organizational knowledge on demand." +modified: 2025-11-02 +tags: + - AI + - GitHub Copilot + - Developer Tools +categories: + - AI and Technology +--- + +**Part 1 of 3** in the Skills Catalog series + +What if I told you that the secret to scaling AI context isn't about cramming more information into the window—it's about building an index? + +Think about how a library works. You don't carry every book with you when you walk in. You use the card catalog (or nowadays, the computer system) to find exactly what you need, then pull that specific book from the shelf. The Dewey Decimal System doesn't contain the knowledge—it _points_ to it. + +That's the fundamental insight behind the Skills catalog pattern: **hint, then dive**. + +## The Context Window Problem + +Most AI implementations fall into one of two traps: + +1. **The Everything Approach**: Dump all your documentation, all your scripts, all your processes into every single conversation. Your context window fills up fast, the AI gets confused by irrelevant information, and you hit token limits before you've even started solving real problems. + +2. **The Nothing Approach**: Provide no context at all, forcing the AI to guess at your conventions, processes, and organizational knowledge. Every conversation starts from zero. + +Neither scales. But there's a third way. + +## The Library Metaphor + +When you walk into a library looking for information about Azure DevOps pipelines, you don't need to see every book in the building. You need: + +1. **An index** that tells you Azure DevOps resources exist +2. **Enough metadata** to decide if that's what you need +3. **A path** to the detailed information if you want it + +The librarian doesn't follow you around reading every book aloud. They point you to the right section, and you decide which books to open. + +Your AI should work the same way. + +## The Skills Table Pattern + +Here's the core mechanic: a simple markdown table that lives in a file that's _always_ in context, listing what knowledge is available: + +```markdown +| Skill Name | Description | Path | +|------------|-------------|------| +| Azure DevOps Pipelines | Work with Azure DevOps YAML pipelines, triggers, variables | `.github/skills/azure-devops-pipelines.md` | +| PowerShell Standards | Coding standards and common patterns for PowerShell | `.github/skills/powershell-standards.md` | +| React Component Patterns | Approved component patterns and examples | `.github/skills/react-patterns.md` | +``` + +This table becomes your Dewey Decimal System. It's small—maybe a few kilobytes—so it fits comfortably in every context window. But it _hints_ at hundreds or thousands of detailed documents. + +When the AI sees a question about Azure pipelines, it: +1. Scans the table +2. Recognizes "Azure DevOps Pipelines" is relevant +3. Reads `.github/skills/azure-devops-pipelines.md` for the details +4. Uses that knowledge to answer your question + +The detailed information loads **on demand**, not upfront. + +## Platform-Agnostic Setup + +This pattern works across AI platforms because it relies on a simple principle: every platform has _some_ file that's always in context. + +**The emerging standard**: `AGENTS.md` is becoming the universal instruction file adopted by 40,000+ projects and supported by OpenAI Codex, Cursor, Gemini CLI, Aider, Factory, and other tools. It's placed in your project root and discovered hierarchically up the directory tree. + +**Platform-specific files** still exist for tools that haven't adopted AGENTS.md: +- **GitHub Copilot**: `.github/copilot-instructions.md` +- **Claude Code**: `CLAUDE.md` +- **Cursor**: `AGENTS.md` (primary) or `.cursorrules` (legacy) +- **Codex CLI**: `AGENTS.md` (can be generated via `/init` command) +- **Gemini CLI**: `AGENTS.md` (primary) or `GEMINI.md` (legacy) + +The pattern stays the same regardless of platform: one always-loaded file contains your skills table (or references it). + +### Vendor-Agnostic Implementation with AGENTS.md + +The cleanest approach leverages the emerging `AGENTS.md` standard. Create it once, and tools that support the standard will automatically discover it. + +**Step 1**: Create `AGENTS.md` in your repository root: + +```markdown +# Skills Catalog + +This repository uses a skills-based knowledge system. When working on a task, check this table to see what organizational knowledge is available. + +## Available Skills + +| Skill Name | Description | Path | +|------------|-------------|------| +| Azure DevOps Pipelines | Work with Azure DevOps YAML pipelines, triggers, variables, and monorepo support | `.github/skills/azure-devops-pipelines.md` | +| PowerShell Standards | Our coding standards, approved modules, and common patterns for PowerShell scripts | `.github/skills/powershell-standards.md` | + +## How to Use Skills + +When you encounter a task related to a skill: +1. Read the skill file at the listed path +2. Follow any guidance, standards, or templates provided +3. Use any scripts referenced in the skill file +``` + +**Step 2**: For tools that don't support AGENTS.md yet, create symlinks or copy the content. + +For **GitHub Copilot**, create `.github/copilot-instructions.md`: + +```markdown +# GitHub Copilot Instructions + +Always read and follow the skills catalog in `AGENTS.md`. +``` + +For **Claude Code**, create a symlink (or copy) from `AGENTS.md`: + +```bash +ln -s AGENTS.md CLAUDE.md +``` + +For **Cursor**, the tool already supports `AGENTS.md`, but you can also create `.cursorrules` as a symlink for backward compatibility: + +```bash +ln -s AGENTS.md .cursorrules +``` + +**Migration tip**: If you have existing instruction files, consolidate them into `AGENTS.md` and create symlinks: + +```bash +mv .github/copilot-instructions.md AGENTS.md +ln -s AGENTS.md .github/copilot-instructions.md +ln -s AGENTS.md CLAUDE.md +ln -s AGENTS.md .cursorrules +``` + +Now your skills catalog lives in one standard location. When you add a new skill, you update `AGENTS.md` once, and all AI tools configured to read it see the update. + +### Alternative: Platform-Specific Instructions + +If you prefer to keep everything in each platform's native file without the extra indirection, you can embed the skills table directly: + +**GitHub Copilot** (`.github/copilot-instructions.md`): + +```markdown +# Repository Skills Catalog + +This repository uses a skills-based knowledge system. When working on a task, check this table to see what organizational knowledge is available. + +## Available Skills + +| Skill Name | Description | Path | +|------------|-------------|------| +| Azure DevOps Pipelines | Work with Azure DevOps YAML pipelines, triggers, variables, and monorepo support | `.github/skills/azure-devops-pipelines.md` | +| PowerShell Standards | Our coding standards, approved modules, and common patterns for PowerShell scripts | `.github/skills/powershell-standards.md` | + +## How to Use Skills + +When you encounter a task related to a skill: +1. Read the skill file at the listed path +2. Follow any guidance, standards, or templates provided +3. Use any scripts referenced in the skill file +``` + +Both approaches work. The `root-skills.md` pattern keeps your catalog truly vendor-agnostic and easier to maintain. The embedded approach requires duplicating the table across platform files but keeps each platform self-contained. + +**Recommendation**: Start with `root-skills.md` for simplicity. You can always inline it later if needed. + +## Why This Scales + +Let's do the math. Each row in your skills table costs maybe 50-100 tokens. A catalog of 100 skills costs around 5,000-10,000 tokens—negligible in modern context windows. + +But each skill file might be 5,000-50,000 tokens. If you loaded all 100 skills upfront, you'd use 500,000-5,000,000 tokens before the conversation even started. + +**The catalog lets you scale to hundreds of skills while keeping your base context lean.** + +More importantly, the AI only loads what it needs. Working on Azure pipelines? It loads the Azure skill. Working on React components? It ignores Azure entirely and loads React patterns instead. + +You get: +- Precision: Only relevant knowledge loads +- Scale: Hundreds of skills supported +- Performance: Lean base context window +- Clarity: AI knows what it doesn't know + +## The "Hint, Then Dive" Workflow + +Here's what it looks like in practice: + +**User**: "Help me set up a monorepo trigger for our Azure pipeline" + +**AI internal process**: +1. Scans copilot-instructions.md, sees the skills table +2. Identifies "Azure DevOps Pipelines" skill mentions "monorepo support" +3. Reads `.github/skills/azure-devops-pipelines.md` +4. Finds a section on monorepo triggers with examples +5. Applies that knowledge to generate the YAML + +**AI response**: "I can help with that. For monorepos, you'll want to use path filters in your trigger section..." + +The AI **discovered** the Azure DevOps skill existed, **chose** to load it, and **applied** the knowledge—all without you manually selecting what to include. + +## What Goes in a Skill File? + +Each skill file (like `.github/skills/azure-devops-pipelines.md`) should contain: + +1. **Overview**: What this skill covers +2. **Key concepts**: Core knowledge +3. **Standards**: Your organizational conventions +4. **Examples**: Code samples, templates +5. **Scripts**: Paths to executable automation (more on this in Part 2) +6. **References**: Links to external docs + +Keep it focused. One skill file = one domain of knowledge. + +If a skill file grows beyond 10-20KB, that's a signal to break it into sub-skills (covered in Part 2). + +## Path-Specific Instructions + +GitHub Copilot supports even more granularity through path-specific instruction files in `.github/instructions/`: + +Create `.github/instructions/api-standards.instructions.md`: + +```markdown +--- +applyTo: "src/api/**" +--- + +When working with files in src/api/: +- All API endpoints must include OpenAPI documentation +- Use the request validation middleware +- See `.github/skills/api-patterns.md` for approved patterns +``` + +Now, when working on files in `src/api/`, Copilot automatically applies these rules _and_ knows to reference the API patterns skill. + +You're building layers: +- **Repository-wide**: `.github/copilot-instructions.md` with the skills table +- **Path-specific**: `.github/instructions/*.instructions.md` for targeted guidance +- **Skill files**: `.github/skills/*.md` for detailed domain knowledge + +## Real-World Impact + +I've used this pattern to: + +- Build a catalog of 50+ organizational skills across development, DevOps, and infrastructure +- Reduce context window bloat by 80%+ (from megabytes of docs to a tiny index) +- Enable teams to discover knowledge they didn't know existed +- Create portable, shareable knowledge bases + +The best part? This isn't bleeding-edge tech. It's just good information architecture applied to AI context management. + +## Next Steps + +In **Part 2**, we'll dive into building nested skills (like Azure DevOps → Repos → Branch Policies → PR Automation) and explore how scripts become on-demand execution primitives that keep your catalog lean while maintaining power. + +In **Part 3**, we'll see how to distribute a shared skills repository across your entire organization using VS Code workspaces, making organizational knowledge instantly available in any project. + +But for now, start simple: + +1. Create `AGENTS.md` in your repository root (this is the emerging standard supported by Codex, Cursor, Gemini CLI, and others) +2. Add a skills table with 2-3 domains you work with regularly +3. Create one skill file with your team's conventions +4. For GitHub Copilot, create `.github/copilot-instructions.md` that references `AGENTS.md` +5. For Claude Code, create a `CLAUDE.md` symlink to `AGENTS.md` +6. Watch as the AI starts discovering and applying your organizational knowledge + +You're not teaching the AI everything upfront. You're teaching it where to look when it needs to know something. + +That's the power of the catalog. diff --git a/_posts/2025-11-02-skills-catalog-part-2-building-skills-that-scale.md b/_posts/2025-11-02-skills-catalog-part-2-building-skills-that-scale.md new file mode 100644 index 00000000..3b8869df --- /dev/null +++ b/_posts/2025-11-02-skills-catalog-part-2-building-skills-that-scale.md @@ -0,0 +1,440 @@ +--- +published: true +layout: post +title: "Building Skills That Scale: Nested Domains and Scripts" +description: "Organize hundreds of AI skills using nested domains and on-demand scripts. Keep your context window lean while maintaining full power and flexibility." +modified: 2025-11-02 +tags: + - AI + - GitHub Copilot + - DevOps + - Automation +categories: + - AI and Technology +--- + +**Part 2 of 3** in the Skills Catalog series ([Part 1](/ai-and-technology/skills-catalog-part-1-indexing-ai-context)) + +In Part 1, we introduced the skills catalog pattern—a Dewey Decimal-style index for AI context. Now we tackle the real challenge: **organizing knowledge that scales to hundreds of skills without becoming a mess.** + +The key is two-fold: +1. **Nested skills** that keep the top-level catalog clean while allowing deep specialization +2. **Scripts as execution primitives** that load only when invoked, not upfront + +Let's build it. + +## The Depth Problem + +Your initial skills table might look like this: + +```markdown +| Skill Name | Description | Path | +|------------|-------------|------| +| Azure DevOps | Everything about Azure DevOps | `.github/skills/azure-devops.md` | +``` + +But "everything about Azure DevOps" is huge: +- Repositories (branches, PRs, policies) +- Pipelines (YAML, triggers, variables, environments) +- Work items (queries, custom fields, automation) +- Boards (columns, swimlanes, sprints) +- Artifacts (feeds, packages, retention) + +If you dump all that into one skill file, it becomes a 100KB document that defeats the purpose of selective loading. The AI has to wade through pipeline documentation when you're asking about work item queries. + +**Solution**: Nested skills. + +## Building Nested Domain Skills + +Think hierarchical, like organizing a library by subject, then sub-subject, then topic. + +### Top-Level Catalog + +Your main `.github/copilot-instructions.md` stays focused on high-level domains: + +```markdown +## Available Skills + +| Skill Name | Description | Path | +|------------|-------------|------| +| Azure DevOps | Work with Azure DevOps repos, pipelines, work items, and boards | `.github/skills/azure-devops/index.md` | +| PowerShell | PowerShell coding standards, modules, and patterns | `.github/skills/powershell/index.md` | +| React | React component patterns and standards | `.github/skills/react/index.md` | +``` + +Notice: each skill now points to an `index.md` inside a folder, not a standalone file. + +### Domain Index + +`.github/skills/azure-devops/index.md` becomes a sub-catalog: + +```markdown +# Azure DevOps Skill + +This skill covers Azure DevOps tools and workflows. + +## Sub-Skills + +| Sub-Skill | Description | Path | +|-----------|-------------|------| +| Repositories | Branch policies, PRs, code reviews | `./repos.md` | +| Pipelines | YAML pipelines, triggers, monorepo support | `./pipelines.md` | +| Work Items | Queries, custom fields, automation rules | `./work-items.md` | + +## Quick References + +- Organization: `https://dev.azure.com/yourorg` +- Project: `YourProject` +- Common repos: `platform`, `services`, `infrastructure` + +## Scripts + +Scripts for Azure DevOps operations live in `./scripts/`: +- `get-related-work-items.ps1` - Get work items for a pipeline run (monorepo-aware) +- `create-pr.ps1` - Create a PR with standard template and reviewers +``` + +Now the AI has two levels of indexing: +1. Main catalog → Azure DevOps skill exists +2. Azure DevOps index → Pipelines sub-skill for monorepo questions + +### Sub-Skill Files + +`.github/skills/azure-devops/pipelines.md` contains focused, actionable knowledge: + +```markdown +# Azure DevOps Pipelines + +## YAML Pipeline Standards + +All pipelines must: +- Use YAML (no classic pipelines) +- Include `trigger.paths` for monorepos +- Use named stages for multi-stage deployments +- Reference templates from the `pipeline-templates` repo + +## Monorepo Trigger Pattern + +For monorepos, always filter triggers by path: + +```yaml +trigger: + branches: + include: + - main + paths: + include: + - services/api/* + - shared/common/* +``` + +## Getting Related Work Items + +Azure DevOps's built-in "Related Work Items" feature doesn't support monorepos. Use our custom script instead: + +```bash +pwsh .github/skills/azure-devops/scripts/get-related-work-items.ps1 -BuildId $BUILD_BUILDID +``` + +See `./scripts/get-related-work-items.ps1` for details. + +## Pipeline Variables + +Standard variables we use: +- `BuildConfiguration` - Debug or Release +- `DeploymentEnvironment` - dev, staging, prod +- `RunTests` - true/false + +## Templates + +Reusable templates live in our `pipeline-templates` repo: +- `build-dotnet.yml` - Standard .NET build +- `deploy-azure-app.yml` - Azure App Service deployment +- `run-integration-tests.yml` - Integration test harness +``` + +Clean. Focused. No more than you need for pipeline questions. + +## Directory Structure + +Here's what a mature Azure DevOps skill looks like: + +``` +.github/skills/azure-devops/ +├── index.md # Sub-skills catalog +├── repos.md # Repository sub-skill +├── pipelines.md # Pipelines sub-skill +├── work-items.md # Work items sub-skill +├── scripts/ +│ ├── get-related-work-items.ps1 +│ ├── create-pr.ps1 +│ └── query-work-items.ps1 +└── templates/ + ├── pr-template.md + └── pipeline-template.yml +``` + +Each `.md` file is 5-15KB. Totally manageable. The AI loads the index, identifies the relevant sub-skill, and dives into just that file. + +## Scripts: On-Demand Execution + +Here's where it gets powerful. Scripts are knowledge that _does things_. + +Traditional approach (bad): Document how to get related work items for a pipeline run. Hope the AI generates correct code every time. + +**Skills approach (good)**: Provide a tested, working script. The AI invokes it. + +### Script Conventions + +Scripts in skill folders follow these rules: + +1. **Self-contained**: Include all dependencies, parameter descriptions +2. **Documented**: Header comments explain purpose, parameters, examples +3. **Tested**: These run in production; they must work +4. **Referenced**: Skill `.md` files tell the AI when to use them + +Example from `.github/skills/azure-devops/scripts/get-related-work-items.ps1`: + +```powershell +#Requires -PSEdition Core + +<# +.SYNOPSIS + Retrieves commits and work items for a build pipeline with monorepo support. + +.DESCRIPTION + Azure DevOps's built-in "Related Work Items" feature doesn't filter by + pipeline trigger paths in monorepos. This script does. + +.PARAMETER BuildId + The ID of the build. Defaults to $ENV:BUILD_BUILDID in Azure Pipelines. + +.PARAMETER CollectionUri + Azure DevOps organization URI. Defaults to $ENV:SYSTEM_COLLECTIONURI. + +.EXAMPLE + ./get-related-work-items.ps1 -BuildId 12345 + +.NOTES + Requires the powershell-yaml module for parsing YAML pipeline files. +#> + +[CmdletBinding()] +param ( + [Parameter()] + [int]$BuildId = $ENV:BUILD_BUILDID, + + [Parameter()] + [Uri]$CollectionUri = $ENV:SYSTEM_COLLECTIONURI, + + [Parameter()] + [Guid]$ProjectId = $ENV:SYSTEM_TEAMPROJECTID, + + [Parameter()] + $AuthorizationHeader = "Bearer $ENV:SYSTEM_ACCESSTOKEN" +) + +# Script implementation... +# (Full implementation omitted for brevity - see Part 1 for complete code) +``` + +Now, when the AI encounters a monorepo pipeline question, it: +1. Loads the pipelines sub-skill +2. Sees the script reference +3. Suggests running the script or shows how to invoke it + +**You get deterministic, tested behavior instead of AI-generated code that might have bugs.** + +## Why Scripts Beat Always-On Tools + +Some platforms (like Claude) support MCP (Model Context Protocol) servers—background processes that expose tools to the AI. They're powerful, but they have a cost: **they're always in your context window**, whether you need them or not. + +Imagine 20 MCP servers, each advertising 10-50 tools. That's 200-1000 tool descriptions occupying your context before you've asked a single question. + +**Scripts are opt-in.** They only load when: +1. The AI reads the skill file that references them +2. The skill file is relevant to your question + +For Azure DevOps questions, you get Azure scripts. For React questions, you get React scripts. Not both. + +### Invoking MCP via Scripts + +But what if a vendor ships an MCP server without a CLI? You still want opt-in behavior. + +**Solution**: Wrap the MCP server in a lightweight CLI client, then call it from scripts. + +Example: A hypothetical Jira MCP server. + +Create `.github/skills/jira/scripts/mcp-client.sh`: + +```bash +#!/bin/bash +# Lightweight MCP client that invokes Jira MCP server tools + +TOOL_NAME=$1 +shift +ARGS="$@" + +# Connect to MCP server and invoke tool +npx @your-org/mcp-client \ + --server jira-mcp-server \ + --tool "$TOOL_NAME" \ + --args "$ARGS" +``` + +Now your Jira skill can reference `./scripts/create-issue.sh`: + +```bash +#!/bin/bash +# Create a Jira issue + +./mcp-client.sh create-issue \ + --project "PROJ" \ + --summary "$1" \ + --description "$2" +``` + +The MCP server's capabilities are available, but only when the Jira skill loads and the AI decides to run the script. + +**You control when capabilities enter the context.** + +## Composing Skills: The Fractal Pattern + +Nested skills can go deeper. Azure DevOps → Pipelines → Monorepo Triggers → Path Filtering. + +Just add another layer: + +``` +.github/skills/azure-devops/pipelines/ +├── index.md # Pipelines overview + sub-catalog +├── triggers.md # Trigger patterns +├── variables.md # Variables and parameters +├── templates.md # Template usage +└── monorepo/ + ├── index.md # Monorepo-specific guidance + ├── path-filtering.md # Path filter patterns + └── scripts/ + └── get-related-work-items.ps1 +``` + +Each level maintains a catalog. The AI navigates from general to specific, loading only what it needs. + +**Practical limit**: 3-4 levels deep. Beyond that, you're over-organizing. + +## Section Conventions + +Within each skill file, use consistent sections: + +```markdown +# [Skill Name] + +## Overview +What this skill covers + +## Standards +Your organizational rules + +## Common Patterns +Frequently used code/configs + +## Scripts +Executable automation + +## Templates +Starting points + +## Troubleshooting +Known issues and fixes + +## References +External docs, links +``` + +The AI learns this structure across skills, making it faster at finding information. + +## Building Your First Nested Skill + +Let's walk through creating a real Azure DevOps skill with sub-skills. + +**Step 1**: Create the directory structure + +```bash +mkdir -p .github/skills/azure-devops/{scripts,templates} +``` + +**Step 2**: Create the index (`.github/skills/azure-devops/index.md`) + +```markdown +# Azure DevOps Skill + +## Sub-Skills + +| Sub-Skill | Description | Path | +|-----------|-------------|------| +| Pipelines | YAML pipelines, triggers, monorepo support | `./pipelines.md` | + +## Scripts + +- `scripts/get-related-work-items.ps1` - Get work items for a pipeline run +``` + +**Step 3**: Create the pipelines sub-skill (`.github/skills/azure-devops/pipelines.md`) + +Include your team's standards, examples, script references (as shown earlier). + +**Step 4**: Add a working script (`.github/skills/azure-devops/scripts/get-related-work-items.ps1`) + +Copy your tested PowerShell script. + +**Step 5**: Reference it in the main catalog (`.github/copilot-instructions.md`) + +```markdown +| Azure DevOps | Work with Azure DevOps repos, pipelines, work items | `.github/skills/azure-devops/index.md` | +``` + +**Step 6**: Test it + +Ask your AI: "How do I get the related work items for this pipeline run in our monorepo?" + +The AI should: +1. Find Azure DevOps in the main catalog +2. Load the index +3. Identify the Pipelines sub-skill +4. Reference the script + +You've just built a nested skill with executable knowledge. + +## The 100-Skill Vision + +With this structure, you can scale to 100+ skills: + +- **10 domain skills** (Azure DevOps, AWS, Docker, React, etc.) +- **5-10 sub-skills each** (50-100 sub-skills total) +- **2-5 scripts per sub-skill** (100-500 scripts total) + +Total catalog overhead: ~10KB (main) + ~50KB (indexes) = 60KB + +Total knowledge base: 5-50MB of detailed docs and scripts + +**The AI accesses megabytes of knowledge through a 60KB index.** + +That's the power of "hint, then dive." + +## Next: Organizational Distribution + +You've built a skill. You've nested it. You've added scripts. It's working great in your repository. + +But what about your other 50 repositories? Do you copy-paste the `.github/skills/` folder into each one? + +**No.** In Part 3, we'll build a shared skills repository and use VS Code workspaces to inject those skills into any project with a few clicks. Your organizational knowledge becomes portable, versionable, and instantly available everywhere. + +We'll also walk through a complete end-to-end demo: creating a new skill, wiring a script, invoking an MCP server, and watching it all work inside GitHub Copilot. + +For now, start nesting: + +1. Pick one skill from your catalog +2. Break it into 2-3 sub-skills +3. Move one repetitive task into a script +4. Reference the script in the skill file + +You're building a library, one indexed section at a time. diff --git a/_posts/2025-11-02-skills-catalog-part-3-organizational-knowledge-at-scale.md b/_posts/2025-11-02-skills-catalog-part-3-organizational-knowledge-at-scale.md new file mode 100644 index 00000000..0e1059ed --- /dev/null +++ b/_posts/2025-11-02-skills-catalog-part-3-organizational-knowledge-at-scale.md @@ -0,0 +1,678 @@ +--- +published: true +layout: post +title: "Organizational Knowledge at Scale: Distribution and Demo" +description: "Share AI skills across your entire organization using VS Code workspaces. Complete end-to-end demo of building and deploying organizational knowledge." +modified: 2025-11-02 +tags: + - AI + - GitHub Copilot + - DevOps + - Team Collaboration +categories: + - AI and Technology +--- + +**Part 3 of 3** in the Skills Catalog series ([Part 1](/ai-and-technology/skills-catalog-part-1-indexing-ai-context) | [Part 2](/ai-and-technology/skills-catalog-part-2-building-skills-that-scale)) + +You've built a beautiful skills catalog. Nested domains. Scripts that execute on demand. A clean index that scales to hundreds of skills. + +Now the question: **How do you share this across your 50 repositories without copy-pasting folders everywhere?** + +The answer: **A shared skills repository plus VS Code workspaces.** + +This final part shows you how to centralize organizational knowledge in one place and inject it into any project with a couple of clicks. Then we'll walk through a complete end-to-end demo—from adding a new skill to watching it work in GitHub Copilot. + +## The Portability Challenge + +Your `.github/skills/` directory is valuable. It contains: +- Organizational standards +- Tested scripts +- Domain expertise +- Battle-tested patterns + +But every team has multiple repositories: +- Frontend apps +- Backend services +- Infrastructure as code +- Shared libraries +- Documentation sites + +Do you copy `.github/skills/` into each repo? What happens when you update a script or add a new skill? Sync them all manually? + +**That doesn't scale.** + +## The Shared Skills Repository + +**Solution**: Create one repository that holds all organizational skills. Every other repository references it. + +### Repository Structure + +Create a new repository called `org-skills` (or whatever you prefer): + +``` +org-skills/ +├── README.md +├── skills/ +│ ├── azure-devops/ +│ │ ├── index.md +│ │ ├── pipelines.md +│ │ ├── repos.md +│ │ ├── work-items.md +│ │ └── scripts/ +│ │ ├── get-related-work-items.ps1 +│ │ └── create-pr.ps1 +│ ├── aws/ +│ │ ├── index.md +│ │ ├── ec2.md +│ │ ├── s3.md +│ │ └── scripts/ +│ ├── docker/ +│ │ ├── index.md +│ │ ├── compose.md +│ │ └── templates/ +│ ├── powershell/ +│ │ ├── index.md +│ │ ├── standards.md +│ │ └── modules.md +│ └── react/ +│ ├── index.md +│ ├── components.md +│ └── patterns.md +├── templates/ +│ ├── copilot-instructions.md +│ └── skill-template.md +└── .github/ + └── workflows/ + └── validate-skills.yml +``` + +This repository becomes your **single source of truth** for organizational knowledge. + +### Benefits + +1. **Version control**: Skills evolve over time; track changes +2. **Collaboration**: Teams contribute skills via PRs +3. **Validation**: CI can verify scripts work, markdown is valid, links aren't broken +4. **Discoverability**: New team members clone one repo and see all organizational knowledge +5. **Consistency**: Everyone uses the same versions of scripts and standards + +## VS Code Workspaces: The Injection Mechanism + +VS Code workspaces let you combine multiple folders into one workspace. This is your distribution mechanism. + +### How It Works + +In any project repository, create a `.code-workspace` file: + +**`my-app.code-workspace`**: + +```json +{ + "folders": [ + { + "name": "my-app", + "path": "." + }, + { + "name": "org-skills", + "path": "../org-skills" + } + ], + "settings": { + "github.copilot.enable": { + "*": true + } + } +} +``` + +This workspace includes: +1. The current repository (`.`) +2. The org-skills repository (`../org-skills`) + +When you open this workspace in VS Code, both folders are visible. More importantly, **GitHub Copilot sees both folders**. + +### Wiring Skills to Copilot + +Now update `.github/copilot-instructions.md` in your app repository: + +```markdown +# Project Instructions + +This repository uses organizational skills from the `org-skills` workspace folder. + +## Available Skills + +| Skill Name | Description | Path | +|------------|-------------|------| +| Azure DevOps | Work with Azure DevOps repos, pipelines, work items | `org-skills/skills/azure-devops/index.md` | +| AWS | AWS services and patterns | `org-skills/skills/aws/index.md` | +| Docker | Container standards and compose patterns | `org-skills/skills/docker/index.md` | +| PowerShell | PowerShell coding standards | `org-skills/skills/powershell/index.md` | +| React | React component patterns | `org-skills/skills/react/index.md` | + +## How to Use Skills + +When working on a task: +1. Check the skills table above for relevant organizational knowledge +2. Read the skill file at the listed path +3. Follow standards, use scripts, and reference templates +``` + +The paths reference `org-skills/skills/...` instead of `.github/skills/...`. When the AI reads the file path, it finds the content in the `org-skills` workspace folder. + +**You've just injected organizational knowledge without copying a single file.** + +## Bootstrapping New Projects + +When starting a new repository: + +1. **Clone the shared skills repo** alongside your new project: + +```bash +cd ~/projects +git clone https://github.com/your-org/my-new-app.git +git clone https://github.com/your-org/org-skills.git +``` + +2. **Create the workspace file** in `my-new-app`: + +```bash +cd my-new-app +cp ../org-skills/templates/my-app.code-workspace . +# Edit to rename workspace appropriately +``` + +3. **Copy the Copilot instructions template**: + +```bash +mkdir -p .github +cp ../org-skills/templates/copilot-instructions.md .github/copilot-instructions.md +``` + +4. **Open the workspace**: + +```bash +code my-new-app.code-workspace +``` + +**Done.** Your new project now has access to all organizational skills. + +## Updating Skills Everywhere + +When you add a new skill or update an existing one: + +1. **Make changes in `org-skills`** repository +2. **Commit and push** +3. **Every project pulls the latest** `org-skills`: + +```bash +cd ~/projects/org-skills +git pull +``` + +All workspaces that reference `org-skills` now see the updates. No syncing required. + +## Combining Repo-Specific and Org-Wide Knowledge + +You can layer knowledge: + +**`.github/copilot-instructions.md`** references org skills: + +```markdown +## Organizational Skills + +| Skill Name | Path | +|------------|------| +| Azure DevOps | `org-skills/skills/azure-devops/index.md` | +| PowerShell | `org-skills/skills/powershell/index.md` | + +## Project-Specific Knowledge + +This app uses: +- Database: PostgreSQL 14 on Azure +- API Framework: .NET 8 minimal APIs +- Frontend: React 18 with Vite +``` + +**`.github/instructions/api.instructions.md`** adds path-specific guidance: + +```markdown +--- +applyTo: "src/api/**" +--- + +When working with API code: +- Follow REST conventions in `org-skills/skills/api-design/rest.md` +- Use FluentValidation for request validation +- All endpoints return `ApiResponse` wrapper +- See `docs/api-standards.md` for this project's specific patterns +``` + +You get: +- **Org-wide standards** from the skills repo +- **Project-specific context** from the app repo +- **Path-specific rules** from instruction files + +The AI combines all layers to understand both general and specific context. + +## End-to-End Demo: Adding a New Skill + +Let's walk through the complete flow of adding a new skill, wiring a script, and using it in Copilot. + +### Scenario + +Your team uses GitHub Actions and wants to standardize workflow patterns. You'll create a GitHub Actions skill with a script that validates workflow YAML files. + +### Step 1: Create the Skill Structure + +In the `org-skills` repository: + +```bash +cd ~/projects/org-skills +mkdir -p skills/github-actions/{scripts,templates} +``` + +### Step 2: Create the Index + +**`skills/github-actions/index.md`**: + +```markdown +# GitHub Actions Skill + +Organizational standards for GitHub Actions workflows. + +## Sub-Skills + +| Sub-Skill | Description | Path | +|-----------|-------------|------| +| Workflows | Workflow patterns and standards | `./workflows.md` | +| Actions | Custom actions and reusable workflows | `./actions.md` | + +## Scripts + +- `scripts/validate-workflow.sh` - Validate workflow YAML syntax and best practices +- `scripts/create-workflow.sh` - Scaffold a new workflow from template + +## Templates + +- `templates/dotnet-build.yml` - Standard .NET build workflow +- `templates/deploy-azure.yml` - Azure deployment workflow +``` + +### Step 3: Create the Workflows Sub-Skill + +**`skills/github-actions/workflows.md`**: + +```markdown +# GitHub Actions Workflows + +## Standards + +All workflows must: +- Use `workflow_dispatch` for manual triggers +- Include `concurrency` groups to prevent duplicate runs +- Use official actions when available (actions/* over third-party) +- Pin action versions to specific SHA for security + +## Validation + +Before committing a workflow, validate it: + +```bash +./org-skills/skills/github-actions/scripts/validate-workflow.sh .github/workflows/build.yml +``` + +## Common Pattern: Build and Test + +```yaml +name: Build and Test + +on: + pull_request: + branches: [main] + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + - run: npm ci + - run: npm run build + - run: npm test +``` +``` + +### Step 4: Create the Validation Script + +**`skills/github-actions/scripts/validate-workflow.sh`**: + +```bash +#!/bin/bash + +# Validate GitHub Actions workflow YAML + +WORKFLOW_FILE=$1 + +if [ -z "$WORKFLOW_FILE" ]; then + echo "Usage: validate-workflow.sh " + exit 1 +fi + +if [ ! -f "$WORKFLOW_FILE" ]; then + echo "Error: File not found: $WORKFLOW_FILE" + exit 1 +fi + +echo "Validating $WORKFLOW_FILE..." + +# Check YAML syntax +if ! command -v yamllint &> /dev/null; then + echo "Installing yamllint..." + pip install yamllint +fi + +yamllint -d relaxed "$WORKFLOW_FILE" + +# Check for common issues +if ! grep -q "workflow_dispatch" "$WORKFLOW_FILE"; then + echo "Warning: Missing 'workflow_dispatch' trigger for manual runs" +fi + +if ! grep -q "concurrency" "$WORKFLOW_FILE"; then + echo "Warning: Missing 'concurrency' group to prevent duplicate runs" +fi + +# Check action versions (should be pinned) +if grep -q "@main\|@master" "$WORKFLOW_FILE"; then + echo "Error: Actions should be pinned to specific versions, not @main or @master" + exit 1 +fi + +echo "✓ Validation complete" +``` + +Make it executable: + +```bash +chmod +x skills/github-actions/scripts/validate-workflow.sh +``` + +### Step 5: Add to Main Catalog + +Update your org-skills catalog template (**`templates/copilot-instructions.md`**): + +```markdown +| GitHub Actions | Workflow standards and validation | `org-skills/skills/github-actions/index.md` | +``` + +### Step 6: Commit and Push + +```bash +git add skills/github-actions +git add templates/copilot-instructions.md +git commit -m "Add GitHub Actions skill with workflow validation" +git push +``` + +### Step 7: Pull into Project + +In any project that uses the workspace: + +```bash +cd ~/projects/my-app +cd ../org-skills +git pull +cd ../my-app +``` + +Update `.github/copilot-instructions.md` if needed to reference the new skill. + +### Step 8: Test in Copilot + +Open the workspace in VS Code: + +```bash +code my-app.code-workspace +``` + +Open GitHub Copilot chat and ask: + +> "What are our standards for GitHub Actions workflows?" + +**Expected behavior**: +1. Copilot scans `.github/copilot-instructions.md` +2. Finds "GitHub Actions" in the skills table +3. Loads `org-skills/skills/github-actions/index.md` +4. Reads `workflows.md` for details +5. Responds with your organizational standards + +Ask a follow-up: + +> "Create a workflow for building and testing a Node.js app" + +Copilot should generate a workflow following your standards (workflow_dispatch, concurrency, pinned versions). + +**You've just added organizational knowledge and watched it work in real-time.** + +## Invoking MCP Servers from Skills + +Earlier we mentioned wrapping MCP servers in scripts for opt-in loading. Here's how that looks in practice. + +### Scenario: Jira MCP Server + +Your vendor ships a Jira MCP server but no CLI. You want to use it from your Jira skill without having it always in context. + +### Step 1: Create MCP Client Wrapper + +**`org-skills/skills/jira/scripts/mcp-client.sh`**: + +```bash +#!/bin/bash +# Lightweight MCP client for Jira operations + +OPERATION=$1 +shift + +case $OPERATION in + create-issue) + SUMMARY=$1 + DESCRIPTION=$2 + npx @your-org/mcp-client \ + --server jira-mcp \ + --tool create-issue \ + --project "PROJ" \ + --summary "$SUMMARY" \ + --description "$DESCRIPTION" + ;; + get-issue) + ISSUE_KEY=$1 + npx @your-org/mcp-client \ + --server jira-mcp \ + --tool get-issue \ + --key "$ISSUE_KEY" + ;; + *) + echo "Unknown operation: $OPERATION" + exit 1 + ;; +esac +``` + +### Step 2: Create Convenience Scripts + +**`org-skills/skills/jira/scripts/create-issue.sh`**: + +```bash +#!/bin/bash +./mcp-client.sh create-issue "$1" "$2" +``` + +### Step 3: Reference in Skill + +**`skills/jira/index.md`**: + +```markdown +# Jira Skill + +## Scripts + +- `scripts/create-issue.sh ` - Create a Jira issue +- `scripts/get-issue.sh ` - Get issue details +``` + +Now the MCP server's capabilities are available, but only when the AI loads the Jira skill and decides to run a script. + +**The server isn't in context until needed.** + +## Validation and CI + +Add a GitHub Actions workflow to `org-skills` to validate skills: + +**`.github/workflows/validate-skills.yml`**: + +```yaml +name: Validate Skills + +on: [push, pull_request] + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Validate Markdown + run: | + npm install -g markdownlint-cli + markdownlint skills/**/*.md + + - name: Check Script Syntax + run: | + find skills -name "*.sh" -exec bash -n {} \; + find skills -name "*.ps1" -exec pwsh -NoProfile -Command "Test-Path {}" \; + + - name: Validate Links + run: | + npm install -g markdown-link-check + find skills -name "*.md" -exec markdown-link-check {} \; +``` + +This ensures: +- Markdown is properly formatted +- Scripts have valid syntax +- Links aren't broken + +Teams can confidently merge skill updates. + +## Complete Checklist: Adding a Skill + +When adding a new skill to `org-skills`: + +- [ ] Create directory structure: `skills//` +- [ ] Create index file: `skills//index.md` +- [ ] Add sub-skill files as needed +- [ ] Create `scripts/` directory if the skill has automation +- [ ] Create `templates/` directory if the skill provides starting files +- [ ] Add scripts with proper documentation headers +- [ ] Make scripts executable (`chmod +x`) +- [ ] Reference scripts in the index or sub-skill files +- [ ] Update `templates/copilot-instructions.md` with new skill row +- [ ] Commit with clear message describing the skill +- [ ] Create PR for review +- [ ] After merge, notify teams to pull latest `org-skills` + +## Distribution at Scale + +For large organizations: + +1. **One skills repo per division** (Engineering, DevOps, Data, etc.) +2. **Workspace includes multiple skill repos**: + +```json +{ + "folders": [ + {"name": "my-app", "path": "."}, + {"name": "engineering-skills", "path": "../engineering-skills"}, + {"name": "devops-skills", "path": "../devops-skills"} + ] +} +``` + +3. **Copilot instructions reference both**: + +```markdown +| Azure DevOps | ... | `devops-skills/skills/azure-devops/index.md` | +| React | ... | `engineering-skills/skills/react/index.md` | +``` + +Teams pull only the skills repos relevant to their work. + +## The Flywheel Effect + +As your skills catalog grows: + +1. **Developers discover knowledge they didn't know existed** + - "Oh, we have a standard pattern for this?" +2. **Tribal knowledge becomes documented** + - "Let me add that trick to the PowerShell skill" +3. **AI becomes more helpful** + - Consistent, accurate guidance across all projects +4. **Onboarding accelerates** + - New hires clone org-skills, get instant context +5. **Standards spread organically** + - Teams adopt patterns they see in skills + +The catalog becomes self-reinforcing. More skills → better AI responses → more trust → more contributions → more skills. + +## Measuring Success + +Track these metrics: + +- **Skills count**: How many domains are documented? +- **Script count**: How much automation is available? +- **Contribution rate**: How often do teams add/update skills? +- **Workspace adoption**: How many projects use the org-skills workspace? +- **AI accuracy**: Anecdotally, are Copilot suggestions improving? + +If skills stagnate, they're not useful. If they're growing, you're capturing organizational knowledge. + +## What You've Built + +Over these three parts, you've learned: + +**Part 1**: The catalog pattern—indexing knowledge so AI can discover and load it on demand, not upfront. + +**Part 2**: Nested skills and scripts—organizing hundreds of domains with hierarchical structure and deterministic execution primitives. + +**Part 3**: Organizational distribution—sharing knowledge across repositories with VS Code workspaces and a centralized skills repo. + +You now have a system for scaling AI context to **hundreds of skills** across **dozens of repositories** without overwhelming your context window or duplicating knowledge. + +## Getting Started Today + +1. **Create `org-skills` repository** in your organization +2. **Add 2-3 skills** from frequently-asked-about domains +3. **Create workspace files** for your top 2-3 projects +4. **Update Copilot instructions** to reference org-skills +5. **Test with your team**: Ask Copilot questions about those domains + +Start small. Grow organically. Let the flywheel spin. + +Your AI doesn't need to know everything. It just needs to know where to look. + +**That's the power of the skills catalog.** + +--- + +_Thanks for reading this series! If you build a skills catalog, I'd love to hear about it. Find me on [LinkedIn](https://linkedin.com/in/tiberriver256) or open an issue on this blog's [GitHub repo](https://github.com/Tiberriver256/Tiberriver256.GitHub.io) with your experience._