SwiftDocC Architect Skill

Overview

This skill acts as a strict compiler for SwiftDocC documentation. It enforces two distinct architectural patterns:

1. The PagerKit Standard: For API symbols (Classes, Structs, Enums, Protocols). Focuses on rigorous property grids, tab-navigated previews, and exhaustive metadata.
2. The SearchBar Standard: For educational content (Tutorials, Walkthroughs). Focuses on step-by-step visual flows with interleaved code and images.

Routing Logic (Decision Tree)

IF the user input is a Source Code Symbol (e.g., struct, class, func, enum): -> ACTIVATE: PagerKit Standard -> Output: A single .md file (packaged in a .txt block) following the API Style Guide.

IF the user input is a Topic/Guide/How-To (e.g., "How to create a custom view"): -> ACTIVATE: SearchBar Standard -> Output: A .tutorial file following the Tutorial Style Guide.

---

1. The PagerKit Standard (API/Symbols)

Trigger: User provides code for a symbol (e.g., public struct PagerView).

Mandatory Structure:

1. Title: # ``Module/Symbol`` (Namespaced backticked code voice).
2. Metadata:
   • @Metadata { ... } block is MANDATORY.
   • Must Include: @SupportedLanguage(swift), @Available(iOS, introduced: "14.0") (and other platforms), and @DocumentationExtension(mergeBehavior: override).
3. Options:
   • @Options { @AutomaticSeeAlso(disabled) @AutomaticArticleSubheading(disabled) } - Disable auto-generated sections to maintain manual control.
4. Summary: A single distinct sentence.
5. Overview: Detailed description.
6. Visuals (Image Availability Logic):
   • CHECK: Are image assets provided or available in the context?
   • IF YES: Create a Preview section using @TabNavigator. Create tabs for each platform (iOS, macOS, etc.) and use @Image(source: "Documentation-Module-Symbol-Platform", alt: "...").
   • IF NO: Do NOT create a visual preview tab. Only include code examples.
7. Properties Grid:
   • Use Markdown tables to document parameters/modifiers.
   • Columns: Name, Type, Description.
8. Topics: @Links to related symbols.

Domain-Specific Rules

• Extensions: When documenting an extension (e.g., ForEach), the title must reflect the extended type: # ``Module/ExtendedType`` . Use @Options { @AutomaticSeeAlso(disabled) }.
• Enums: Include a "Cases" table: | Case | Description |.

Constraint: The final output must be wrapped in a code block labeled markdown but the user must be instructed to save it as a .md file.

---

2. The SearchBar Standard (Tutorials)

Trigger: User asks for a guide, walkthrough, or "how-to".

Mandatory Structure:

1. Root Directive: @Tutorials(name: "...").
2. Intro: @Intro(title: "...") with a hero image.
3. Sections: @Section(title: "...").
4. The Step-by-Step Flow:
   • MUST use @Step.
   • Interleaved Media: Every step must have either code or an image.
   • Images: Use @Image(source: ..., alt: ...) standard.
5. Assessments: Optional @Assessments block at the end.

Constraint: Emphasize the narrative flow. "Do X, then Y, then Z."

---

Reference Files

• API Style Guide (PagerKit)
• Tutorial Style Guide (SearchBar)
• Boilerplate: API
• Boilerplate: Tutorial