Implement Agent Skills discovery with progressive disclosure (#182)

Author: Copilot

.gitignore

@@ -2,3 +2,6 @@
 coding-context
 coding-context-cli
 *.test
+
+# Test workspaces
+examples/test-workspace/

examples/agents/skills/README.md

@@ -0,0 +1,98 @@
+# Agent Skills Examples
+
+This directory contains example skills that demonstrate the Agent Skills format.
+
+## What are Agent Skills?
+
+Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. Each skill is a folder containing a `SKILL.md` file with metadata and instructions.
+
+## Skills in this directory
+
+### pdf-processing
+
+Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs.
+
+```bash
+coding-context -C examples/test-workspace your-task
+```
+
+### data-analysis
+
+Analyze datasets, generate charts, and create summary reports for CSV, Excel, and other tabular data formats.
+
+## Skill Structure
+
+Each skill folder contains:
+
+```
+skill-name/
+├── SKILL.md          # Required: instructions + metadata
+├── scripts/          # Optional: executable code
+├── references/       # Optional: documentation
+└── assets/           # Optional: templates, resources
+```
+
+## Required Frontmatter
+
+The `SKILL.md` file must contain YAML frontmatter with at least:
+
+- `name`: A unique identifier (1-64 characters, lowercase alphanumeric and hyphens only)
+- `description`: What the skill does and when to use it (1-1024 characters)
+
+Example:
+
+```yaml
+---
+name: pdf-processing
+description: Extract text and tables from PDF files, fill forms, merge documents.
+---
+```
+
+## Optional Frontmatter
+
+- `license`: License name or reference
+- `compatibility`: Environment requirements
+- `metadata`: Additional key-value pairs
+- `allowed-tools`: Pre-approved tools (experimental)
+
+## Progressive Disclosure
+
+Skills use progressive disclosure for efficient context management:
+
+1. **Discovery**: At startup, only the `name` and `description` are loaded
+2. **Activation**: When relevant, the agent loads the full `SKILL.md` content
+3. **Execution**: Scripts and resources are loaded as needed
+
+## Selectors
+
+Skills can be filtered using selectors in their frontmatter, just like rules:
+
+```yaml
+---
+name: dev-skill
+description: A skill for development environments
+env: development
+---
+```
+
+Then use with:
+
+```bash
+coding-context -s env=development your-task
+```
+
+Skills without the selector key are included by default (OR logic).
+
+## Testing
+
+To see skills in action:
+
+```bash
+# Navigate to the test workspace
+cd examples/test-workspace
+
+# Run a simple task and see discovered skills
+coding-context simple
+```
+
+The output will include an `<available_skills>` section with skill metadata.

examples/agents/skills/data-analysis/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: data-analysis
+description: Analyze datasets, generate charts, and create summary reports. Use when the user needs to work with CSV, Excel, or other tabular data formats for analysis or visualization.
+---
+
+# Data Analysis
+
+## When to use this skill
+Use this skill when the user needs to:
+- Analyze CSV or Excel files
+- Generate charts and visualizations
+- Calculate statistics and summaries
+- Clean and transform data
+
+## How to analyze data
+1. Use pandas for data analysis:
+   ```python
+   import pandas as pd
+   df = pd.read_csv('data.csv')
+   summary = df.describe()
+   ```
+
+## How to create visualizations
+1. Use matplotlib or seaborn for charts:
+   ```python
+   import matplotlib.pyplot as plt
+   df.plot(kind='bar')
+   plt.savefig('chart.png')
+   ```

examples/agents/skills/pdf-processing/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: pdf-processing
+description: Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
+license: Apache-2.0
+metadata:
+  author: example-org
+  version: "1.0"
+---
+
+# PDF Processing
+
+## When to use this skill
+Use this skill when the user needs to work with PDF files, including:
+- Extracting text or tables from PDF documents
+- Filling out PDF forms programmatically
+- Merging multiple PDF files into one
+- Splitting PDF files into separate documents
+
+## How to extract text
+1. Use pdfplumber for text extraction:
+   ```python
+   import pdfplumber
+   with pdfplumber.open('document.pdf') as pdf:
+       text = pdf.pages[0].extract_text()
+   ```
+
+## How to fill forms
+1. Use PyPDF2 to fill form fields:
+   ```python
+   from PyPDF2 import PdfReader, PdfWriter
+   reader = PdfReader('form.pdf')
+   writer = PdfWriter()
+   # Fill fields here
+   ```
+
+## How to merge documents
+See [the reference guide](references/REFERENCE.md) for details.

examples/agents/skills/pdf-processing/references/REFERENCE.md

@@ -0,0 +1,76 @@
+# PDF Processing Reference Guide
+
+## Supported Libraries
+
+### pdfplumber
+- Text extraction
+- Table detection and extraction
+- Image extraction
+- Comprehensive metadata access
+
+### PyPDF2
+- Form field manipulation
+- PDF merging and splitting
+- Encryption and decryption
+- Rotation and cropping
+
+## Detailed Examples
+
+### Extract Tables
+
+```python
+import pdfplumber
+
+with pdfplumber.open('document.pdf') as pdf:
+    for page in pdf.pages:
+        tables = page.extract_tables()
+        for table in tables:
+            # Process table data
+            print(table)
+```
+
+### Fill PDF Forms
+
+```python
+from PyPDF2 import PdfReader, PdfWriter
+
+reader = PdfReader('form.pdf')
+writer = PdfWriter()
+
+# Get the first page
+page = reader.pages[0]
+
+# Update form fields
+writer.add_page(page)
+writer.update_page_form_field_values(
+    writer.pages[0],
+    {"field_name": "value"}
+)
+
+# Save the filled form
+with open('filled_form.pdf', 'wb') as output_file:
+    writer.write(output_file)
+```
+
+### Merge PDFs
+
+```python
+from PyPDF2 import PdfMerger
+
+merger = PdfMerger()
+
+# Add multiple PDFs
+merger.append('file1.pdf')
+merger.append('file2.pdf')
+merger.append('file3.pdf')
+
+# Write merged PDF
+merger.write('merged.pdf')
+merger.close()
+```
+
+## Performance Considerations
+
+- For large PDFs, process pages incrementally
+- Use caching for frequently accessed documents
+- Consider parallel processing for batch operations

examples/agents/skills/pdf-processing/scripts/extract.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""
+Extract text from a PDF file.
+
+Usage:
+    extract.py <input_pdf> [output_txt]
+"""
+
+import sys
+import pdfplumber
+
+def extract_text(pdf_path, output_path=None):
+    """Extract text from all pages of a PDF."""
+    text_content = []
+    
+    try:
+        with pdfplumber.open(pdf_path) as pdf:
+            for i, page in enumerate(pdf.pages, 1):
+                print(f"Processing page {i}/{len(pdf.pages)}...", file=sys.stderr)
+                text = page.extract_text()
+                if text:
+                    text_content.append(f"--- Page {i} ---\n{text}\n")
+        
+        result = '\n'.join(text_content)
+        
+        if output_path:
+            with open(output_path, 'w', encoding='utf-8') as f:
+                f.write(result)
+            print(f"Text extracted to {output_path}", file=sys.stderr)
+        else:
+            print(result)
+            
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        print(__doc__, file=sys.stderr)
+        sys.exit(1)
+    
+    input_pdf = sys.argv[1]
+    output_txt = sys.argv[2] if len(sys.argv) > 2 else None
+    
+    extract_text(input_pdf, output_txt)

main.go

@@ -166,6 +166,17 @@ func main() {
 			fmt.Println("---")
 		}
 
+		// Output available skills metadata (progressive disclosure)
+		if len(result.Skills.Skills) > 0 {
+			skillsXML, err := result.Skills.AsXML()
+			if err != nil {
+				logger.Error("Failed to encode skills as XML", "error", err)
+				os.Exit(1)
+			}
+			fmt.Println(skillsXML)
+			fmt.Println()
+		}
+
 		// Output the combined prompt (rules + task)
 		fmt.Println(result.Prompt)
 	}