Skill: mneves75/healthkit-sync (version 1.0.0)

--- name: healthkit-sync description: iOS HealthKit data sync CLI commands and patterns. Use when working with healthsync CLI, fetching Apple Health data (steps, heart rate, sleep, workouts), pairing iOS devices over local network, or understanding the iOS Health Sync project architecture including mTLS certificate pinning, Keychain storage, and audit logging. license: Apache-2.0 compatibility: macOS with healthsync CLI installed (~/.healthsync/config.json) metadata: category: development platforms: ios,macos author: mneves --- # HealthKit Sync CLI Securely sync Apple HealthKit data from iPhone to Mac over local network using mTLS. ## When to Use This Skill - User asks about syncing health data from iPhone - User mentions `healthsync` CLI commands - User wants to fetch steps, heart rate, sleep, or workout data - User needs to pair a Mac with an iOS device - User asks about the iOS Health Sync project architecture - User mentions certificate pinning or mTLS patterns ## CLI Quick Reference ### Pairing Flow (First Time) ```bash # 1. Discover devices on local network healthsync discover # 2. On iOS app: tap "Share" to generate QR code, then "Copy" # 3. Scan QR from clipboard (Universal Clipboard) healthsync scan # Alternative: scan from image file healthsync scan --file ~/Desktop/qr.png ``` ### Fetching Health Data ```bash # Check connection status healthsync status # List enabled data types healthsync types # Fetch data as CSV (default) healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z --types steps # Fetch multiple types as JSON healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z \ --types steps,heartRate,sleepAnalysis --format json | jq # Pipe to file healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z \ --types steps > steps.csv ``` ### Available Health Data Types **Activity**: steps, distanceWalkingRunning, distanceCycling, activeEnergyBurned, basalEnergyBurned, exerciseTime, standHours, flightsClimbed, workouts **Heart**: heartRate, restingHeartRate, walkingHeartRateAverage, heartRateVariability **Vitals**: bloodPressureSystolic, bloodPressureDiastolic, bloodOxygen, respiratoryRate, bodyTemperature, vo2Max **Sleep**: sleepAnalysis, sleepInBed, sleepAsleep, sleepAwake, sleepREM, sleepCore, sleepDeep **Body**: weight, height, bodyMassIndex, bodyFatPercentage, leanBodyMass ## Configuration Config stored at `~/.healthsync/config.json` (permissions: 0600): ```json { "host": "192.168.1.x", "port": 8443, "fingerprint": "sha256-certificate-fingerprint" } ``` Token stored in macOS Keychain under service `org.mvneves.healthsync.cli`. ## Security Architecture ### Certificate Pinning The CLI validates server certificates by SHA256 fingerprint (TOFU model): 1. First pairing stores fingerprint from QR code 2. Subsequent connections verify fingerprint matches 3. Mismatch = connection rejected (MITM protection) ### Local Network Only Host validation restricts connections to: - `localhost`, `*.local` domains - Private IPv4: `192.168.*`, `10.*`, `172.16-31.*` - IPv6 loopback: `::1`, link-local: `fe80::` ### Keychain Storage Tokens never stored in config file - always in Keychain with: - `kSecAttrAccessibleWhenUnlocked` protection class - Service: `org.mvneves.healthsync.cli` - Account: `token-{host}` ## Project Structure ``` ai-health-sync-ios-clawdbot/ ├── iOS Health Sync App/ # Swift 6 iOS app │ ├── Services/Security/ # CertificateService, KeychainStore, PairingService │ ├── Services/HealthKit/ # HealthKitService, HealthSampleMapper │ ├── Services/Network/ # NetworkServer (TLS), HTTPTypes │ └── Services/Audit/ # AuditService (SwiftData) └── macOS/HealthSyncCLI/ # Swift Package CLI ``` ## Troubleshooting **"No devices found"**: - Ensure iOS app is running with sharing enabled - Both devices must be on same Wi-Fi network - Check firewall isn't blocking mDNS (port 5353) **"Pairing code expired"**: - Generate new QR code on iOS app (codes expire in 5 minutes) **"Certificate mismatch"**: - Delete `~/.healthsync/config.json` and re-pair - Server certificate may have been regenerated **"Connection refused"**: - iOS app server may not be running - Run `healthsync status --dry-run` to test without connecting ## See Also - [CLI Reference](references/CLI-REFERENCE.md) - Detailed command documentation - [Security Patterns](references/SECURITY.md) - mTLS and certificate pinning patterns - [Architecture](references/ARCHITECTURE.md) - iOS app architecture details

