Skill Maintainer

Skill Maintainer — Documentation Ingestion & Skill Updater

Process new Apple developer documentation and route extracted knowledge into the correct skill files.

Workflow

Step 1: Classify Incoming Documentation

Read each uploaded document and classify it by answering:

If a document spans multiple skills (e.g., "SwiftUI-WebKit-Integration" touches both swiftui-core and a potential swiftui-webkit skill), extract relevant portions into each.

Step 2: Extract Actionable Content

From each document, extract exactly these categories:

Patterns — Working, copy-pasteable code blocks with:

• The API call or view/modifier being demonstrated
• Required imports
• Minimum OS version (if not the latest)
• Inline comments on non-obvious behavior

Constraints — Things an LLM will get wrong:

• Deprecated APIs that the new one replaces (❌ old → ✅ new)
• Parameters that changed names or types
• Behaviors that differ from what the name implies
• Common mistakes visible in the doc's "Best Practices" or notes

Decision Logic — When to use which approach:

• If the doc presents multiple approaches (e.g., .background vs .foreground(.dynamic) intent modes), capture the decision tree
• If the doc distinguishes platform availability, capture the conditional

References — Source links:

• Apple Developer Documentation URLs
• WWDC session links with year

Step 3: Diff Against Existing Skills

Before writing, read the target skill file(s) and check:

1. Duplicate patterns — Does this pattern already exist? If yes, check if the new version supersedes it
2. Contradictions — Does the new doc contradict existing constraints? If yes, the new doc wins (it's more recent)
3. Gaps — Does the existing skill lack coverage for this area? If yes, add a new section
4. Deprecations — Does the new doc make any existing patterns obsolete? If yes, move old pattern to constraints with ❌

Step 4: Update Target Skills

Apply changes following the target skill's internal structure. Every skill should maintain these sections (add if missing):

## Critical Constraints        ← ❌ DO NOT / ✅ INSTEAD rules
## Decision Tree               ← When to use what
## Verified Patterns           ← Working code blocks
  ### Pattern: [Name]          ← Each with OS version tag
## Common Mistakes & Fixes     ← Table format
## References                  ← Apple doc + WWDC links

Formatting rules for inserted content:

• Tag every pattern with version: <!-- Verified: macOS 26, Swift 6.2, Xcode 26 -->
• Prefix new constraints with the source: <!-- Source: SwiftUI-New-Toolbar-Features.md -->
• Keep code blocks self-contained (include imports)
• Prefer short inline comments over paragraph explanations

Step 5: Handle New Skills

If the document covers a framework with no existing skill, create one:

1. Use the Skill Registry to confirm no existing skill covers it
2. Create SKILL.md with proper frontmatter
3. Follow the standard section structure above
4. If content exceeds ~400 lines, split into SKILL.md (core workflow + index) and references/ files
5. Register the new skill in the registry

Step 6: Report Changes

After processing, output a summary:

## Ingestion Report

### Documents Processed
- [filename] → [target skill(s)]

### Changes Made
| Skill | Action | Details |
|-------|--------|---------|
| swift-lang | UPDATED | Added @concurrent attribute pattern, Swift 6.2 default MainActor isolation |
| liquid-glass | UPDATED | Added WidgetKit accented rendering mode |
| swiftui-webkit | CREATED | New skill — WebView/WebPage APIs from SwiftUI-WebKit-Integration.md |

### Deprecations Flagged
- `NavigationView` → `NavigationSplitView` (swiftui-core)
- `ObservableObject` → `@Observable` for macOS 14+ (swift-lang)

### Unresolved
- [any docs that didn't map cleanly — ask user for guidance]

Skill Registry

Map frameworks/topics to target skills. Update this when creating new skills.

Unmapped content: If a document doesn't fit any existing skill, flag it and ask the user whether to create a new skill or fold it into an existing one.

Classification Heuristics

Use these signals to auto-classify documents:

Quality Rules

When updating skills, enforce these standards:

1. No orphan code — Every code block must include required import statements
2. No version ambiguity — Every pattern tagged with minimum OS version
3. No stale deprecations — If adding a new way, mark the old way as ❌
4. No duplicates — Search existing skill before inserting; merge if similar
5. Constraints > Patterns — It's more valuable to tell the agent what NOT to do than to show one more example
6. Size budget — SKILL.md body stays under 500 lines; overflow goes to references/
7. Self-contained patterns — Each code block should compile independently if pasted into a fresh file with the right imports

Batch Processing

When processing multiple documents at once:

1. Read all documents first to build a complete picture
2. Group by target skill to minimize file edits
3. Process in dependency order: swift-lang first (language level), then frameworks
4. Deduplicate across documents (e.g., Liquid Glass appears in 4 docs — consolidate)
5. Generate a single unified ingestion report at the end