Implement Anthropic Claude Skills PowerShell port into PSAI

[Copilot]

Overview

This PR implements the Anthropic Claude Skills architecture pattern for PowerShell, enabling PSAI agents to use modular, filesystem-based capabilities with progressive disclosure. This brings the power of the Anthropic Claude Skills pattern to PowerShell AI agents.

What are Skills?

Skills are reusable, filesystem-based resources that provide AI agents with domain-specific expertise through a three-level loading architecture:

1. Level 1: Metadata (always loaded) - YAML frontmatter with name and description for skill discovery
2. Level 2: Instructions (loaded on-demand) - Full skill content with workflows and code examples
3. Level 3: Resources (loaded as needed) - Additional files, scripts, and reference materials

This progressive disclosure pattern ensures only relevant content occupies the context window at any given time.

New Functions

Get-PSAISkillFrontmatter

Scans a skills directory for SKILL.md files and extracts YAML frontmatter metadata:

# Get all skills as JSON
Get-PSAISkillFrontmatter -SkillsRoot "./skills"

# Get skills as PowerShell objects
Get-PSAISkillFrontmatter -SkillsRoot "./skills" -AsPSCustomObject

Read-PSAISkill

Reads the complete content of a skill file on-demand:

$skills = Get-PSAISkillFrontmatter -SkillsRoot "./skills" -AsPSCustomObject
$readSkill = $skills | Where-Object { $_.name -eq "Read File" }
Read-PSAISkill -Fullname $readSkill.fullname

Usage Example

Creating a skills-enabled agent:

$instructions = @"
You are a PowerShell Skills AI Assistant.
Use Read-PSAISkill to access skill content when needed.
Available skills: $(Get-PSAISkillFrontmatter -SkillsRoot "./skills" -Compress)
"@

$agent = New-Agent `
    -Tools @('Invoke-Expression', 'Read-PSAISkill') `
    -Instructions $instructions `
    -Name 'PSSkillsAgent'

# Use the agent
$agent | Get-AgentResponse "How do I read a file in PowerShell?"

What's Included

Core Implementation

• ✅ Two new functions fully integrated into PSAI module
• ✅ Exports added to PSAI.psd1 manifest
• ✅ Module imports added to PSAI.psm1

Testing

• ✅ 11 new comprehensive tests (all passing)
• ✅ Total: 197 tests pass, 0 failures
• ✅ Full coverage for both new functions

Sample Skills

Three example skills demonstrating proper structure:

• read-file - File reading operations
• write-file - File writing operations
• process-management - Process information and management

Documentation

• ✅ Main README.md updated with PSAI Skills section
• ✅ Comprehensive skills/README.md with architecture guide and best practices
• ✅ Example script (Use-PSAISkills.ps1) with complete usage patterns
• ✅ Implementation summary document (SKILLS_IMPLEMENTATION.md)

Skill Structure

Each skill is a directory containing a SKILL.md file with YAML frontmatter:

---
name: Your Skill Name
description: What this skill does and when to use it
---

# Your Skill Name

## Quick start
[Step-by-step guidance with code examples]

## Best practices
[Tips and recommendations]

Benefits

• Progressive Disclosure: Only loads content as needed, saving context
• Modular Design: Easy to add, remove, and share skills
• Reusable: Skills can be used across multiple agents
• Discoverable: Metadata makes skills easily findable
• Extensible: Clear pattern for creating custom skills

References

• Anthropic Claude Skills Documentation
• Anthropic Skills GitHub Repository
• Spike implementation: spikes/PowerShell-Skills/PSSkills.ps1

Breaking Changes

None. This PR maintains full backward compatibility with existing PSAI functionality.

Files Changed

• New Functions: Public/Get-PSAISkillFrontmatter.ps1, Public/Read-PSAISkill.ps1
• New Tests: __tests__/Get-PSAISkillFrontmatter.tests.ps1, __tests__/Read-PSAISkill.tests.ps1
• Example: examples/Use-PSAISkills.ps1
• Skills: 3 sample skills in skills/public/
• Documentation: Updated README.md, new skills/README.md, SKILLS_IMPLEMENTATION.md
• Module: Updated PSAI.psm1 and PSAI.psd1

Total: 13 files added/modified, 990 lines added

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Implement Anthropic Claude Skills PowerShell port into PSAI</issue_title>
<issue_description>It was pretty straightforward. Doing dir listings to get files.

The Anthropic Claude Skills. You open the markdown file and return the frontmatter. I do that and parse it with PowerShell. I set that up with New-Agent -Instructions and add more instructions so AI model can tell New-Agent what directory and md file should then be fully loaded in the context - worked like a charm.

Similar with Anthropic Claude Skills. They open the markdown file and return the frontmatter. I do that and parse it with PowerShell. I set that up with New-Agent -Instructions and add more instructions so AI model can tell New-Agent what directory and md file should then be fully loaded in the context - worked like a charm.

Expected Output

Review the "Reference links" and other internet sources about Anthropic Claude skills

• Review the current implementation of PSAI
• in spikes\PowerShell-Skills\PSSkills.ps1
• Skills are in spikes\PowerShell-Skills\skills

Reference links

Anthropic Claude Skills links:

• Agent Skills Overview - https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview
• GitHub Repository - https://github.com/anthropics/skills</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #109

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.