path: references/ARCHITECTURE.md
content: # Project Architecture

iOS Health Sync is a Swift 6 project for secure HealthKit data transfer.

## Repository Structure

```
ai-health-sync-ios-clawdbot/
├── iOS Health Sync App/              # Xcode project
│   ├── iOS Health Sync App/
│   │   ├── App/
│   │   │   ├── iOS_Health_Sync_AppApp.swift  # @main entry
│   │   │   └── AppState.swift                # @Observable state
│   │   ├── Core/
│   │   │   ├── Models/
│   │   │   │   ├── HealthDataType.swift      # Enum of health types
│   │   │   │   ├── PersistenceModels.swift   # SwiftData models
│   │   │   │   └── SchemaVersions.swift      # Migration schemas
│   │   │   ├── DTO/
│   │   │   │   └── HealthSampleDTO.swift     # Network transfer object
│   │   │   └── Utilities/
│   │   │       ├── DEREncoder.swift          # X.509 certificate builder
│   │   │       └── Loggers.swift             # os.Logger instances
│   │   ├── Features/
│   │   │   ├── ContentView.swift             # Main UI
│   │   │   ├── QRCodeView.swift              # Pairing QR display
│   │   │   ├── PrivacyPolicyView.swift       # Privacy disclosure
│   │   │   └── AboutView.swift               # App info
│   │   └── Services/
│   │       ├── HealthKit/
│   │       │   ├── HealthKitService.swift    # HealthKit queries
│   │       │   ├── HealthStoreProtocol.swift # Testability protocol
│   │       │   └── HealthSampleMapper.swift  # HKSample -> DTO
│   │       ├── Security/
│   │       │   ├── CertificateService.swift  # TLS cert generation
│   │       │   ├── KeychainStore.swift       # Secure storage
│   │       │   └── PairingService.swift      # Device pairing
│   │       ├── Network/
│   │       │   ├── NetworkServer.swift       # HTTPS server
│   │       │   └── HTTPTypes.swift           # Request/response types
│   │       └── Audit/
│   │           └── AuditService.swift        # Access logging
│   └── iOS Health Sync AppTests/
│       ├── DEREncoderTests.swift
│       ├── NetworkServerTests.swift
│       └── HealthKitServiceTests.swift
├── macOS/
│   └── HealthSyncCLI/                        # Swift Package
│       ├── Package.swift
│       ├── Sources/HealthSyncCLI/
│       │   └── main.swift                    # CLI implementation
│       └── Tests/HealthSyncCLITests/
│           └── HealthSyncCLITests.swift
└── DOCS/
    ├── GUIDELINES-REF/                       # Shared guidelines (symlink)
    └── CLAWDBOT-SKILL-PLAN.md
```

## Key Components

### iOS App

**AppState** (@Observable):
- Manages sharing state, paired clients, server lifecycle
- Holds references to services

**HealthKitService**:
- Requests HealthKit authorization
- Queries samples by type and date range
- Maps to DTO format

**NetworkServer**:
- NWListener with TLS configuration
- Routes: `/api/v1/pair`, `/api/v1/status`, `/api/v1/health/types`, `/api/v1/health/data`
- Uses SecIdentity for TLS

**CertificateService**:
- Generates self-signed ECDSA P-256 certificate
- Stores in Keychain
- Prefers Secure Enclave when available

**AuditService** (actor):
- Records all health data access
- SwiftData persistence
- 90-day retention with auto-purge

### macOS CLI

Single-file implementation with:
- Bonjour discovery (NWBrowser)
- QR code scanning (Vision framework)
- Certificate pinning (URLSessionDelegate)
- Keychain token storage

## Data Flow

### Pairing

```
iOS App                          macOS CLI
   │                                │
   ├─ Generate TLS cert ───────────►│
   ├─ Generate pairing code         │
   ├─ Display QR code               │
   │                                │
   │◄─────── User copies QR ────────┤
   │                                ├─ Parse QR payload
   │                                ├─ Validate host (local)
   │                                ├─ Validate expiration
   │◄──────── POST /pair ───────────┤
   ├─ Verify code                   │
   ├─ Generate token                │
   ├─ Record audit event            │
   ├──────── Return token ─────────►│
   │                                ├─ Store fingerprint
   │                                ├─ Store token (Keychain)
```

