Use when structuring app entry points, managing authentication flows, switching root views, handling scene lifecycle, or asking 'how do I structure my @main', 'where does auth state live', 'how do I prevent screen flicker on launch', 'when should I modularize' - app-level composition patterns for iOS 26+
/plugin marketplace add CharlesWiltgen/Axiom/plugin install axiom@axiom-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Use this skill when:
| What You Might Ask | Why This Skill Helps |
|---|---|
| "How do I switch between login and main screens?" | AppStateController pattern with validated transitions |
| "My app flickers when switching from splash to main" | Flicker prevention with animation coordination |
| "Where should auth state live?" | App-level state machine, not scattered booleans |
| "How do I handle app going to background?" | scenePhase lifecycle patterns |
| "When should I split my app into modules?" | Decision tree based on codebase size and team |
| "How do I restore state after app is killed?" | SceneStorage and state validation patterns |
What app-level architecture question are you solving?
│
├─ How do I manage app states (loading, auth, main)?
│ └─ Part 1: App-Level State Machines
│ - Enum-based state with validated transitions
│ - AppStateController pattern
│ - Prevents "boolean soup" anti-pattern
│
├─ How do I structure @main and root view switching?
│ └─ Part 2: Root View Switching Patterns
│ - Delegate to AppStateController (no logic in @main)
│ - Flicker prevention with animation
│ - Coordinator integration
│
├─ How do I handle scene lifecycle?
│ └─ Part 3: Scene Lifecycle Integration
│ - scenePhase for session validation
│ - SceneStorage for restoration
│ - Multi-window coordination
│
├─ When should I modularize?
│ └─ Part 4: Feature Module Basics
│ - Decision tree by size/team
│ - Module boundaries and DI
│ - Navigation coordination
│
└─ What mistakes should I avoid?
└─ Part 5: Anti-Patterns + Part 6: Pressure Scenarios
- Boolean-based state
- Logic in @main
- Missing restoration validation
"Apps have discrete states. Model them explicitly with enums, not scattered booleans."
Every non-trivial app has distinct states: loading, unauthenticated, onboarding, authenticated, error recovery. These states should be:
// ❌ Boolean soup — impossible to validate, prone to invalid states
class AppState {
var isLoading = true
var isLoggedIn = false
var hasCompletedOnboarding = false
var hasError = false
var user: User?
// What if isLoading && isLoggedIn && hasError are all true?
// Invalid state, but nothing prevents it
}
Problems
enum AppState: Equatable {
case loading
case unauthenticated
case onboarding(OnboardingStep)
case authenticated(User)
case error(AppError)
}
enum OnboardingStep: Equatable {
case welcome
case permissions
case profileSetup
case complete
}
enum AppError: Equatable {
case networkUnavailable
case sessionExpired
case maintenanceMode
}
@Observable
@MainActor
class AppStateController {
private(set) var state: AppState = .loading
// MARK: - State Transitions
func transition(to newState: AppState) {
guard isValidTransition(from: state, to: newState) else {
assertionFailure("Invalid transition: \(state) → \(newState)")
logInvalidTransition(from: state, to: newState)
return
}
let oldState = state
state = newState
logTransition(from: oldState, to: newState)
}
// MARK: - Validation
private func isValidTransition(from: AppState, to: AppState) -> Bool {
switch (from, to) {
// From loading
case (.loading, .unauthenticated): return true
case (.loading, .authenticated): return true
case (.loading, .error): return true
// From unauthenticated
case (.unauthenticated, .onboarding): return true
case (.unauthenticated, .authenticated): return true
case (.unauthenticated, .error): return true
// From onboarding
case (.onboarding, .onboarding): return true // Step changes
case (.onboarding, .authenticated): return true
case (.onboarding, .unauthenticated): return true // Cancelled
// From authenticated
case (.authenticated, .unauthenticated): return true // Logout
case (.authenticated, .error): return true
// From error
case (.error, .loading): return true // Retry
case (.error, .unauthenticated): return true
default: return false
}
}
// MARK: - Logging
private func logTransition(from: AppState, to: AppState) {
#if DEBUG
print("AppState: \(from) → \(to)")
#endif
}
private func logInvalidTransition(from: AppState, to: AppState) {
// Log to analytics for debugging
Analytics.log("InvalidStateTransition", properties: [
"from": String(describing: from),
"to": String(describing: to)
])
}
}
extension AppStateController {
func initialize() async {
// Check for stored session
if let session = await SessionStorage.loadSession() {
// Validate session is still valid
do {
let user = try await AuthService.validateSession(session)
transition(to: .authenticated(user))
} catch {
// Session expired or invalid
await SessionStorage.clearSession()
transition(to: .unauthenticated)
}
} else {
transition(to: .unauthenticated)
}
}
}
┌─────────────────────────────────────────────────────────────┐
│ .loading │
└────────────┬───────────────┬────────────────┬───────────────┘
│ │ │
▼ ▼ ▼
.unauthenticated .authenticated .error
│ │ │
▼ │ │
.onboarding ─────────►│◄───────────────┘
│ │
└───────────────┘
@Test func testValidTransitions() async {
let controller = AppStateController()
// Loading → Unauthenticated (valid)
controller.transition(to: .unauthenticated)
#expect(controller.state == .unauthenticated)
// Unauthenticated → Authenticated (valid)
let user = User(id: "1", name: "Test")
controller.transition(to: .authenticated(user))
#expect(controller.state == .authenticated(user))
}
@Test func testInvalidTransitionRejected() async {
let controller = AppStateController()
// Loading → Onboarding (invalid — must go through unauthenticated)
controller.transition(to: .onboarding(.welcome))
#expect(controller.state == .loading) // Unchanged
}
@Test func testSessionExpiredTransition() async {
let controller = AppStateController()
let user = User(id: "1", name: "Test")
controller.transition(to: .authenticated(user))
// Authenticated → Error (session expired)
controller.transition(to: .error(.sessionExpired))
#expect(controller.state == .error(.sessionExpired))
// Error → Unauthenticated (force re-login)
controller.transition(to: .unauthenticated)
#expect(controller.state == .unauthenticated)
}
From WWDC 2025's "Explore concurrency in SwiftUI":
"Find the boundaries between UI code that requires time-sensitive changes, and long-running async logic."
The key insight: synchronous state changes drive UI (for animations), async code lives in the model (testable without SwiftUI), and state bridges the two.
// ✅ State-as-Bridge: UI triggers state, model does async work
struct ColorExtractorView: View {
@State private var model = ColorExtractor()
var body: some View {
Button("Extract Colors") {
// ✅ Synchronous state change triggers animation
withAnimation { model.isExtracting = true }
// Async work happens in Task
Task {
await model.extractColors()
// ✅ Synchronous state change ends animation
withAnimation { model.isExtracting = false }
}
}
.scaleEffect(model.isExtracting ? 1.5 : 1.0)
}
}
@Observable
class ColorExtractor {
var isExtracting = false
var colors: [Color] = []
func extractColors() async {
// Heavy computation happens here, testable without SwiftUI
let extracted = await heavyComputation()
colors = extracted
}
}
Why this matters for app composition
"The @main entry point should be a thin shell. All logic belongs in AppStateController."
@main
struct MyApp: App {
@State private var appState = AppStateController()
var body: some Scene {
WindowGroup {
RootView()
.environment(appState)
.task {
await appState.initialize()
}
}
}
}
What @main does
What @main does NOT do
struct RootView: View {
@Environment(AppStateController.self) private var appState
var body: some View {
Group {
switch appState.state {
case .loading:
LaunchView()
case .unauthenticated:
AuthenticationFlow()
case .onboarding(let step):
OnboardingFlow(step: step)
case .authenticated(let user):
MainTabView(user: user)
case .error(let error):
ErrorRecoveryView(error: error)
}
}
}
}
When app state changes, you might see a flash of the old screen before the new one appears. This happens when:
struct RootView: View {
@Environment(AppStateController.self) private var appState
var body: some View {
ZStack {
switch appState.state {
case .loading:
LaunchView()
.transition(.opacity)
case .unauthenticated:
AuthenticationFlow()
.transition(.opacity)
case .onboarding(let step):
OnboardingFlow(step: step)
.transition(.opacity)
case .authenticated(let user):
MainTabView(user: user)
.transition(.opacity)
case .error(let error):
ErrorRecoveryView(error: error)
.transition(.opacity)
}
}
.animation(.easeInOut(duration: 0.3), value: appState.state)
}
}
For a polished experience, ensure the loading screen is visible long enough:
extension AppStateController {
func initialize() async {
let startTime = Date()
// Do actual initialization
await performInitialization()
// Ensure minimum display time for loading screen
let elapsed = Date().timeIntervalSince(startTime)
let minimumDuration: TimeInterval = 0.5
if elapsed < minimumDuration {
try? await Task.sleep(for: .seconds(minimumDuration - elapsed))
}
}
}
If using coordinators, integrate them at the root level:
struct RootView: View {
@Environment(AppStateController.self) private var appState
@State private var authCoordinator = AuthCoordinator()
@State private var mainCoordinator = MainCoordinator()
var body: some View {
Group {
switch appState.state {
case .loading:
LaunchView()
case .unauthenticated, .onboarding:
AuthenticationFlow()
.environment(authCoordinator)
case .authenticated(let user):
MainTabView(user: user)
.environment(mainCoordinator)
case .error(let error):
ErrorRecoveryView(error: error)
}
}
.animation(.easeInOut(duration: 0.3), value: appState.state)
}
}
"Scene lifecycle events are app-wide concerns handled centrally, not scattered across features."
ScenePhase indicates a scene's operational state. How you interpret the value depends on where it's read.
Read from a View → Returns the phase of the enclosing scene Read from App → Returns an aggregate value reflecting all scenes
| Phase | Description |
|---|---|
.active | Scene is in the foreground and interactive |
.inactive | Scene is in the foreground but should pause work |
.background | Scene isn't visible; app may terminate soon |
Critical insight from Apple docs When reading at the App level, .active means any scene is active, and .background means all scenes are in background.
@main
struct MyApp: App {
@State private var appState = AppStateController()
@Environment(\.scenePhase) private var scenePhase
var body: some Scene {
WindowGroup {
RootView()
.environment(appState)
.task {
await appState.initialize()
}
}
.onChange(of: scenePhase) { oldPhase, newPhase in
handleScenePhaseChange(from: oldPhase, to: newPhase)
}
}
private func handleScenePhaseChange(from: ScenePhase, to: ScenePhase) {
switch to {
case .active:
// App became active — validate session, refresh data
Task {
await appState.validateSession()
await appState.refreshIfNeeded()
}
case .inactive:
// App about to go inactive — save state
appState.prepareForBackground()
case .background:
// App in background — release resources
appState.releaseResources()
@unknown default:
break
}
}
}
extension AppStateController {
func validateSession() async {
guard case .authenticated(let user) = state else { return }
do {
// Check if token is still valid
let isValid = try await AuthService.validateToken(user.token)
if !isValid {
transition(to: .error(.sessionExpired))
}
} catch {
// Network error — keep authenticated but show warning
// Don't immediately log out on transient network issues
}
}
func prepareForBackground() {
// Save any pending data
// Cancel non-essential network requests
// Prepare for potential termination
}
func releaseResources() {
// Release cached images
// Stop location updates if not essential
// Reduce memory footprint
}
}
From Apple documentation: SceneStorage provides automatic state restoration. The system manages saving and restoring on your behalf.
Key constraints
struct MainTabView: View {
@SceneStorage("selectedTab") private var selectedTab = 0
@SceneStorage("lastViewedItemID") private var lastViewedItemID: String?
var body: some View {
TabView(selection: $selectedTab) {
HomeTab()
.tag(0)
SearchTab()
.tag(1)
ProfileTab()
.tag(2)
}
.onAppear {
if let itemID = lastViewedItemID {
// Restore to last viewed item
navigateToItem(itemID)
}
}
}
}
For complex navigation, use a Codable NavigationModel:
// Encapsulate navigation state with Codable conformance
class NavigationModel: ObservableObject, Codable {
@Published var selectedCategory: Category?
@Published var recipePath: [Recipe] = []
enum CodingKeys: String, CodingKey {
case selectedCategory
case recipePathIds
}
func encode(to encoder: Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)
try container.encodeIfPresent(selectedCategory, forKey: .selectedCategory)
// Store only IDs, not full models
try container.encode(recipePath.map(\.id), forKey: .recipePathIds)
}
required init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
self.selectedCategory = try container.decodeIfPresent(
Category.self, forKey: .selectedCategory)
let recipePathIds = try container.decode([Recipe.ID].self, forKey: .recipePathIds)
// compactMap discards deleted items gracefully
self.recipePath = recipePathIds.compactMap { DataModel.shared[$0] }
}
var jsonData: Data? {
get { try? JSONEncoder().encode(self) }
set {
guard let data = newValue,
let model = try? JSONDecoder().decode(NavigationModel.self, from: data)
else { return }
self.selectedCategory = model.selectedCategory
self.recipePath = model.recipePath
}
}
}
// Use with SceneStorage
struct ContentView: View {
@StateObject private var navModel = NavigationModel()
@SceneStorage("navigation") private var data: Data?
var body: some View {
NavigationSplitView { /* ... */ }
.task {
if let data = data {
navModel.jsonData = data
}
for await _ in navModel.objectWillChangeSequence {
data = navModel.jsonData
}
}
}
}
Key patterns from WWDC
compactMap to handle deleted items gracefullyobjectWillChange for real-time persistenceNever trust restored state blindly:
struct DetailView: View {
@SceneStorage("detailItemID") private var restoredItemID: String?
@State private var item: Item?
var body: some View {
Group {
if let item {
ItemContent(item: item)
} else {
ProgressView()
}
}
.task {
if let itemID = restoredItemID {
// Validate item still exists
item = await ItemService.fetch(itemID)
if item == nil {
// Item was deleted — clear restoration
restoredItemID = nil
}
}
}
}
}
From Apple documentation: Every window in a WindowGroup maintains independent state. The system allocates new storage for @State and @StateObject for each window.
@main
struct MyApp: App {
@State private var appState = AppStateController()
var body: some Scene {
// Primary window
WindowGroup {
MainView()
.environment(appState)
}
// Data-presenting window (iPad)
// Prefer lightweight data (IDs, not full models)
WindowGroup("Detail", id: "detail", for: Item.ID.self) { $itemID in
if let itemID {
DetailView(itemID: itemID)
.environment(appState)
}
}
#if os(visionOS)
// Immersive space
ImmersiveSpace(id: "immersive") {
ImmersiveView()
.environment(appState)
}
#endif
}
}
Key behaviors from Apple docs
struct ItemRow: View {
let item: Item
@Environment(\.openWindow) private var openWindow
var body: some View {
Button(item.title) {
// Open in new window on iPad
// Use ID to match window group, value to pass data
openWindow(id: "detail", value: item.id)
}
}
}
struct DetailView: View {
var itemID: Item.ID?
@Environment(\.dismiss) private var dismiss
var body: some View {
VStack {
// ...
Button("Done") {
dismiss() // Closes this window
}
}
}
}
"Split into modules when features have clear boundaries. Not before."
Premature modularization creates overhead. Late modularization creates pain. Use this decision tree.
Should I extract this feature into a module?
│
├─ Is the codebase under 5,000 lines with 1-2 developers?
│ └─ NO modularization needed yet
│ Single target is fine, revisit at 10,000 lines
│
├─ Is the codebase 5,000-20,000 lines with 3+ developers?
│ └─ CONSIDER modularization
│ Look for natural boundaries
│
├─ Is the codebase over 20,000 lines?
│ └─ MODULARIZE for build times
│ Parallel compilation essential
│
├─ Could this feature be used in multiple apps?
│ └─ EXTRACT to reusable module
│ Shared authentication, analytics, axiom-networking
│
├─ Do multiple developers work on this feature daily?
│ └─ EXTRACT for merge conflict reduction
│ Isolated codebases = parallel work
│
└─ Does the feature have clear input/output boundaries?
├─ YES → Good candidate for module
└─ NO → Refactor boundaries first, then extract
// FeatureModule/Sources/FeatureModule/FeatureAPI.swift
/// Public interface for the feature module
public protocol FeatureAPI {
/// Show the feature's main view
@MainActor
func makeMainView() -> AnyView
/// Handle deep link into feature
@MainActor
func handleDeepLink(_ url: URL) -> Bool
}
/// Factory to create feature with dependencies
public struct FeatureFactory {
public static func create(
analytics: AnalyticsProtocol,
networking: NetworkingProtocol
) -> FeatureAPI {
FeatureImplementation(
analytics: analytics,
networking: axiom-networking
)
}
}
// FeatureModule/Sources/FeatureModule/Internal/FeatureImplementation.swift
internal class FeatureImplementation: FeatureAPI {
private let analytics: AnalyticsProtocol
private let networking: NetworkingProtocol
internal init(
analytics: AnalyticsProtocol,
networking: NetworkingProtocol
) {
self.analytics = analytics
self.networking = networking
}
@MainActor
public func makeMainView() -> AnyView {
AnyView(FeatureMainView(viewModel: makeViewModel()))
}
public func handleDeepLink(_ url: URL) -> Bool {
// Handle feature-specific deep links
return false
}
private func makeViewModel() -> FeatureViewModel {
FeatureViewModel(analytics: analytics, axiom-networking: axiom-networking)
}
}
// MainApp/Sources/App/AppDependencies.swift
@Observable
class AppDependencies {
let analytics: AnalyticsProtocol
let networking: NetworkingProtocol
// Lazy-created feature modules
lazy var profileFeature: FeatureAPI = {
ProfileFeatureFactory.create(
analytics: analytics,
networking: axiom-networking
)
}()
lazy var settingsFeature: FeatureAPI = {
SettingsFeatureFactory.create(
analytics: analytics,
networking: axiom-networking
)
}()
}
// MainApp/Sources/App/MainTabView.swift
struct MainTabView: View {
@Environment(AppDependencies.self) private var dependencies
var body: some View {
TabView {
dependencies.profileFeature.makeMainView()
.tabItem { Label("Profile", systemImage: "person") }
dependencies.settingsFeature.makeMainView()
.tabItem { Label("Settings", systemImage: "gear") }
}
}
}
Features should not know about each other directly:
// ❌ Feature knows about other features
struct ProfileView: View {
func showSettings() {
// ProfileView imports SettingsFeature — circular dependency risk
NavigationLink(value: SettingsDestination())
}
}
// ✅ Feature delegates navigation to coordinator
struct ProfileView: View {
let onShowSettings: () -> Void
func showSettings() {
onShowSettings() // ProfileView doesn't know what happens
}
}
// Coordinator wires features together
class MainCoordinator {
func showSettings(from profile: ProfileFeatureAPI) {
// Coordinator knows about both features
navigationPath.append(SettingsRoute())
}
}
MyApp/
├── App/ # Main app target
│ ├── MyApp.swift # @main entry point
│ ├── AppDependencies.swift # Dependency container
│ ├── AppStateController.swift # App state machine
│ └── Coordinators/ # Navigation coordinators
│
├── Packages/
│ ├── Core/ # Shared utilities
│ │ ├── Networking/
│ │ ├── Analytics/
│ │ └── Design/ # Design system
│ │
│ ├── Features/ # Feature modules
│ │ ├── Profile/
│ │ ├── Settings/
│ │ └── Onboarding/
│ │
│ └── Domain/ # Business logic
│ ├── Models/
│ └── Services/
// ❌ Boolean soup — impossible to validate
class AppState {
var isLoading = true
var isLoggedIn = false
var hasCompletedOnboarding = false
var hasError = false
}
// What if isLoading && isLoggedIn && hasError are all true?
Fix Use enum-based state (Part 1)
// ✅ Explicit states — compiler prevents invalid combinations
enum AppState {
case loading
case unauthenticated
case onboarding(OnboardingStep)
case authenticated(User)
case error(AppError)
}
// ❌ Business logic in App entry point
@main
struct MyApp: App {
@State private var user: User?
@State private var isLoading = true
var body: some Scene {
WindowGroup {
if isLoading {
LoadingView()
} else if let user {
MainView(user: user)
} else {
LoginView(onLogin: { self.user = $0 })
}
}
.task {
user = await AuthService.getCurrentUser()
isLoading = false
}
}
}
Problems
Fix Delegate to AppStateController (Part 2)
// ✅ @main is a thin shell
@main
struct MyApp: App {
@State private var appState = AppStateController()
var body: some Scene {
WindowGroup {
RootView()
.environment(appState)
.task { await appState.initialize() }
}
}
}
// ❌ Trusts restored state blindly
.onAppear {
if let savedState = SceneStorage.appState {
appState.state = savedState // Token might be expired!
}
}
Problems
Fix Validate before applying (Part 3)
// ✅ Validates restored state
.task {
if let savedSession = await SessionStorage.loadSession() {
do {
let user = try await AuthService.validateSession(savedSession)
appState.transition(to: .authenticated(user))
} catch {
// Session invalid — force re-login
await SessionStorage.clearSession()
appState.transition(to: .unauthenticated)
}
}
}
// ❌ Every feature knows about every other feature
struct ProfileView: View {
@Environment(\.navigationPath) private var path
func showSettings() {
path.append(SettingsDestination()) // ProfileView imports Settings
}
func showOrderHistory() {
path.append(OrderHistoryDestination()) // ProfileView imports Orders
}
}
Problems
Fix Delegate to coordinator (Part 4)
// ✅ Feature delegates navigation decisions
struct ProfileView: View {
let onShowSettings: () -> Void
let onShowOrderHistory: () -> Void
// ProfileView doesn't know what these do
}
// ❌ Single coordinator knows all features
class AppCoordinator {
func showProfile() { }
func showSettings() { }
func showOnboarding() { }
func showPayment() { }
func showChat() { }
func showOrderHistory() { }
func showNotifications() { }
// ... 50 more methods
}
Problems
Fix Scoped coordinators
// ✅ Scoped coordinators for each domain
class AuthCoordinator { } // Login, signup, forgot password
class MainCoordinator { } // Tab navigation, main flows
class SettingsCoordinator { } // Settings navigation tree
class OrderCoordinator { } // Order flow, history, details
"We only have one flow right now. Just show MainView directly, we'll add auth later."
| Option | Initial | When Adding Auth | Total |
|---|---|---|---|
| Hardcode MainView | 0 min | 2-4 hours refactor | 2-4 hours |
| AppStateController | 30 min | 30 min add state | 1 hour |
"The AppStateController pattern takes 30 minutes now. When we add auth later — and we will — it'll take another 30 minutes to add the state. Hardcoding now saves 0 minutes because we'll spend 2-4 hours refactoring when we need auth. Let's invest 30 minutes now."
Create minimal AppStateController with two states:
enum AppState {
case loading
case ready
}
When auth is needed, add states:
enum AppState {
case loading
case unauthenticated // Added
case authenticated(User) // Added
}
Total effort: 1 hour instead of 4 hours
"Let's keep everything in one target. Modules are over-engineering."
| Codebase | Team | Recommendation |
|---|---|---|
| < 5,000 lines | 1-2 devs | Single target is fine |
| 5,000-20,000 lines | 3+ devs | Consider modules |
| > 20,000 lines | Any | Modules essential |
"I agree modules add overhead. Let's use this decision tree: We have [X] lines and [Y] developers. Based on that, we [should/shouldn't] modularize yet. If we hit [threshold], we'll revisit. Sound good?"
find . -name "*.swift" | xargs wc -l"Testing navigation state is too hard. Let's just do manual QA."
// ✅ Test navigation state without UI
@Test func testLoginCompletesOnboarding() async {
let controller = AppStateController()
controller.transition(to: .unauthenticated)
// Simulate login
await controller.handleLogin(user: mockUser)
// First-time user goes to onboarding
#expect(controller.state == .onboarding(.welcome))
}
@Test func testDeepLinkWhileUnauthenticated() async {
let controller = AppStateController()
controller.transition(to: .unauthenticated)
// Deep link to order
let handled = controller.handleDeepLink(URL(string: "app://order/123")!)
// Should not navigate — requires auth
#expect(handled == false)
#expect(controller.state == .unauthenticated)
}
"Navigation is complex, which is exactly why we need automated tests. The AppStateController pattern lets us test state transitions without launching the UI. We can verify deep linking, auth flows, and restoration in seconds. Manual QA can't catch all the combinations."
isValidTransitionWWDC: 2025-266, 2024-10150, 2023-10149, 2025-256, 2022-10054
Docs: /swiftui/scenephase, /swiftui/scene, /swiftui/scenestorage, /swiftui/windowgroup, /observation/observable()
Skills: axiom-swiftui-architecture, axiom-swiftui-nav, axiom-swift-concurrency
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.