amethyst/.claude/core-skills-plan.md

AmethystMultiplatform Skills Creation Plan

Overview

Create 8 hybrid domain skills combining general expertise with AmethystMultiplatform-specific patterns.

Approach: Each skill provides domain knowledge + project-specific implementation patterns from codebase.

Skills to Implement

1. kotlin-multiplatform ✅ COMPLETED

Focus: KMP architecture, jvmAndroid source set pattern, expect/actual

SKILL.md sections:

• Mental model: KMP hierarchy as dependency graph
• Source set architecture: commonMain → jvmAndroid → {androidMain, jvmMain}
• The jvmAndroid pattern (unique to this project, verified in quartz/build.gradle.kts:132-149)
• expect/actual mechanics with 24+ examples from codebase
• iOS framework setup for Quartz distribution

Bundled resources:

• references/source-set-hierarchy.md - Visual diagram + examples
• references/expect-actual-catalog.md - All 24 expect/actual pairs with patterns
• scripts/validate-kmp-structure.sh - Verify source set dependencies
• assets/kmp-hierarchy-diagram.png - Visual graph

Differentiation: Existing kotlin-multiplatform agent = general KMP. This skill = Amethyst's unique jvmAndroid pattern, concrete examples.

Status: ✅ Skill created and packaged at .claude/skills/kotlin-multiplatform/

---

2. gradle-expert

Focus: Build optimization, dependency resolution, multi-module KMP troubleshooting

SKILL.md sections:

• Build architecture: 4 modules, dependency flow
• Version catalog mastery (libs.versions.toml)
• Module dependency patterns (api vs implementation)
• Android-specific: compileSdk, proguard
• Desktop packaging: TargetFormat, distributions
• Build performance: daemon, parallel, caching
• Common errors: compose version conflicts, secp256k1 JNI variants

Bundled resources:

• references/build-commands.md - Common gradle tasks
• references/dependency-graph.md - Module visualization
• scripts/analyze-build-time.sh - Performance report
• scripts/fix-dependency-conflicts.sh - Conflict patterns

Differentiation: Focus on 4-module structure, KMP + Android + Desktop combo, specific issues (compose conflicts).

---

3. kotlin-expert ✅ DRAFT COMPLETE

Focus: Flow state management, sealed hierarchies, immutability, DSL builders, inline/reified

SKILL.md sections:

• Flow state management: StateFlow/SharedFlow patterns (AccountManager, RelayConnectionManager)
• Sealed hierarchies: sealed class vs sealed interface decision trees (AccountState, SignerResult)
• Immutability: @Immutable for Compose performance (173+ event classes)
• DSL builders: Type-safe fluent APIs (TagArrayBuilder, TlvBuilder)
• Inline functions: reified generics, performance optimization (OptimizedJsonMapper)
• Value classes: Zero-cost wrappers (optimization opportunity)

Bundled resources:

• references/flow-patterns.md - StateFlow/SharedFlow with AccountManager, RelayManager patterns
• references/sealed-class-catalog.md - All 8 sealed types in quartz with usage patterns
• references/dsl-builder-examples.md - TagArrayBuilder, PrivateTagArrayBuilder, TlvBuilder, custom DSL patterns
• references/immutability-patterns.md - @Immutable annotation, data classes, ImmutableList/Map/Set

Differentiation: Complements kotlin-coroutines agent (deep async). This skill = Amethyst Kotlin idioms (StateFlow state management, sealed for type safety, @Immutable for Compose, DSL builders).

Status: ✅ SKILL.md (455 lines) + 4 references created at .claude/skills/kotlin-expert/

10-Step Progress:

1. ✅ UNDERSTAND - Defined scope (Flow/sealed/DSL/immutability/inline)
2. ✅ EXPLORE - Found 173 @Immutable events, StateFlow in AccountManager/RelayManager, SignerResult generics, TagArrayBuilder
3. ✅ RESEARCH - StateFlow vs SharedFlow, sealed class vs interface best practices 2025
4. ✅ SYNTHESIZE - Extracted Amethyst patterns (hot flows for state, sealed for results, @Immutable for perf)
5. ✅ DRAFT - Created SKILL.md + 4 reference files (flow, sealed, dsl, immutability)
6. ✅ SELF-CRITIQUE - Reviewed against 4 Core Truths (all PASS)
7. ✅ ITERATE - Draft complete (skipping deep iteration for now)
8. ⏸️ TEST - Deferred to later (requires real usage scenarios)
9. ⏸️ FINALIZE - Deferred to later
10. ✅ DOCUMENT - Updated plan