### Health Data Fetch

```
iOS App                          macOS CLI
   │                                │
   │◄───── POST /health/data ───────┤
   ├─ Verify Bearer token           │
   ├─ Query HealthKit               │
   ├─ Map to DTOs                   │
   ├─ Record audit event            │
   ├─────── Return samples ────────►│
   │                                ├─ Format as CSV/JSON
   │                                ├─ Output to stdout
```

## Key Patterns

### Protocol-Oriented Testing

```swift
protocol HealthStoreProtocol {
    func requestAuthorization(...) async throws
    func samples(for type: HealthDataType, ...) async throws -> [HealthSampleDTO]
}

// Production
class HealthKitService: HealthStoreProtocol { ... }

// Tests
class MockHealthStore: HealthStoreProtocol { ... }
```

### Actor for Audit

```swift
actor AuditService {
    // Thread-safe, no data races
    func record(eventType: String, details: [String: String]) async { ... }
}
```

### SwiftData Models

```swift
@Model
final class AuditEventRecord {
    var id: UUID
    var eventType: String
    var detailJSON: String
    var timestamp: Date

    // No deletedAt - audit records are immutable until retention expires
}
```

## Build & Test

```bash
# iOS App
xcodebuild -project "iOS Health Sync App/iOS Health Sync App.xcodeproj" \
  -scheme "iOS Health Sync App" build

# iOS Tests
xcodebuild test -scheme "iOS Health Sync App" \
  -destination 'platform=iOS Simulator,name=iPhone 16'

# macOS CLI
cd macOS/HealthSyncCLI
swift build
swift test  # 39 tests
```


path: references/CLI-REFERENCE.md
content: # HealthSync CLI Reference

Complete command reference for the `healthsync` CLI tool.

## Commands

### `healthsync discover [--auto-scan]`

Discover HealthSync devices on local network using Bonjour/mDNS.

**Options:**
- `--auto-scan` - Automatically scan QR from clipboard after discovery

**Output:**
```
Searching for HealthSync devices on local network...
Found 1 device(s):

  iPhone-Marcus
    Host: 192.168.1.42
    Port: 8443
```

**Notes:**
- Uses `_healthsync._tcp` Bonjour service type
- Timeout: 5 seconds for discovery, 3 seconds per service resolution
- Requires both devices on same Wi-Fi network

---

### `healthsync scan [--file <path>] [--name <name>] [--debug-pasteboard]`

Scan QR code and pair with iOS device.

**Options:**
- `--file <path>` - Scan QR from image file instead of clipboard
- `--name <name>` - Client name (default: Mac hostname)
- `--debug-pasteboard` - Print pasteboard types/sizes to debug Universal Clipboard issues

**Clipboard scanning priority:**
1. JSON text (Universal Clipboard - most reliable)
2. PNG image data
3. TIFF image data

**QR Payload format:**
```json
{
  "version": "1",
  "host": "192.168.1.42",
  "port": 8443,
  "code": "abc123",
  "expiresAt": "2026-01-07T12:05:00Z",
  "certificateFingerprint": "a1b2c3..."
}
```

**Validations:**
- Version must be "1"
- Host must be local network
- Code must not be expired
- Fingerprint stored for certificate pinning

---

### `healthsync pair --host <host> --port <port> --code <code> --fingerprint <fp> [--name <name>]`

Manual pairing (alternative to QR scanning).

**Options:**
- `--host` - iOS device IP address
- `--port` - Server port (usually 8443)
- `--code` - One-time pairing code
- `--fingerprint` - Certificate SHA256 fingerprint
- `--name` - Client name (default: Mac hostname)
- `--qr <json>` - Full QR payload as JSON string

---

### `healthsync status [--dry-run]`

Check connection status with paired iOS device.

**Options:**
- `--dry-run` - Print request without connecting

**Output:**
```
Status: ok
Device: iPhone-Marcus
Types: steps, heartRate, sleepAnalysis
```

**Response fields:**
- `status` - "ok" or error state
- `deviceName` - iOS device name
- `enabledTypes` - Health data types with permission
- `serverTime` - Server timestamp (for clock sync validation)

