Implement Anthropic Claude Skills PowerShell port into PSAI

PSAI.psd1

@@ -39,6 +39,8 @@ PSAI brings OpenAI ChatGPT to PowerShell, leveraging advanced AI capabilities in
         'New-Agent'
         'Get-AgentResponse'
         'Invoke-InteractiveCLI'
+        'Get-PSAISkillFrontmatter'
+        'Read-PSAISkill'
         'Add-OAIVectorStore'
         'Clear-OAIAllItems'
         'Clear-OAIAssistants'

PSAI.psm1

@@ -18,6 +18,8 @@
 . $PSScriptRoot/Public/New-Agent.ps1
 . $PSScriptRoot/Public/Get-AgentResponse.ps1
 . $PSScriptRoot/Public/Invoke-InteractiveCLI.ps1
+. $PSScriptRoot/Public/Get-PSAISkillFrontmatter.ps1
+. $PSScriptRoot/Public/Read-PSAISkill.ps1
 . $PSScriptRoot/Public/Add-OAIVectorStore.ps1
 . $PSScriptRoot/Public/Clear-OAIAllItems.ps1
 . $PSScriptRoot/Public/Clear-OAIAssistants.ps1

Public/Get-PSAISkillFrontmatter.ps1

@@ -0,0 +1,96 @@
+<#
+.SYNOPSIS
+Retrieves skill metadata (name and description) from SKILL.md files in a skills directory.
+
+.DESCRIPTION
+The Get-PSAISkillFrontmatter function scans a directory for SKILL.md files and extracts
+their YAML frontmatter metadata. This implements the Anthropic Claude Skills pattern where
+skills are discovered via their metadata (Level 1 loading).
+
+Each SKILL.md file should have YAML frontmatter with 'name' and 'description' fields:
+---
+name: Skill Name
+description: What this skill does and when to use it
+---
+
+.PARAMETER SkillsRoot
+The root directory containing skill subdirectories. Defaults to "./skills".
+
+.PARAMETER AsPSCustomObject
+Returns results as PowerShell custom objects instead of JSON.
+
+.PARAMETER Compress
+When returning JSON, compress the output to a single line.
+
+.EXAMPLE
+PS> Get-PSAISkillFrontmatter
+Returns JSON array of all skills found in ./skills directory.
+
+.EXAMPLE
+PS> Get-PSAISkillFrontmatter -SkillsRoot "C:\MySkills" -AsPSCustomObject
+Returns PowerShell objects for all skills in the specified directory.
+
+.NOTES
+This function implements the Anthropic Claude Skills architecture pattern for PowerShell,
+enabling progressive disclosure where skill metadata is loaded first, and full skill
+content is loaded on-demand using Read-PSAISkill.
+#>
+function Get-PSAISkillFrontmatter {
+    [CmdletBinding()]
+    param(
+        [Parameter()]
+        [string]$SkillsRoot = "./skills",
+
+        [Parameter()]
+        [switch]$AsPSCustomObject,
+
+        [Parameter()]
+        [switch]$Compress
+    )
+
+    $skillFiles = Get-ChildItem -Path $SkillsRoot -Recurse -Filter "SKILL.md" -ErrorAction SilentlyContinue
+    $results = @()
+
+    foreach ($file in $skillFiles) {
+        $lines = Get-Content $file.FullName
+        $start = $lines.IndexOf('---')
+
+        if ($start -ge 0) {
+            # Find the closing '---' after $start
+            $end = -1
+            for ($i = $start + 1; $i -lt $lines.Count; $i++) {
+                if ($lines[$i] -eq '---') {
+                    $end = $i
+                    break
+                }
+            }
+
+            if ($end -gt $start) {
+                $frontmatter = $lines[$start..$end]
+                $name = $null
+                $description = $null
+
+                foreach ($line in $frontmatter) {
+                    if ($line -match '^name:\s*(.+)$') {
+                        $name = $matches[1].Trim()
+                    }
+                    if ($line -match '^description:\s*(.+)$') {
+                        $description = $matches[1].Trim()
+                    }
+                }
+
+                $results += [PSCustomObject]@{
+                    fullname    = $file.FullName
+                    name        = $name
+                    description = $description
+                }
+            }
+        }
+    }
+
+    if ($AsPSCustomObject) {
+        return $results
+    }
+
+    return $results | ConvertTo-Json -Depth 3 -Compress:$Compress
+}

Public/Read-PSAISkill.ps1

