From a21719f43b71ea50c23af851da63d7da3907f1f2 Mon Sep 17 00:00:00 2001
From: Alberto Farah Blair <alberto.farah.b@gmail.com>
Date: Wed, 29 Apr 2026 16:00:51 +0000
Subject: [PATCH] Add SKILL.md for AI agents

- Add comprehensive SKILL.md file for AI agents using sigmf-python
- Include core operations, advanced features, and common workflows
- Provide examples for reading RF signals, format conversion, and analysis
- Include error handling and best practices
- Meets requirements: <500 lines, <5000 tokens

Resolves #139
---
 docs/SKILL.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 162 insertions(+)
 create mode 100644 docs/SKILL.md

diff --git a/docs/SKILL.md b/docs/SKILL.md
new file mode 100644
index 0000000..7835da8
--- /dev/null
+++ b/docs/SKILL.md
@@ -0,0 +1,162 @@
+# SKILL.md - SigMF Python
+
+## Description
+SigMF Python library skill for AI agents to work with Signal Metadata Format recordings. This skill enables AI agents to read, write, and process RF time series data using the SigMF standard.
+
+## Use Cases
+- Reading and analyzing RF signal recordings
+- Converting between different RF data formats
+- Processing and validating SigMF metadata
+- Creating automated RF signal analysis workflows
+- Generating reports from RF signal data
+
+## Setup
+```python
+import sigmf
+```
+
+## Core Operations
+
+### Read SigMF Recordings
+```python
+# Read SigMF recording
+meta = sigmf.fromfile("recording.sigmf-meta")
+samples = meta[0:1024]  # Get first 1024 samples
+sample_rate = meta.sample_rate  # Get sample rate
+
+# Read other formats as SigMF
+meta = sigmf.fromfile("recording.wav")   # WAV files
+meta = sigmf.fromfile("recording.cdif")  # BLUE/Platinum files  
+meta = sigmf.fromfile("recording.xml")   # Signal Hound Spike files
+```
+
+### Signal Analysis
+```python
+# Basic signal properties
+sample_rate = meta.sample_rate
+center_freq = meta.core:frequency
+datetime = meta.core:datetime
+annotation = meta.annotations[0] if meta.annotations else None
+
+# Process signal data
+samples = meta.read_samples(start_index=0, count=1024)
+```
+
+### Format Conversion
+```python
+# Convert between RF formats
+# WAV to SigMF
+sigmf.fromfile("input.wav").tofile("output.sigmf-meta")
+
+# CDIF to SigMF  
+sigmf.fromfile("input.cdif").tofile("output.sigmf-meta")
+
+# Signal Hound to SigMF
+sigmf.fromfile("input.xml").tofile("output.sigmf-meta")
+```
+
+### Metadata Operations
+```python
+# Access metadata
+global_fields = meta.global_fields
+global_keys = list(meta.global_fields.keys())
+
+# Validate SigMF files
+sigmf.validate.validate_file("recording.sigmf-meta")
+```
+
+## Advanced Features
+
+### Signal Generation
+```python
+# Generate test signals
+from sigmf import siggen
+
+# Create sine wave
+samples = siggen.sinewave(frequency=1e6, sample_rate=10e6, duration=1.0)
+
+# Create noise
+samples = siggen.white_noise(sample_rate=10e6, num_samples=1024)
+```
+
+### Archive Operations
+```python
+# Handle SigMF archives
+archive = sigmf.Archive("archive.sigmf-meta")
+archive.add_file("recording1.sigmf-meta")
+archive.add_file("recording2.sigmf-meta")
+archive.write("combined.sigmf-meta")
+```
+
+## Best Practices
+1. Always validate SigMF files before processing
+2. Use appropriate sample rates for your analysis
+3. Include proper metadata annotations
+4. Handle large files in chunks when memory is constrained
+5. Use proper units for frequency (Hz) and time (seconds)
+
+## Common Tasks
+
+### RF Signal Analysis Workflow
+```python
+def analyze_rf_signal(file_path):
+    """Complete RF signal analysis workflow"""
+    # Load signal
+    meta = sigmf.fromfile(file_path)
+    
+    # Get basic properties
+    sample_rate = meta.sample_rate
+    center_freq = meta.core.get('frequency', 0)
+    
+    # Read samples
+    samples = meta.read_samples(count=1024)
+    
+    # Basic analysis
+    max_amplitude = max(abs(samples))
+    avg_amplitude = sum(abs(samples)) / len(samples)
+    
+    return {
+        'sample_rate': sample_rate,
+        'center_frequency': center_freq,
+        'max_amplitude': max_amplitude,
+        'avg_amplitude': avg_amplitude
+    }
+```
+
+### Batch Processing
+```python
+def batch_convert_rf_files(input_dir, output_dir, input_format='wav'):
+    """Convert multiple RF files to SigMF format"""
+    import glob
+    
+    pattern = f"{input_dir}/*.{input_format}"
+    for input_file in glob.glob(pattern):
+        output_file = input_file.replace(input_format, 'sigmf-meta')
+        meta = sigmf.fromfile(input_file)
+        meta.tofile(output_file)
+        print(f"Converted {input_file} to {output_file}")
+```
+
+## Error Handling
+```python
+try:
+    meta = sigmf.fromfile("signal.sigmf-meta")
+    samples = meta.read_samples()
+except sigmf.SigMFError as e:
+    print(f"SigMF error: {e}")
+except FileNotFoundError:
+    print("File not found")
+except Exception as e:
+    print(f"Unexpected error: {e}")
+```
+
+## References
+- [SigMF Specification](https://sigmf.org/)
+- [SigMF Python Documentation](https://sigmf.readthedocs.io/)
+- [Signal Metadata Format](https://github.com/sigmf/SigMF)
+
+## Notes
+- Compatible with Python 3.7-3.14
+- Licensed under GNU Lesser GPL v3
+- Supports various RF recording formats
+- Includes validation and conversion utilities
\ No newline at end of file