---

### `healthsync types [--dry-run]`

List enabled health data types.

**Output:**
```
steps, distanceWalkingRunning, heartRate, sleepAnalysis
```

---

### `healthsync fetch --start <iso> --end <iso> --types <list> [--format csv|json] [--dry-run]`

Fetch health data from iOS device.

**Required options:**
- `--start` - Start date (ISO 8601: `2026-01-01T00:00:00Z`)
- `--end` - End date (ISO 8601: `2026-12-31T23:59:59Z`)
- `--types` - Comma-separated list of types

**Optional:**
- `--format` - Output format: `csv` (default) or `json`
- `--dry-run` - Print request without fetching

**CSV output format:**
```csv
id;type;value;unit;startDate;endDate;sourceName
uuid;steps;1234;count;2026-01-07T08:00:00Z;2026-01-07T09:00:00Z;iPhone
```

**JSON output format:**
```json
{
  "status": "ok",
  "count": 42,
  "samples": [
    {
      "id": "uuid",
      "type": "steps",
      "value": 1234,
      "unit": "count",
      "startDate": "2026-01-07T08:00:00Z",
      "endDate": "2026-01-07T09:00:00Z",
      "sourceName": "iPhone",
      "metadata": null
    }
  ]
}
```

---

### `healthsync version`

Show version information.

**Output:**
```
HealthSyncCLI v1.0.0
Build: 2026-01-07
Platform: macOS (Version 15.3)

Copyright 2026 Marcus Neves
License: Apache-2.0
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Error (message printed to stderr) |

## Environment

- Config: `~/.healthsync/config.json` (0600 permissions)
- Token: macOS Keychain (`org.mvneves.healthsync.cli`)
- Logs: stderr (errors only)

## Build from Source

```bash
cd macOS/HealthSyncCLI
swift build
swift test  # 39 tests

# Run
.build/debug/healthsync --help
```


path: references/SECURITY.md
content: # Security Architecture

iOS Health Sync implements defense-in-depth security for health data transfer.

## Threat Model

- **Network eavesdropping** - Mitigated by TLS encryption
- **MITM attacks** - Mitigated by certificate pinning (TOFU)
- **Token theft** - Mitigated by Keychain storage
- **SSRF attacks** - Mitigated by local network host validation
- **Replay attacks** - Mitigated by time-limited pairing codes

## TLS Certificate Management

### iOS Server (CertificateService.swift)

Self-signed ECDSA P-256 certificate generated on first run:

```swift
struct TLSIdentity {
    let identity: SecIdentity
    let certificateData: Data
    let fingerprint: String  // SHA256 hex
}

// Keychain storage
private static let keyTag = "org.mvneves.healthsync.tlskey"
private static let certLabel = "HealthSync Local TLS"
```

**Key generation priority:**
1. Secure Enclave (if available) - hardware-backed
2. Software keychain - `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`

**Certificate fields:**
- Subject: `CN=HealthSync Local`
- Validity: 365 days from generation
- Algorithm: ECDSA with SHA256

### macOS Client (Certificate Pinning)

SHA256 fingerprint pinning via `URLSessionDelegate`:

```swift
final class PinnedSessionDelegate: NSObject, URLSessionDelegate {
    private let expectedFingerprint: String

    func urlSession(_ session: URLSession,
                    didReceive challenge: URLAuthenticationChallenge,
                    completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
        guard let trust = challenge.protectionSpace.serverTrust,
              let certificate = (SecTrustCopyCertificateChain(trust) as? [SecCertificate])?.first else {
            completionHandler(.cancelAuthenticationChallenge, nil)
            return
        }

        let data = SecCertificateCopyData(certificate) as Data
        let fingerprint = SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()

        if fingerprint == expectedFingerprint {
            completionHandler(.useCredential, URLCredential(trust: trust))
        } else {
            completionHandler(.cancelAuthenticationChallenge, nil)
        }
    }
}
```

## Token Storage

### iOS Server (SwiftData)

Tokens are **hashed** (SHA256) and stored in SwiftData, NOT Keychain:

```swift
// PairedDevice model (SwiftData)
@Model
final class PairedDevice {
    var tokenHash: String      // SHA256 of token (never plaintext)
    var expiresAt: Date
    var isActive: Bool
    var lastSeenAt: Date?
}

