Skip to content

AGENTS.md

Latest commit

 

History

History
150 lines (125 loc) · 7.13 KB

AGENTS.md

File metadata and controls

150 lines (125 loc) · 7.13 KB

AGENTS.md

Purpose

  • This repository is a documentation skill pack for Xcode 26 era Apple framework updates.
  • Content lives in Markdown; there is no compiled source code or app target here.
  • When writing, prefer crisp summaries and actionable guidance.

Repository Layout

  • README.md explains how to install the skill.
  • xcode-26/SKILL.md defines the skill metadata and the reference map.
  • xcode-26/references/ holds the detailed topic notes used by agents.
  • Images such as source.png live at the repo root.

Build, Lint, Test

  • No build system, package manager, or CI config is present in this repo.
  • There are no lint or test scripts configured.
  • If you need to validate Swift snippets, do it in a host app or scratch Xcode project.
  • Prefer manual review: check code blocks compile and match Apple API naming.

Single Test Execution

  • Not applicable; there is no test harness in this repository.
  • If a user wants a single test, instruct them to run it in their app target.

Cursor/Copilot Rules

  • No .cursor/rules/, .cursorrules, or .github/copilot-instructions.md found.
  • If these appear later, append their guidance here and follow them.

Documentation Style

  • Use Markdown with ATX headings (#, ##, ###) as seen in reference files.
  • Start files with an overview section when writing new topic docs.
  • Keep paragraphs short; prefer 1-3 sentences before a list.
  • Use bullet lists for features, steps, and callouts.
  • Use numbered lists for procedures that must be followed in order.
  • Keep line length around 100-120 characters when convenient.
  • Use backticks for identifiers, API names, file paths, and commands.
  • Place code in fenced blocks with a language tag (usually swift or bash).
  • Avoid fancy typography; stick to ASCII punctuation.
  • Prefer neutral, instructional tone; avoid marketing language.

Skill File Conventions

  • Skill files start with YAML front matter (---), name, and description.
  • The name should match the folder (xcode-26) and be lowercase.
  • Keep the description action-oriented and mention the supported domains.
  • Maintain the "Reference map" section listing all reference docs.
  • When adding a new reference doc, update the map in xcode-26/SKILL.md.

Reference Doc Conventions

  • Use ## Overview and ## Basic Implementation when relevant.
  • Use ### for subtopics such as setup, customization, or testing.
  • Include short "Key features" or "Key updates" lists near the top.
  • Provide both explanation and code examples when a feature is complex.
  • Call out platform availability and OS requirements explicitly.
  • Prefer specific API names and modifiers rather than broad prose.
  • Note any feature caveats or gotchas as short bullet points.

Swift Code Snippet Style

  • Use Swift 6 idioms unless the feature is older.
  • Use import statements only for frameworks actually referenced.
  • Keep sample code minimal but complete enough to compile.
  • Use UpperCamelCase for types and lowerCamelCase for variables/functions.
  • Use trailing closures and shorthand arguments when they aid clarity.
  • Prefer let over var unless mutation is required.
  • Use @MainActor/@Observable/@Environment where appropriate and documented.
  • Show Task {} or async/await for concurrency examples rather than callbacks.

Error Handling Guidance

  • Use do/try/catch when the API throws; surface meaningful errors in text.
  • Mention error types or domains only when relevant to the feature.
  • For optional-returning APIs, use guard let with a short fallback.
  • Avoid silent failures in sample code; show a minimal error path.

Naming and Terminology

  • Use Apple's official framework names (SwiftUI, UIKit, AppKit, WidgetKit).
  • Use platform names with correct casing (iOS, iPadOS, macOS, visionOS).
  • Use "Liquid Glass" capitalization as seen in reference docs.
  • Prefer "App Intents" (plural) and "Foundation Models Framework" naming.
  • When referencing APIs, include the module if it helps disambiguate.

Imports and Module Organization

  • Group imports at the top of code blocks; avoid unused imports.
  • If multiple frameworks are required, list system frameworks first.
  • Avoid third-party frameworks in examples unless explicitly requested.

Formatting and Layout

  • Keep indentation at 4 spaces in Swift code blocks.
  • Align chained modifiers vertically when readability improves.
  • Use blank lines between conceptual sections in long code samples.
  • Avoid overly long chained expressions; split into intermediate let bindings.

Content Accuracy

  • Prefer direct guidance based on these reference docs.
  • If information is missing, say so and suggest where to look next.
  • When summarizing, keep the mapping between feature and framework clear.
  • Avoid guessing APIs; if unsure, state the uncertainty.

Agents Workflow

  • For user requests about Xcode 26 features, open the relevant file in xcode-26/references/.
  • Summarize using the repository's phrasing and terminology.
  • If multiple references apply, merge the guidance and note intersections.
  • Keep answers short unless the user asks for deep dives.

Adding New Docs

  • Name files using Title-Case words with hyphens, e.g. SwiftUI-New-Toolbar-Features.md.
  • Place new docs under xcode-26/references/.
  • Add the file to xcode-26/SKILL.md under "Reference map".
  • Update README.md only if install or usage changes.

Markdown Quality Checks

  • Ensure all headings are properly nested (no skipping levels).
  • Verify code fences are closed and language tags are correct.
  • Avoid duplicate headings in the same file unless intentional.
  • Keep images local when possible and include alt text.

Suggested Local Validation (Optional)

  • Use a scratch Xcode project to compile Swift snippets.
  • Run examples on the minimum OS versions mentioned in the docs.
  • If validating widgets or StoreKit, use local configuration files as described.

Known Gaps

  • No automated tooling or CI configuration is present.
  • No Swift packages, Xcode projects, or tests are included.
  • This repo is documentation-first; treat it like a knowledge base.

Security and Safety

  • Do not include real API keys or credentials in examples.
  • Avoid writing code that requires private entitlements unless noted.
  • Prefer on-device testing recommendations when Apple requires it.

Update Process

  • Keep edits scoped to the topic being addressed.
  • Preserve existing structure and wording unless updating for clarity.
  • When adding major sections, match the tone of the surrounding document.
  • Re-run spelling and grammar checks mentally after edits.

Attribution and Links

  • When linking to Apple docs, use official developer.apple.com URLs.
  • Use link text that describes the destination (not "click here").
  • Keep reference links at the end of sections when possible.

Agent Notes

  • If the xcode-26 skill is referenced, load only the needed reference files.
  • Mention when guidance is not covered by the current reference set.
  • Avoid inventing new APIs; prefer "check the latest docs" if uncertain.

Maintenance

  • Keep this AGENTS.md aligned with repository contents.
  • If new tooling appears, update Build/Lint/Test sections first.
  • Revisit style guidelines after major content restructuring.

End