From 8bc7bcac35527f8edf54cbb183f104dd6b3eebc1 Mon Sep 17 00:00:00 2001
From: Michael <m.anderson23@icloud.com>
Date: Wed, 7 Jan 2026 20:13:36 -0600
Subject: [PATCH] Add reference documentation for skill authoring

---
 .../references/quality-checklist.md           | 38 ++++++++++
 .../references/skill-structure.md             | 65 ++++++++++++++++
 .../references/writing-guidelines.md          | 74 +++++++++++++++++++
 3 files changed, 177 insertions(+)
 create mode 100644 creating-swift-skills/references/quality-checklist.md
 create mode 100644 creating-swift-skills/references/skill-structure.md
 create mode 100644 creating-swift-skills/references/writing-guidelines.md

diff --git a/creating-swift-skills/references/quality-checklist.md b/creating-swift-skills/references/quality-checklist.md
new file mode 100644
index 0000000..5ad5f9d
--- /dev/null
+++ b/creating-swift-skills/references/quality-checklist.md
@@ -0,0 +1,38 @@
+# Quality checklist
+
+## Before submitting
+
+### Structure
+- [ ] SKILL.md has frontmatter with `name` and `description`
+- [ ] Has `## Overview` section
+- [ ] Has numbered `## Workflow` steps
+- [ ] Has `## Reference material` section (if references exist)
+- [ ] Reference files are single-topic focused
+
+### Content
+- [ ] Code examples are minimal and tested
+- [ ] No verbose explanations before code
+- [ ] No "Introduction" or "When to Use" sections
+- [ ] Experienced developer would find useful
+- [ ] Matches format of existing skills
+
+### Style
+- [ ] No emojis
+- [ ] kebab-case file and folder names
+- [ ] Tables used for comparisons
+- [ ] Short paragraphs
+
+### Code
+- [ ] Examples compile and run
+- [ ] Uses modern Swift syntax
+- [ ] Follows Swift API Design Guidelines
+- [ ] Copy-paste ready
+
+## Common issues
+
+| Issue | Fix |
+|-------|-----|
+| Too much preamble | Start with code, explain after |
+| Giant code blocks | Show minimal pattern only |
+| Duplicate Apple docs | Add unique value or don't write |
+| Tutorial tone | Write for peers, not students |
diff --git a/creating-swift-skills/references/skill-structure.md b/creating-swift-skills/references/skill-structure.md
new file mode 100644
index 0000000..63bbb31
--- /dev/null
+++ b/creating-swift-skills/references/skill-structure.md
@@ -0,0 +1,65 @@
+# Skill structure
+
+## Required files
+
+```
+skill-name/
+├── SKILL.md              # Entry point, always required
+└── references/           # Optional, for deep content
+    └── topic.md
+```
+
+## SKILL.md anatomy
+
+```markdown
+---
+name: skill-name
+description: What it does + when to invoke it.
+---
+
+# Skill Title
+
+## Overview
+
+One to two sentences.
+
+## Workflow
+
+### 1. First step
+
+Actionable instruction with code.
+
+### 2. Next step
+
+More instructions.
+
+## Reference material
+
+- See `references/topic.md` for details.
+```
+
+## References folder
+
+One file per topic. Use when content is too detailed for SKILL.md.
+
+| File | Purpose |
+|------|---------|
+| `basics.md` | Core concepts and usage |
+| `advanced-patterns.md` | Complex scenarios |
+| `migration.md` | Upgrade paths |
+
+## Assets folder
+
+Optional. Use for templates and scripts.
+
+```
+assets/templates/
+├── bootstrap/        # Starter project files
+└── scripts/          # Automation scripts
+```
+
+## Naming
+
+- Skill folder: `kebab-case` (e.g., `swift-testing`)
+- Files: `kebab-case.md`
+- No prefixes like `swift-` unless disambiguating
diff --git a/creating-swift-skills/references/writing-guidelines.md b/creating-swift-skills/references/writing-guidelines.md
new file mode 100644
index 0000000..11494f8
--- /dev/null
+++ b/creating-swift-skills/references/writing-guidelines.md
@@ -0,0 +1,74 @@
+# Writing guidelines
+
+## Tone
+
+- Direct and actionable
+- Write for experienced developers
+- No tutorials or hand-holding
+- No emojis
+
+## Structure
+
+**Do:**
+- Numbered workflow steps
+- Code examples inline
+- Tables for comparisons
+- Short paragraphs
+
+**Don't:**
+- "Introduction" sections
+- "When to Use This" preambles
+- Lengthy explanations before code
+- Theory without examples
+
+## Code examples
+
+Minimal and copy-paste ready:
+
+```swift
+// Good - shows the pattern directly
+@Test func userCanLogin() async throws {
+    let result = try await auth.login(user: "test", pass: "pass")
+    #expect(result.isSuccess)
+}
+```
+
+```swift
+// Bad - too much setup noise
+import Testing
+import Foundation
+
+struct AuthTests {
+    let auth = AuthService()
+
+    // This test verifies that a user can successfully log in
+    // with valid credentials and receive a success response
+    @Test func userCanLogin() async throws {
+        // Arrange
+        let username = "test"
+        let password = "pass"
+
+        // Act
+        let result = try await auth.login(user: username, pass: password)
+
+        // Assert
+        #expect(result.isSuccess)
+    }
+}
+```
+
+## Descriptions
+
+Frontmatter description format:
+
+```yaml
+# Good
+description: Fix Swift Concurrency issues with actor isolation and Sendable. Use when compiler warns about data races.
+
+# Bad
+description: A comprehensive skill for understanding and resolving Swift Concurrency problems.
+```
+
+Include:
+- What it does
+- When to use (trigger words)