// Token hashing in PairingService
private static func hashToken(_ [REDACTED_SECRET]) -> String {
    let digest = SHA256.hash(data: Data(token.utf8))
    return digest.map { String(format: "%02x", $0) }.joined()
}
```

**Note:** Keychain is used for TLS private key storage (CertificateService), not tokens.

### macOS CLI (Keychain)

```swift
enum KeychainStore {
    private static let service = "org.mvneves.healthsync.cli"

    static func saveToken(_ [REDACTED_SECRET], for host: String) throws {
        let account = "token-\(host)"
        let addQuery: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: account,
            kSecValueData as String: tokenData,
            kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlocked
        ]
        // ...
    }
}
```

## Local Network Validation

Prevents SSRF by restricting hosts to local network:

```swift
func isLocalNetworkHost(_ host: String) -> Bool {
    // Allow: localhost, *.local domains
    // Allow: 192.168.*, 10.*, 172.16-31.*
    // Allow: ::1, fe80::*
    // Reject: all others
}
```

## Pairing Security

### QR Code Payload

```json
{
  "version": "1",
  "host": "192.168.1.42",
  "port": 8443,
  "code": "random-one-time-code",
  "expiresAt": "2026-01-07T12:05:00Z",
  "certificateFingerprint": "sha256-hex"
}
```

**Validations performed:**
1. Version check (forward compatibility)
2. Host must be local network
3. Code must not be expired (5 min TTL)
4. Fingerprint stored for future connections

### Token Exchange

```
POST /api/v1/pair
{
  "code": "one-time-code",
  "clientName": "MacBook Pro"
}

Response:
{
  "token": "bearer-token",
  "expiresAt": "2026-01-14T00:00:00Z"
}
```

## Audit Logging

All health data access is logged via AuditService:

```swift
actor AuditService {
    private static let retentionDays: Int = 90

    func record(eventType: String, details: [String: String]) async {
        // Persisted to SwiftData
        // Auto-purged after 90 days
    }
}
```

**Logged events:**
- `health.read` - Data fetch requests
- `health.types` - Type enumeration
- `pairing.request` - New pairing attempts
- `pairing.success` - Successful pairings

**Privacy rules:**
- No PII in logs
- Request IDs for correlation
- os.Logger with privacy annotations


path: TESTING.md
content: # Testing the HealthKit Sync Skill

This guide explains how to test the `healthkit-sync` Agent Skill in ClawdBot.

## Prerequisites

- ClawdBot CLI installed (`clawdbot --version`)
- ClawdBot gateway configured (`~/.clawdbot/clawdbot.json`)
- Active messaging provider (WhatsApp, Telegram, or Discord)

## Step 1: Link the Skill

ClawdBot loads skills from `~/.clawdbot/skills/`. Create a symlink to keep the skill in sync with the repo:

```bash
# Check if already linked
ls -la ~/.clawdbot/skills/healthkit-sync

# Create symlink (if not exists)
ln -sf "$(pwd)/skills/healthkit-sync" ~/.clawdbot/skills/healthkit-sync

# Verify
ls -la ~/.clawdbot/skills/healthkit-sync/
```

Expected output:
```
SKILL.md
references/
TESTING.md
```

## Step 2: Validate Skill Structure

Verify the skill follows the [Agent Skills specification](https://agentskills.io/specification):

```bash
# Check frontmatter
head -15 ~/.clawdbot/skills/healthkit-sync/SKILL.md
```

Expected frontmatter:
```yaml
---
name: healthkit-sync
description: iOS HealthKit data sync CLI commands and patterns...
license: Apache-2.0
compatibility: macOS with healthsync CLI installed
metadata:
  category: development
  platforms: ios,macos
  author: mneves
---
```

Validation checklist:
- [ ] `name` matches folder name (`healthkit-sync`)
- [ ] `name` is lowercase with hyphens only
- [ ] `description` is under 1024 characters
- [ ] SKILL.md is under 500 lines

```bash
# Check line count
wc -l ~/.clawdbot/skills/healthkit-sync/SKILL.md
# Should be < 500
```

## Step 3: Start a New Session

**Important:** Skills are snapshotted when a session starts. Changes require a new session.

### Option A: Restart Gateway

```bash
# Stop existing gateway (Ctrl+C or kill)
pkill -f "clawdbot gateway"