@@ -0,0 +1,46 @@
+<#
+.SYNOPSIS
+Reads the complete content of a skill file.
+
+.DESCRIPTION
+The Read-PSAISkill function reads the entire content of a SKILL.md file (or any file)
+and returns it as a single string. This implements Level 2 loading in the Anthropic 
+Claude Skills pattern, where the full skill instructions are loaded on-demand when
+the AI agent determines a skill is needed.
+
+This function is designed to be called by an AI agent when it needs detailed instructions
+from a skill file. The file path is typically obtained from Get-PSAISkillFrontmatter.
+
+.PARAMETER Fullname
+The full path to the skill file to read. This is typically a SKILL.md file path from
+the Get-PSAISkillFrontmatter output.
+
+.EXAMPLE
+PS> Read-PSAISkill -Fullname "C:\skills\pdf-processing\SKILL.md"
+Returns the complete content of the PDF processing skill file.
+
+.EXAMPLE
+PS> $skills = Get-PSAISkillFrontmatter -AsPSCustomObject
+PS> $pdfSkill = $skills | Where-Object { $_.name -eq "PDF Processing" }
+PS> Read-PSAISkill -Fullname $pdfSkill.fullname
+Discovers and reads a specific skill file.
+
+.NOTES
+This function implements the Anthropic Claude Skills architecture pattern for PowerShell.
+It should only be used to read skill files (SKILL.md) or related resources, not arbitrary
+files. The AI agent's instructions should enforce this constraint.
+#>
+function Read-PSAISkill {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$Fullname
+    )
+
+    if (-not (Test-Path -Path $Fullname)) {
+        Write-Error "File not found: $Fullname"
+        return
+    }
+
+    Get-Content -Path $Fullname -Raw
+}

README.md

@@ -111,6 +111,92 @@ This command will recursively list all files in the specified directory and its
 
 Run either of these commands in PowerShell to output all files in a directory.
 
+## PSAI Skills
+
+**PSAI Skills** bring the Anthropic Claude Skills architecture pattern to PowerShell, enabling modular, reusable capabilities that extend AI agent functionality with domain-specific expertise. Skills use progressive disclosure to load only the information needed at each stage, making agents more efficient and focused.
+
+### What are Skills?
+
+Skills are filesystem-based resources that provide AI agents with:
+- **Domain-specific workflows** and best practices
+- **On-demand loading** (progressive disclosure pattern)
+- **Structured guidance** through YAML frontmatter and markdown content
+
+### Three-Level Loading Architecture
+
+Skills implement a three-level loading pattern inspired by Anthropic Claude:
+
+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
+
+### Quick Start with Skills
+
+Discover available skills:
+
+```powershell
+# Get all skills as JSON
+Get-PSAISkillFrontmatter -SkillsRoot "./skills"
+
+# Get skills as PowerShell objects
+Get-PSAISkillFrontmatter -SkillsRoot "./skills" -AsPSCustomObject
+```
+
+Read full skill content:
+
+```powershell
+$skills = Get-PSAISkillFrontmatter -SkillsRoot "./skills" -AsPSCustomObject
+$readSkill = $skills | Where-Object { $_.name -eq "Read File" }
+Read-PSAISkill -Fullname $readSkill.fullname
+```
+
+### Creating a Skills-Enabled Agent
+
+```powershell
+$instructions = @"
+You are a PowerShell Skills AI Assistant. 
+
+When a user provides a request, analyze it to determine which skills are relevant.
+
+**ONLY USE** Read-PSAISkill to read SKILL.md files. 
+
+You have access to these skills:
+$(Get-PSAISkillFrontmatter -SkillsRoot "./skills" -Compress)
+"@
+
+$tools = @('Invoke-Expression', 'Read-PSAISkill')
+
+$agent = New-Agent -Tools $tools -Instructions $instructions -Name 'PSSkillsAgent'
+
+# Use the agent
+$agent | Get-AgentResponse "How do I read a file in PowerShell?"
+```
+
+### Creating Custom Skills
+
+Each skill is a directory containing a `SKILL.md` file with YAML frontmatter:
+
+```markdown
+---
+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]
+```
+
+For more information, see the [Skills README](skills/README.md) and the example script [Use-PSAISkills.ps1](examples/Use-PSAISkills.ps1).
+
+### References
+
+- [Anthropic Claude Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
+- [Anthropic Skills GitHub Repository](https://github.com/anthropics/skills)
 
 ## What Are Autonomous Agents?