---

4. compose-expert

Focus: Shared composables, state management, animations, Material3

SKILL.md sections:

• Shared composables philosophy (100+ already shared in commons/commonMain)
• State management: remember, derivedStateOf, produceState
• Recomposition optimization: @Stable/@Immutable
• Material3 conventions: theming
• Custom icons: ImageVector builders (38+ icons)
• Platform differences: Desktop vs Android UI
• Performance: lazy lists, image loading

Bundled resources:

• references/shared-composables-catalog.md - 100+ composables
• references/state-patterns.md - State hoisting examples
• references/icon-assets.md - Custom icon catalog
• scripts/find-composables.sh - Grep @Composable

Differentiation: Multiplatform Compose patterns, shared vs platform UI philosophy, Amethyst conventions (robohash, custom icons).

---

5. ios-expert

Focus: iosMain patterns, Swift/KMP interop, XCFramework generation

SKILL.md sections:

• iOS source sets: iosMain, iosX64Main, iosArm64Main
• Swift interop: type mapping, nullability
• expect/actual iOS: 10+ examples from quartz/iosMain
• XCFramework setup: baseName = "quartz-kmpKit"
• Platform APIs: platform.posix, CFNetwork, Security
• CocoaPods integration
• XCode project setup

Bundled resources:

• references/ios-actual-implementations.md - 10 iosMain actuals
• references/swift-interop-guide.md - Type mapping
• references/xcode-integration.md - XCode setup
• scripts/generate-xcframework.sh - Build all iOS targets

Differentiation: iOS platform specialization with Amethyst iosMain patterns, Quartz framework setup.

---

6. desktop-expert ✅ DRAFT COMPLETE

Focus: Desktop UX, window management, Compose Desktop APIs, OS-specific conventions

SKILL.md sections:

• Desktop entry point: application {} DSL
• Window management: WindowState, positioning, multi-window
• Menu system: MenuBar, keyboard shortcuts (OS-aware)
• System tray: minimize to tray
• Desktop navigation: NavigationRail pattern (vs Android bottom nav)
• File system: Desktop.getDesktop(), file pickers, drag-drop
• Desktop UX principles: keyboard-first, native feel, tooltips
• OS-specific behavior: macOS vs Windows vs Linux
• Platform detection: PlatformDetector utility
• Packaging: DMG, MSI, DEB distribution

Bundled resources:

• references/desktop-compose-apis.md - Complete Desktop API catalog (Window, Tray, MenuBar, Dialog, etc.)
• references/desktop-navigation.md - NavigationRail vs BottomNav patterns
• references/keyboard-shortcuts.md - Standard shortcuts by OS with DesktopShortcuts helper
• references/os-detection.md - Platform detection, file paths, system integration

Differentiation: Desktop-only APIs, OS conventions (Cmd vs Ctrl), NavigationRail, delegates build to gradle-expert and shared code to kotlin-multiplatform/compose-expert.

Status: ✅ SKILL.md + 4 references created at .claude/skills/desktop-expert/

10-Step Progress:

1. ✅ UNDERSTAND - Defined desktop usage scenarios
2. ✅ EXPLORE - Analyzed desktopApp/ module patterns (Main.kt, FeedScreen.kt, LoginScreen.kt)
3. ✅ RESEARCH - Compose Desktop APIs, OS-specific UX conventions (JetBrains docs, HIG)
4. ✅ SYNTHESIZE - Extracted desktop principles from codebase
5. ✅ DRAFT - Created SKILL.md + 4 reference files
6. ✅ SELF-CRITIQUE - Reviewed against 4 Core Truths (all PASS)
7. ✅ ITERATE - Draft complete (skipping deep iteration for now)
8. ⏸️ TEST - Deferred to later (requires real desktop scenarios)
9. ⏸️ FINALIZE - Deferred to later
10. ✅ DOCUMENT - Updated plan

---

7. android-expert ✅ DRAFT COMPLETE

Focus: Android platform APIs, navigation, permissions, Material Design

SKILL.md sections:

• Android module structure: amethyst/ layout
• Navigation: Navigation Compose, bottom nav
• Permissions: runtime (camera, biometric)
• Platform APIs: Intent, Context, ContentResolver
• Lifecycle: Lifecycle-aware, ViewModel
• Material Design: Android Material 3
• Build config: Proguard, R8
• Android UX: mobile-first patterns

