# alessiorubicini/apple-foundation-models-agent-skill architecture

> Architecture diagram of the GitHub repository alessiorubicini/apple-foundation-models-agent-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alessiorubicini/apple-foundation-models-agent-skill
- Repository: https://github.com/alessiorubicini/apple-foundation-models-agent-skill

## Overview

This repository is an Agent Skill: it equips AI coding assistants to advise developers building with Apple’s FoundationModels framework, rather than implementing those APIs itself. The principal workflow is an assistant using the skill’s entry guidance and on-demand reference routing to answer a developer’s integration question. The references cover model selection and session setup, generation and tool interactions, and operational concerns such as concurrency and errors. Routing edges reflect the README’s description of the reference index; individual runtime API behavior is guidance, not repository code.

Main entry points: [`apple-foundation-models-skill/references/_index.md`](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/_index.md) (Reference Index), [`apple-foundation-models-skill/SKILL.md`](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/SKILL.md) (Skill Guidance), [`apple-foundation-models-skill/references/system-language-model.md`](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/system-language-model.md) (System Models), [`apple-foundation-models-skill/references/session-lifecycle.md`](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/session-lifecycle.md) (Session Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Skill Entry"]
  node_skill["Skill Guidance<br/>[SKILL.md]"]
  node_index["Reference Index<br/>[_index.md]"]
end

subgraph group_model_sessions["Models And Sessions"]
  node_models["System Models"]
  node_sessions["Session Lifecycle"]
  node_properties["Session Properties"]
  node_cloud["Private Cloud"]
  node_providers["Custom Providers"]
end

subgraph group_generation["Generation And Interaction"]
  node_generation["Guided Generation"]
  node_options["Generation Options"]
  node_tools["Tool Calling<br/>[tool-calling.md]"]
  node_streaming["Streaming<br/>[streaming.md]"]
  node_attachments["Prompt Attachments"]
  node_transcripts["Transcript History<br/>[transcripts.md]"]
end

subgraph group_operations["Operations And Guidance"]
  node_concurrency["Concurrency<br/>[concurrency.md]"]
  node_errors["Errors And Fallbacks<br/>[error-handling.md]"]
  node_performance["Performance<br/>[performance.md]"]
  node_prompting["Prompting Techniques"]
  node_profiles["Dynamic Profiles"]
  node_os27["OS 27 Changes"]
end

node_developer(("Developer"))
node_assistant(("AI Assistant"))

node_developer -->|"requests guidance"| node_assistant
node_assistant -->|"reads skill"| node_skill
node_assistant -->|"routes references"| node_index
node_index -->|"routes to"| node_models
node_index -->|"routes to"| node_sessions
node_index -->|"routes to"| node_properties
node_index -->|"routes to"| node_cloud
node_index -->|"routes to"| node_providers
node_index -->|"routes to"| node_generation
node_index -->|"routes to"| node_options
node_index -->|"routes to"| node_tools
node_index -->|"routes to"| node_streaming
node_index -->|"routes to"| node_attachments
node_index -->|"routes to"| node_transcripts
node_index -->|"routes to"| node_concurrency
node_index -->|"routes to"| node_errors
node_index -->|"routes to"| node_performance
node_index -->|"routes to"| node_prompting
node_index -->|"routes to"| node_profiles
node_index -->|"routes to"| node_os27

click node_skill "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/SKILL.md"
click node_index "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/_index.md"
click node_models "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/system-language-model.md"
click node_sessions "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/session-lifecycle.md"
click node_properties "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/session-properties.md"
click node_cloud "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/private-cloud-compute.md"
click node_providers "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/custom-language-model-provider.md"
click node_generation "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/guided-generation.md"
click node_options "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/generation-options.md"
click node_tools "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/tool-calling.md"
click node_streaming "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/streaming.md"
click node_attachments "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/prompt-attachments.md"
click node_transcripts "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/transcripts.md"
click node_concurrency "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/concurrency.md"
click node_errors "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/error-handling.md"
click node_performance "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/performance.md"
click node_prompting "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/prompting-techniques.md"
click node_profiles "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/dynamic-profiles.md"
click node_os27 "https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/os-27-api-changes.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill,node_index toneBlue
class node_models,node_sessions,node_properties,node_cloud,node_providers toneAmber
class node_generation,node_options,node_tools,node_streaming,node_attachments,node_transcripts toneMint
class node_concurrency,node_errors,node_performance,node_prompting,node_profiles,node_os27 toneRose
class node_developer,node_assistant toneIndigo
```

## Components

### Skill Entry

- [Skill Guidance](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/SKILL.md): `apple-foundation-models-skill/SKILL.md`
- [Reference Index](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/_index.md): `apple-foundation-models-skill/references/_index.md`

### Models And Sessions

- [System Models](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/system-language-model.md): `apple-foundation-models-skill/references/system-language-model.md`
- [Session Lifecycle](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/session-lifecycle.md): `apple-foundation-models-skill/references/session-lifecycle.md`
- [Session Properties](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/session-properties.md): `apple-foundation-models-skill/references/session-properties.md`
- [Private Cloud](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/private-cloud-compute.md): `apple-foundation-models-skill/references/private-cloud-compute.md`
- [Custom Providers](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/custom-language-model-provider.md): `apple-foundation-models-skill/references/custom-language-model-provider.md`

### Generation And Interaction

- [Guided Generation](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/guided-generation.md): `apple-foundation-models-skill/references/guided-generation.md`
- [Generation Options](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/generation-options.md): `apple-foundation-models-skill/references/generation-options.md`
- [Tool Calling](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/tool-calling.md): `apple-foundation-models-skill/references/tool-calling.md`
- [Streaming](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/streaming.md): `apple-foundation-models-skill/references/streaming.md`
- [Prompt Attachments](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/prompt-attachments.md): `apple-foundation-models-skill/references/prompt-attachments.md`
- [Transcript History](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/transcripts.md): `apple-foundation-models-skill/references/transcripts.md`

### Operations And Guidance

- [Concurrency](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/concurrency.md): `apple-foundation-models-skill/references/concurrency.md`
- [Errors And Fallbacks](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/error-handling.md): `apple-foundation-models-skill/references/error-handling.md`
- [Performance](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/performance.md): `apple-foundation-models-skill/references/performance.md`
- [Prompting Techniques](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/prompting-techniques.md): `apple-foundation-models-skill/references/prompting-techniques.md`
- [Dynamic Profiles](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/dynamic-profiles.md): `apple-foundation-models-skill/references/dynamic-profiles.md`
- [OS 27 Changes](https://github.com/alessiorubicini/apple-foundation-models-agent-skill/blob/main/apple-foundation-models-skill/references/os-27-api-changes.md): `apple-foundation-models-skill/references/os-27-api-changes.md`

### Other components

- **Developer**
- **AI Assistant**

## Connections

- Developer → AI Assistant: requests guidance
- AI Assistant → Skill Guidance: reads skill
- AI Assistant → Reference Index: routes references
- Reference Index → System Models: routes to
- Reference Index → Session Lifecycle: routes to
- Reference Index → Session Properties: routes to
- Reference Index → Private Cloud: routes to
- Reference Index → Custom Providers: routes to
- Reference Index → Guided Generation: routes to
- Reference Index → Generation Options: routes to
- Reference Index → Tool Calling: routes to
- Reference Index → Streaming: routes to
- Reference Index → Prompt Attachments: routes to
- Reference Index → Transcript History: routes to
- Reference Index → Concurrency: routes to
- Reference Index → Errors And Fallbacks: routes to
- Reference Index → Performance: routes to
- Reference Index → Prompting Techniques: routes to
- Reference Index → Dynamic Profiles: routes to
- Reference Index → OS 27 Changes: routes to