# Start fresh
clawdbot gateway --port 18789
```

### Option B: New Chat Session

Start a new conversation in your messaging app:
- **WhatsApp**: Send a message from an allowed number
- **Telegram**: Start fresh chat with your bot
- **Discord**: New channel or DM

## Step 4: Test Skill Activation

Send test messages that should trigger the skill. The skill activates when the agent detects relevant keywords in your message.

### Test Cases

| # | Message | Expected Response |
|---|---------|-------------------|
| 1 | "How do I sync health data from my iPhone to my Mac?" | CLI pairing flow (`healthsync discover`, `healthsync scan`) |
| 2 | "What commands does healthsync support?" | Full CLI reference with all commands |
| 3 | "How do I fetch my step count?" | `healthsync fetch` command with `--types steps` |
| 4 | "Explain the security architecture of iOS Health Sync" | mTLS, certificate pinning, Keychain storage details |
| 5 | "What's the project structure of ai-health-sync?" | Architecture overview with file paths |
| 6 | "How does certificate pinning work in healthsync?" | TOFU model, SHA256 fingerprint validation |
| 7 | "Troubleshoot: no devices found" | Troubleshooting steps (WiFi, mDNS, firewall) |

### Verification

A successful skill activation should include:
- Specific CLI commands (not generic advice)
- Correct paths (`~/.healthsync/config.json`)
- Accurate security details (SwiftData for iOS tokens, Keychain for macOS)
- References to project files when relevant

## Step 5: Test Progressive Disclosure

The skill uses progressive disclosure - references load on-demand:

1. **Initial query**: Only SKILL.md content loads (~100-150 lines)
2. **Detailed query**: Reference files load as needed

Test this by asking increasingly specific questions:

```
Message 1: "What is healthsync?"
→ Basic overview from SKILL.md

Message 2: "Show me the detailed CLI reference"
→ Loads references/CLI-REFERENCE.md

Message 3: "Explain the certificate pinning implementation"
→ Loads references/SECURITY.md

Message 4: "What's the full project architecture?"
→ Loads references/ARCHITECTURE.md
```

## Step 6: Debug Issues

### Skill Not Loading

```bash
# Check ClawdBot recognizes the skills directory
cat ~/.clawdbot/clawdbot.json | jq '.skills'

# Verify skill is readable
cat ~/.clawdbot/skills/healthkit-sync/SKILL.md | head -20

# Check for YAML parsing errors (must be valid YAML frontmatter)
```

### Skill Not Activating

The skill activates based on keyword matching in the `description` field. Ensure your message contains relevant terms:
- "healthsync", "health sync"
- "HealthKit", "health data"
- "iPhone", "iOS", "macOS"
- "pairing", "sync", "fetch"
- "certificate pinning", "mTLS"

### Wrong Information Returned

If the agent returns incorrect info, the skill may not be loading. Verify by asking:
```
"What is the config path for healthsync CLI?"
```

Correct answer: `~/.healthsync/config.json`
If wrong: Skill not loaded, check steps 1-3.

## Step 7: Monitor Logs

```bash
# Watch ClawdBot logs in real-time
tail -f ~/.clawdbot/logs/*.log

# Filter for skill-related messages
tail -f ~/.clawdbot/logs/*.log | grep -iE "(skill|healthkit)"
```

## Troubleshooting

| Issue | Cause | Solution |
|-------|-------|----------|
| Skill not found | Symlink broken | Re-run `ln -sf` command |
| Old content returned | Session cached | Start new session |
| YAML parse error | Invalid frontmatter | Check for tabs (use spaces) |
| References not loading | Wrong path syntax | Use `[text](path)` not `[See: file]` |
| Skill ignored | Description mismatch | Add more keywords to description |

## Updating the Skill

After making changes to the skill files:

1. **Git pull** (if changes from repo):
   ```bash
   git pull origin master
   ```

2. **Symlink auto-updates** (if linked correctly)

3. **Start new session** (required for changes to take effect)

## References

- [Agent Skills Specification](https://agentskills.io/specification)
- [ClawdBot Skills Documentation](https://docs.clawd.bot/tools/skills)
- [ClawdBot Skills Config](https://docs.clawd.bot/tools/skills-config)


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)