cmp-feature
Skill0 starsChanged 3 days agoMITView on GitHub
Use when adding a new screen, feature module or data source to this Compose Multiplatform app — creating or filling feature/<name> with contract, domain, data and presentation layers, a new ViewModel with Route and Content, a repository backed by Ktor, Room or DataStore, a navigation destination, or the Koin wiring for any of these.
In this repository20 other files it gives its agents.
- compass-kit/CLAUDE.mdCLAUDE.md
- unity-kit/CLAUDE.mdCLAUDE.md
- backend-new-projectSkill
- cmp-backendSkill
- cmp-code-rulesSkill
- cmp-commitSkill
- cmp-design-rulesSkill
- cmp-design-to-codeSkill
- cmp-detektSkill
- cmp-gatesSkill
- cmp-maestroSkill
- cmp-new-projectSkill
- cmp-testingSkill
- cmp-verifySkill
- game-balanceSkill
- game-briefSkill
- game-lookSkill
- game-new-projectSkill
- game-releaseSkill
- game-smokeSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 2 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
Look in settings.gradle.kts first.
- Distinctive: line 24
When Compass started this run, its prompt names the module to use.
- Very specific: line 70
Every module's @Module @ComponentScan classes are registered in appModules() in initKoin.kt (older projects: in the buildList inside …
- Very specific: line 76
Not every layer needs code.
- Very specific: line 101
Before deleting GuideScreen.kt, keep what the stores require, which it used to reach:
- Very specific: line 149
Only when core/network exists.
- Very specific: line 161
Only when the app needs local storage.
- Distinctive: line 168
Before the first release, schema version 1 may change freely.
- Very specific: line 191
No DTO or entity appears in domain or presentation.
- Very specific: line 197
Write the files with Write and Edit.
- Very specific: line 199
Do not ask which layers to create.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Adding a screen or a feature
This project uses one Gradle module per layer: feature/<name>/{contract,domain,data,presentation}.
The code rules for what goes inside the files are in cmp-code-rules.
1. Decide where it goes
- Something with its own data and its own destination is a feature module. A screen that only
shows another view of an existing feature's data goes into that feature's
presentation. - Look in
settings.gradle.ktsfirst. The generator may already have created the module. From the template release with the blank guide screen on, every planned feature is a complete module:contract/Screens.kt(<Name>Destination),presentationwith<Name>Screen(Route + Screen),<Name>UiState,<Name>Actions,<Name>ViewModel,<Name>Providerand<Name>Entry, and an empty@Moduleindataanddomain— all three registered inappModules(). Projects generated before that have starter files only in the first planned feature and empty shells (fourbuild.gradle.kts, no sources) for the rest. Fill an existing module; do not create a parallel one. - When Compass started this run, its prompt names the module to use. Follow it.
2. Inspect before writing
- The four
build.gradle.ktsfiles of the existing feature: which convention plugin each applies (libs.plugins.feature.<layer>.plugin) and which project dependencies it declares. - The package root, read from
contract/Screens.kt. - The Koin module class(es) under
*/di/and their lines inshared/.../di/initKoin.kt. shared/.../MainScreen.kt: the start destination and how navigation providers are collected.- Which
core/*modules exist (logging,network,database,presentation,designsystem,multilang); the sections below apply only to what is there.
3. Skeleton
Full tree, build files and the checklist for a brand-new module: references/layout.md.
feature/<name>/contract/ Screens.kt: destinations (@Serializable, NavigationCommand.Destination)
feature/<name>/domain/ model/, repository/<Name>Repository.kt, usecase/ (@Factory), di/<Name>DomainModule.kt
feature/<name>/data/ repository/<Name>RepositoryImpl.kt (@Single(binds = ...)), model/ (DTOs), mapper/, di/<Name>DataModule.kt
feature/<name>/presentation/ ui/<Name>Screen.kt (Route + Content), ui/<Name>ViewModel.kt, ui/<Name>UiState.kt,
ui/<Name>Actions.kt, ui/<Name>TestTags.kt, di/<Name>PresentationModule.kt,
navigation/<Name>Provider.kt, navigation/<Name>Entry.ktOn a blank app, <Name>Entry (a FeatureEntry) puts a button for the module on GuideScreen,
which opens the module's destination. GuideScreen is a developer placeholder the app opens on
until you replace it (section 4), not a screen of the app. Projects generated before the blank
guide screen release have no <Name>Entry and no FeatureEntry.
From the deep link template release on, every generated module also has
presentation/navigation/<Name>DeepLink.kt: a DeepLinkRoute (core/navigation) with
@Single(binds = [DeepLinkRoute::class]), @Named("<Name>DeepLink") and pattern = "<name>", so
<scheme>://<name> (scheme = project name in lower case) opens the module's destination. To link
to a screen with an argument, set pattern = "<name>/{id}" and return the destination from
fun destination(arguments: Map<String, String>): NavigationCommand.Destination?
(arguments["id"]); return null for a missing or invalid value, and the link only opens the app.
Validate the argument (a link is user input). Do not use navDeepLink; links go through
DeepLinkHandler and NavigationManager.
- Packages follow the generated files:
<rootPackage>.feature.<name>.<layer>(projects generated before the blank guide screen release:<rootPackage>.<name>.<layer>) plus the sub-package (...feature.<name>.presentation.ui), all lowercase. Copy the root fromScreens.kt; do not invent one. - A new module is added to
settings.gradle.kts(include(":feature:<name>:<layer>")) and to thecommonMaindependencies ofshared/build.gradle.kts(implementation(projects.feature.<name>.<layer>)). - Every module's
@Module @ComponentScanclasses are registered inappModules()ininitKoin.kt(older projects: in thebuildListinsideinitKoin). New projects already have presentation, data and domain registered; in older ones add the data and domain modules when those layers get classes. - Dependencies point inward:
presentation → domain,presentation → contract,data → domain. Another feature is reached only through itscontract. - Not every layer needs code. A screen with no data of its own leaves
domainanddataempty; leave a generated empty module as it is, and do not create one you do not need.
4. Navigation
This template navigates through Koin-registered graph providers and a NavigationManager, not
through callbacks or a passed-down NavController.
- Destinations live in
contract/Screens.kt:@Serializable data object XDestinationor@Serializable data class XDestination(val id: String), both implementingNavigationCommand.Destination. Arguments are simple values such as ids, never whole objects. - The feature's
presentation/navigation/<Name>Provider.ktimplementsNavGraphProviderand registerscomposable<XDestination> { XRoute() }for each destination.MainScreencollects every provider from Koin, so a new destination needs no edit inshared. Only the start destination is set inMainScreen.kt. - A blank app generated from the blank guide screen release on starts at
GuideDestination, the developer placeholder. When you build the app, point the start destination inshared/.../MainScreen.ktat the app's first destination (sharedalready depends on every feature'scontract): thestartvalue, which with the backend is the argument ofrememberSessionStart(GuideDestination, …)(the sign-in gate returns there after sign-in). Then deleteGuideScreen.ktand, inMainScreen.kt, thecomposable<GuideDestination> { ... }block, theentriesanduriHandlerlines and the imports they leave unused. Do not delete theReviewRequestEffect()line inMainScreen.kt; it passes in-app review requests on. The About dialog onGuideScreengoes with it;core/aboutstays (its licences screen and the legal URLs are still used). The<Name>Entryclasses may stay or go. - Before deleting
GuideScreen.kt, keep what the stores require, which it used to reach:- With the backend (
feature/accountexists): a way from the app's own screens (a settings or profile entry) toAccountSettingsDestination. It holds account deletion and the privacy and terms links; App Store and Google Play reject an app with accounts but no in-app deletion. ReferenceAccountSettingsDestinationdirectly; theFeatureEntrylist GuideScreen showed does not count. - With insights (
core/insightsexists): keepInsightsConsentDialoginMainScreen.ktand putInsightsConsentSettings(the analytics and crash report switches) in the app's own settings screen; GuideScreen's About dialog held them. - Without the backend: show the privacy and terms links (
AppInfo.legalLinksfromcore/about) on the app's own settings or about screen; GuideScreen's About dialog held them, and the App Store requires an in-app privacy policy link. - Fill
PRIVACY_POLICY_URLandTERMS_URLincore/about/.../LegalUrls.kt; while they are empty the links stay hidden.
- With the backend (
- The ViewModel navigates with the injected
NavigationManager:NavigationCommand.NavigateTo(XDestination(id)),NavigateUp,PopBackStackTo(...). - The ViewModel reads its arguments from
SavedStateHandleby name:private val id: String = checkNotNull(savedStateHandle[XDestination::id.name]) { "id missing" }.toRoute<XDestination>()works in the app but fails the JVM host test (Bundlenot mocked); it stays for customNavTypearguments. Details:references/screen.md. - To open another feature's screen, the presentation module depends on that feature's contract
(
implementation(projects.feature.<other>.contract)).
5. Presentation
Code shapes, imports and test tags: references/screen.md.
- The generated
ui/<Name>Screen.ktis a placeholder screen (a Route and a private<Name>Screenwith a Back button). Replace its content with the real Route and Content, and make the provider call the Route. - The Route (
internal) takes the ViewModel fromkoinViewModel()and collects state. The Content (private) is stateless and draws loading, empty, error and content. - The screen root and every interactive element get a
Modifier.testTag(...)from constants in<Name>TestTags;cmp-maestrobuilds the walkthrough on these tags. - A module that gets
src/commonMain/composeResources/(strings, drawables, fonts) must also enable Android resources in its build file (references/screen.md, "Resources"). Without it both gates stay green, but the files are left out of the APK and the app fails on Android. - Previews: none in
commonMain(seereferences/screen.mdfor the Android-only option).
6. Data
Details: references/data.md. The repository interface lives in domain, the implementation in
data. Reads are Flow<T> or suspend functions; failures come back typed. Mappers are
extension functions (fun XDto.toDomain(): X) that do not change their input. No silent
fallbacks.
7. Network
Only when core/network exists. Details: references/network.md.
- Reuse the
HttpClientfromcore/network'sNetworkModule; never build a second client. The platform engines stay as the template set them. - DTOs are
@Serializable; the client already ignores unknown keys. - The base URL is set in
core/network'sApiConfig.kt(debug and release; older projects:NetworkModule). - Network failures become typed errors in
data. - An API that needs a key is never written into source. If no key-free public API fits, use fake data and say so in your summary.
8. Persistence
Only when the app needs local storage. Details: references/persistence.md.
- DataStore already exists in
core/databasewhen the project was generated with it; reuse the single instance from Koin. - Room is not in the template. Add it to
core/databasethe wayreferences/persistence.mddescribes; the Room compiler generates the database constructor'sactuals. - DAOs read with
Flowand write withsuspend. Entities do not leavecore/databaseanddata. - Before the first release, schema version 1 may change freely. After a release every schema change needs a migration; no destructive fallback.
9. Koin
Details and runtime diagnosis: references/koin.md.
- Annotations and imports:
cmp-code-rules, section 6. - A class is only resolvable if its Gradle module is on
shared's dependency list and its@Moduleis registered ininitKoin.kt. - A dependency provided by another Gradle module is marked
@Provided(or that module is included), or KSP stops withUnreachable definition. - A dependency cycle (A needs B, B needs A) is reported, not hidden.
- The template turns on Koin's compile-time check in KSP. Keep it on.
NoDefinitionFoundExceptionat runtime: go through the order inreferences/koin.md.
Done when
- New modules are in
settings.gradle.ktsandshared/build.gradle.kts, and every new@Moduleclass is ininitKoin.kt. - Each new destination is registered by a provider and reachable: something navigates to it, or it
is the start destination. A
GuideScreenbutton does not count for an app you ship: that app starts at its own first destination, not atGuideDestination(section 4). - No DTO or entity appears in
domainorpresentation. - The screen's
<Name>TestTagsexist and are applied. - The Android gate is green (
cmp-gates android); the iOS gate runs on the schedule incmp-verify, section 2.
Headless runs
- Write the files with Write and Edit. Run the Android gate (
cmp-gates android) once the screen or module's files are in place, not after every file and not only at the end (cmp-verify, section 2). - Do not ask which layers to create. Choose by need and list the choice under
Assumptionsin your final message.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

