Add SKILL.md for AI agent customization
This file provides instructions for AI agents to fork, customize, and build branded versions of Amethyst. Includes: - Prerequisites and environment setup - Step-by-step build workflow - Common customizations (app name, package ID, icons, client tags) - Troubleshooting guide - Distribution options
This commit is contained in:
Centauri
@@ -0,0 +1,230 @@
|
||||
# Amethyst Builder Skill
|
||||
|
||||
Build customized Amethyst Nostr clients for Android. Fork, rebrand, customize, and distribute your own version.
|
||||
|
||||
## Overview
|
||||
|
||||
[Amethyst](https://github.com/vitorpamplona/amethyst) is the premier Nostr client for Android. This skill enables you to:
|
||||
- Create rebranded versions (custom name, package, icons)
|
||||
- Build F-Droid-compatible releases (no Google Play dependencies)
|
||||
- Add or modify features
|
||||
- Sign and distribute APKs
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required Tools
|
||||
|
||||
1. **Java 21** (via SDKMAN)
|
||||
```bash
|
||||
curl -s "https://get.sdkman.io" | bash
|
||||
source "$HOME/.sdkman/bin/sdkman-init.sh"
|
||||
sdk install java 21.0.5-tem
|
||||
sdk use java 21.0.5-tem
|
||||
```
|
||||
|
||||
2. **Android SDK**
|
||||
- Command-line tools from https://developer.android.com/studio#command-line-tools-only
|
||||
- Required components: build-tools, platform-tools, platforms;android-35
|
||||
|
||||
3. **Git** for cloning the repository
|
||||
|
||||
### Environment Setup
|
||||
|
||||
```bash
|
||||
export ANDROID_HOME=$HOME/Android/Sdk
|
||||
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
|
||||
export PATH=$PATH:$ANDROID_HOME/platform-tools
|
||||
```
|
||||
|
||||
## Build Workflow
|
||||
|
||||
### 1. Clone the Repository
|
||||
|
||||
```bash
|
||||
mkdir -p ~/projects/your-app-name
|
||||
cd ~/projects/your-app-name
|
||||
git clone https://github.com/vitorpamplona/amethyst.git .
|
||||
```
|
||||
|
||||
### 2. Create Signing Key
|
||||
|
||||
```bash
|
||||
keytool -genkeypair -v \
|
||||
-keystore ./release-key.jks \
|
||||
-alias your-app \
|
||||
-keyalg RSA -keysize 2048 \
|
||||
-validity 10000
|
||||
```
|
||||
|
||||
Create `keystore.properties` in project root:
|
||||
```properties
|
||||
storeFile=release-key.jks
|
||||
storePassword=your-password
|
||||
keyAlias=your-app
|
||||
keyPassword=your-password
|
||||
```
|
||||
|
||||
### 3. Configure Signing
|
||||
|
||||
Add to `amethyst/build.gradle` inside the `android {}` block:
|
||||
|
||||
```gradle
|
||||
def keystorePropertiesFile = rootProject.file("keystore.properties")
|
||||
def keystoreProperties = new Properties()
|
||||
if (keystorePropertiesFile.exists()) {
|
||||
keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
|
||||
}
|
||||
|
||||
signingConfigs {
|
||||
release {
|
||||
if (keystorePropertiesFile.exists()) {
|
||||
storeFile rootProject.file(keystoreProperties['storeFile'])
|
||||
storePassword keystoreProperties['storePassword']
|
||||
keyAlias keystoreProperties['keyAlias']
|
||||
keyPassword keystoreProperties['keyPassword']
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Update the release buildType to use the signing config:
|
||||
```gradle
|
||||
buildTypes {
|
||||
release {
|
||||
signingConfig signingConfigs.release
|
||||
// ... existing config
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Disable Google Services (Required for F-Droid)
|
||||
|
||||
**⚠️ CRITICAL:** The Google Services plugin fails when you change the package name. For F-Droid builds, disable it.
|
||||
|
||||
Edit `amethyst/build.gradle`, comment out the plugin:
|
||||
```gradle
|
||||
plugins {
|
||||
alias(libs.plugins.androidApplication)
|
||||
alias(libs.plugins.jetbrainsKotlinAndroid)
|
||||
// alias(libs.plugins.googleServices) // DISABLED for F-Droid
|
||||
alias(libs.plugins.jetbrainsComposeCompiler)
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Build
|
||||
|
||||
```bash
|
||||
source "$HOME/.sdkman/bin/sdkman-init.sh"
|
||||
sdk use java 21.0.5-tem
|
||||
./gradlew assembleFdroidRelease
|
||||
```
|
||||
|
||||
**Build time:** ~9 minutes first build, faster on subsequent builds.
|
||||
|
||||
### 6. Locate APKs
|
||||
|
||||
Output directory: `amethyst/build/outputs/apk/fdroid/release/`
|
||||
|
||||
Files generated:
|
||||
- `amethyst-fdroid-arm64-v8a-release.apk` - ARM64 (most phones)
|
||||
- `amethyst-fdroid-universal-release.apk` - All architectures (larger)
|
||||
|
||||
## Customizations
|
||||
|
||||
### Change App Name
|
||||
|
||||
Edit `amethyst/src/main/res/values/strings.xml`:
|
||||
```xml
|
||||
<string name="app_name" translatable="false">YourAppName</string>
|
||||
<string name="app_name_debug" translatable="false">YourAppName Debug</string>
|
||||
```
|
||||
|
||||
### Change Package ID
|
||||
|
||||
Edit `amethyst/build.gradle`:
|
||||
```gradle
|
||||
android {
|
||||
defaultConfig {
|
||||
applicationId = "com.yourcompany.yourapp"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Change Project Name
|
||||
|
||||
Edit `settings.gradle`:
|
||||
```gradle
|
||||
rootProject.name = "YourAppName"
|
||||
```
|
||||
|
||||
### Change App Icon
|
||||
|
||||
Replace icon files in:
|
||||
- `amethyst/src/main/res/mipmap-*/ic_launcher.webp`
|
||||
- `amethyst/src/main/res/mipmap-*/ic_launcher_round.webp`
|
||||
|
||||
### Add Client Tag to Posts
|
||||
|
||||
Make your app identify itself on posts with `["client", "YourAppName"]`.
|
||||
|
||||
**1. Create tag builder extension:**
|
||||
|
||||
Create `quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/tags/clientTag/TagArrayBuilderExt.kt`:
|
||||
```kotlin
|
||||
package com.vitorpamplona.quartz.nip01Core.tags.clientTag
|
||||
|
||||
import com.vitorpamplona.quartz.nip01Core.core.Event
|
||||
import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
|
||||
|
||||
fun <T : Event> TagArrayBuilder<T>.client(clientName: String) =
|
||||
addUnique(arrayOf(ClientTag.TAG_NAME, clientName))
|
||||
```
|
||||
|
||||
**2. Add to TextNoteEvent:**
|
||||
|
||||
Edit `quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip10Notes/TextNoteEvent.kt`:
|
||||
|
||||
Add import:
|
||||
```kotlin
|
||||
import com.vitorpamplona.quartz.nip01Core.tags.clientTag.client
|
||||
```
|
||||
|
||||
In both `build()` functions, add after `alt(...)`:
|
||||
```kotlin
|
||||
client("YourAppName")
|
||||
```
|
||||
|
||||
### Modify Default Relays
|
||||
|
||||
Edit relay configuration in `quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/` or the UI settings files.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### google-services.json error
|
||||
Disable the Google Services plugin (see step 4).
|
||||
|
||||
### Java version error
|
||||
```bash
|
||||
sdk use java 21.0.5-tem
|
||||
java -version # Must show 21.x
|
||||
```
|
||||
|
||||
### Out of memory
|
||||
Edit `gradle.properties`:
|
||||
```properties
|
||||
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=512m
|
||||
```
|
||||
|
||||
### Clean build
|
||||
```bash
|
||||
./gradlew --stop
|
||||
./gradlew clean
|
||||
./gradlew assembleFdroidRelease
|
||||
```
|
||||
|
||||
## Distribution
|
||||
|
||||
Deploy APKs via:
|
||||
- **Surge.sh:** `surge ./releases your-app.surge.sh`
|
||||
- **Zapstore:** Submit to zapstore.dev
|
||||
- **Direct download:** Host on any web server
|
||||
Reference in New Issue
Block a user