Bundled resources:

• references/android-navigation.md - Navigation Compose
• references/android-permissions.md - Permission handling
• references/proguard-rules.md - Proguard explanation
• scripts/analyze-apk-size.sh - APK optimization

Differentiation: amethyst module structure, Android vs desktop patterns, Amethyst conventions.

Status: ✅ SKILL.md + 3 references + 1 script created at .claude/skills/android-expert/

10-Step Progress:

1. ✅ UNDERSTAND - Defined Android usage scenarios
2. ✅ EXPLORE - Analyzed amethyst/ module patterns
3. ✅ RESEARCH - Android best practices + KMP Android patterns
4. ✅ SYNTHESIZE - Extracted Android principles from codebase
5. ✅ DRAFT - Initialized skill, created resources
6. ✅ SELF-CRITIQUE - Reviewed against 4 Core Truths (all PASS)
7. ✅ ITERATE - Draft complete (skipping deep iteration for now)
8. ⏸️ TEST - Deferred to later
9. ⏸️ FINALIZE - Deferred to later
10. ✅ DOCUMENT - Updated plan

---

8. nostr-expert

Focus: Nostr protocol, NIPs, Quartz architecture, event patterns

SKILL.md sections:

• Quartz architecture: package structure by NIP (57 NIPs implemented)
• Event anatomy: IEvent, Event, kinds, tags (verified in TextNoteEvent.kt)
• NIP implementation patterns: Event class, tags, builders
• Common event types: TextNoteEvent, MetadataEvent, ReactionEvent
• Tag patterns: aTag, eTag, pTag builders
• Relay client: WebSocket, subscriptions
• Cryptography: secp256k1, NIP-44 encryption
• Event builders: TagArrayBuilder DSL

Bundled resources:

• references/nip-catalog.md - All 57 NIPs with code links
• references/event-hierarchy.md - Event class diagram
• references/tag-patterns.md - Tag builders from nip01Core/tags/
• scripts/nip-lookup.sh - Find NIP implementation files

Differentiation: nostr-protocol agent = NIP specs. This skill = Quartz implementation (57 NIPs), code patterns.

---

Implementation Workflow

Using skill-creator 10-step methodology per skill:

Overall Plan:

1. UNDERSTAND ✅ - 8 skills defined, user clarifications obtained
2. EXPLORE ✅ - Codebase analyzed via Explore agent
3. RESEARCH ✅ - Domain patterns identified via Plan agent
4. SYNTHESIZE ✅ - Skills designed above

Per-Skill Implementation:

• kotlin-multiplatform: ✅ COMPLETED
• android-expert: ✅ DRAFT COMPLETE
• desktop-expert: ✅ DRAFT COMPLETE
• kotlin-expert: ✅ DRAFT COMPLETE
• Remaining 4 skills: Pending (gradle-expert, compose-expert, ios-expert, nostr-expert)

Critical Files Referenced

Build patterns:

• /quartz/build.gradle.kts:132-149 - jvmAndroid source set
• /commons/build.gradle.kts - Shared UI setup

Code patterns:

• /quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip10Notes/TextNoteEvent.kt - Event structure
• /commons/src/jvmAndroid/kotlin/com/vitorpamplona/amethyst/commons/account/AccountManager.kt - StateFlow pattern
• /quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/Platform.kt - expect/actual

Documentation:

• /docs/shared-ui-analysis.md - UI migration strategy

Output Location

.claude/skills/<skill-name>/ for each skill

Next Steps

1. ✅ Save this plan as .claude/core-skills-plan.md for reference
2. ✅ Completed kotlin-multiplatform skill
3. ✅ Completed android-expert skill (DRAFT)
4. ✅ Completed desktop-expert skill (DRAFT)
5. ⏳ Next: Pick one of the remaining 5 skills:
   • gradle-expert - Build optimization, dependency resolution
   • kotlin-expert - Coroutines, Flow, sealed classes
   • compose-expert - Shared composables, state management
   • ios-expert - iOS platform patterns, XCFramework
   • nostr-expert - Nostr protocol, NIPs, Quartz

Current Focus: 3 skills completed

Completed:

• kotlin-multiplatform ✅
• android-expert ✅
• desktop-expert ✅

Remaining: 5 skills

Ready to start next skill when requested.