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 ✅ COMPLETED

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
• references/version-catalog-guide.md - Version catalog patterns
• references/common-errors.md - Troubleshooting guide
• 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).

Status: ✅ SKILL.md (549 lines) + 4 references + 2 scripts created at .claude/skills/gradle-expert/

---

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 ✅ COMPLETED

Focus: Shared composables, state management, animations, Material3

SKILL.md sections:

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

Bundled resources:

• references/shared-composables-catalog.md - Complete catalog with patterns
• references/state-patterns.md - State hoisting, derivedStateOf examples
• references/icon-assets.md - ImageVector patterns, roboBuilder DSL
• scripts/find-composables.sh - Grep @Composable utility

Differentiation: Multiplatform Compose patterns, shared vs platform UI philosophy, Amethyst conventions (robohash, custom icons). Delegates navigation to platform experts, defers Kotlin language details to kotlin-expert.

Status: ✅ SKILL.md (578 lines) + 3 references + 1 script created at .claude/skills/compose-expert/

---

5. ios-expert

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

SKILL.md sections:

• iOS source sets: iosMain, 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 ✅ COMPLETED

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
• EventTemplate & TagArrayBuilder DSL patterns
• Common event types: TextNoteEvent, MetadataEvent, ReactionEvent, Addressable events
• Tag patterns: e-tag, p-tag, a-tag, d-tag with builders
• Threading (NIP-10): reply/root markers
• Cryptography: secp256k1 signing, NIP-44 encryption
• Bech32 encoding: npub, nsec, note, nevent
• Event validation & verification
• Common workflows: publishing, querying, zaps, gift-wrapped DMs

Bundled resources:

• references/nip-catalog.md - All 57 NIPs with package locations (179 lines)
• references/event-hierarchy.md - Event class hierarchy, kind classifications (293 lines)
• references/tag-patterns.md - Tag structure, TagArrayBuilder DSL, parsing (251 lines)
• scripts/nip-lookup.sh - Find NIP implementations by number or search term

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

Status: ✅ SKILL.md (552 lines) + 3 references + 1 script created at .claude/skills/nostr-expert/

---

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
• gradle-expert: ✅ COMPLETED
• kotlin-expert: ✅ COMPLETED
• compose-expert: ✅ COMPLETED
• desktop-expert: ✅ COMPLETED
• android-expert: ✅ COMPLETED
• nostr-expert: ✅ COMPLETED
• ios-expert: ⏸️ DEFERRED (iOS not yet implemented in AmethystMultiplatform)

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 gradle-expert skill
4. ✅ Completed kotlin-expert skill
5. ✅ Completed compose-expert skill
6. ✅ Completed desktop-expert skill
7. ✅ Completed android-expert skill
8. ✅ Completed nostr-expert skill
9. ⏸️ Deferred ios-expert (iOS not yet implemented in codebase)

Current Status: 7/8 Skills Completed

Completed Skills (Auto-loaded from .claude/skills/):

1. ✅ kotlin-multiplatform (KMP architecture, jvmAndroid pattern, expect/actual)
2. ✅ gradle-expert (Build system, dependencies, version catalog, troubleshooting)
3. ✅ kotlin-expert (Flow state, sealed classes, @Immutable, DSL builders)
4. ✅ compose-expert (Shared composables, state management, Material3, ImageVector)
5. ✅ desktop-expert (Desktop UX, window management, Compose Desktop APIs)
6. ✅ android-expert (Android platform APIs, navigation, permissions)
7. ✅ nostr-expert (Nostr protocol, Quartz implementation, NIPs, events, tags)

Deferred:

• ⏸️ ios-expert (iOS not implemented yet in AmethystMultiplatform)

Skill Loading

All completed skills are automatically loaded when this project opens. Skills are auto-discovered from .claude/skills/ directory.

To manually verify skills are loaded:

ls -1 .claude/skills/

Should show:

• android-expert/
• compose-expert/
• desktop-expert/
• gradle-expert/
• kotlin-expert/
• kotlin-multiplatform/
• nostr-expert/

---

Phase 2 (2026-04): Audit & Expansion

After a full audit of the skill library, the following changes were made:

Stale references fixed

• CLAUDE.md tech-stack versions updated to Compose 1.10.3 / Kotlin 2.3.20.
• kotlin-multiplatform reframed iOS as a mature target (not future) and added secp256k1-kmp 0.23.0 version notes.
• desktop-expert Main.kt line references rewritten to match current layout (Main.kt grew from ~270 to ~1341 lines; NavigationRail moved to ui/deck/SinglePaneLayout.kt:97); the obsolete "hardcoded ctrl = true anti-pattern" section replaced with a note that isMacOS branching is now applied throughout.

Redundant files removed

• .claude/skills/compose-desktop.md deleted (superseded by desktop-expert/). quartz-kmp.md kept as a small breadcrumb pointer.

New references added to existing skills

• nostr-expert/references/nip19-bech32.md — Nip19Parser, Bech32Util, TlvBuilder, entities.
• nostr-expert/references/event-factory.md — EventFactory dispatch + registering a new kind.
• nostr-expert/references/crypto-and-encryption.md — EventHasher, Secp256k1Instance, NIP-44, SharedKeyCache.
• nostr-expert/references/large-cache.md — LargeCache<K,V> + ICacheOperations.
• kotlin-expert/references/common-utilities.md — NumberFormatters, TimeUtils, Hex, PubKeyFormatter, CoroutinesExt.launchIO, etc.
• compose-expert/references/rich-text-parsing.md — RichTextParser, UrlParser, GalleryParser, NIP-92 imeta.
• android-expert/references/image-loading.md — Coil 3.x setup, custom fetchers, MyAsyncImage, RobohashAsyncImage.

New skills created

• account-state/ — Account.kt (50+ StateFlow properties) and LocalCache.kt event store.
  • references/account-state-flow.md, references/local-cache.md
• relay-client/ — ComposeSubscriptionManager, filter assemblers, preloaders (MetadataPreloader, MetadataRateLimiter).
  • references/filter-assemblers.md, references/preloaders.md
• feed-patterns/ — FeedFilter, AdditiveComplexFeedFilter, FeedViewModel hierarchy in commons/.
  • references/feed-filter-composition.md, references/viewmodel-base-classes.md
• auth-signers/ — NostrSigner abstraction across NostrSignerInternal, NostrSignerRemote (NIP-46), NostrSignerExternal (NIP-55).
  • references/nip46-remote-signer.md, references/nip55-android-signer.md

Updated skills directory (Phase 2)

- android-expert/
- auth-signers/                (new)
- account-state/               (new)
- compose-expert/
- desktop-expert/
- feed-patterns/               (new)
- find-missing-translations/
- find-non-lambda-logs/
- gradle-expert/
- kotlin-coroutines/
- kotlin-expert/
- kotlin-multiplatform/
- nostr-expert/
- quartz-integration/
- relay-client/                (new)
- quartz-kmp.md                (breadcrumb pointer)

Still deferred

• ⏸️ ios-expert — iOS targets are mature but iOS-specific UI work hasn't surfaced yet in this repo.