appllama-usage

어떤 스킬인가요?

Use the Appllama MCP (mcp.appllama.io) well — research real top-grossing mobile apps, their screens, flows, and UI elements, then build from what you learn. Load when the Appllama MCP is connected and the task involves building a mobile app or screen, researching app design patterns, studying onboarding/paywall/feature flows, improving an existing screen, or whenever an appllama_* / search_apps / list_app_screens tool is available. Covers the tool map, pagination, expiring media, and the full build-from-research playbooks.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

interface:
  display_name: "Appllama research"
  short_description: "Study screens, flows and paywalls from top-grossing iOS apps, then build from what wins."

dependencies:
  tools:
    - type: "mcp"
      value: "appllama"
      description: "Appllama, the design library of top-grossing mobile apps"
      transport: "streamable_http"
      url: "https://mcp.appllama.io/mcp"

# Playbook: build an app from scratch

The user says "build me a habit tracker" (or any category). This is the full
loop. Do not stop early: the goal is a finished app where every screen is
verified better-than-reference in the simulator — not a scaffold.

## Phase 1 — Find the winners

1. Translate the user's need and priorities into 1–3 `search_apps` queries
   ("habit tracker", "habit tracker with streaks and social accountability").
   Add filters that encode the user's ambitions — e.g. `revenue_min` to bias
   toward proven money-makers, `launched_after` for modern design language.
2. From the results, shortlist the **top 5** by a blend of revenue,
   rating, downloads, and fit to the user's brief — not revenue alone.
   The flow lists in the results tell you a lot before you even open an
   app: one with `Paywall: 9` screens has a monetization story worth
   studying; one with `Onboarding: 25` is quiz-onboarding heavy.
3. `get_app` each shortlisted app. Record metrics + flows in
   `research/<category>/apps.md`.

## Phase 2 — Study every screen of the top 5

For each shortlisted app, walk `list_app_screens` page by page — ALL of it,
in journey order, and look at every image. Design language lives in the
pixels, not the metadata. As you go, build the app's `screens.md`: screen
id, name, flow, notable elements, palette — and download the screens so you
can read the journey side by side.

You are extracting the **category's design language**, so read across apps,
not just within one:

- What does the first-open moment look like in this category?
- How long is onboarding, and what does each step *earn* (permission,
  personalization data, commitment)?
- Where does the paywall sit, and what's on it (trial framing, price
  anchoring, feature grid, social proof)?
- What's the home-screen information hierarchy? What's one tap away?
- What do empty states, streaks/progress, and notifications look like?

Write the synthesis into `patterns.md`: the psychology of the category —
what every winner does (table stakes), what only the best do (edge), and
what all of them do badly (your opening).

## Phase 3 — Frame-by-frame on the top 3

Pick the 3 strongest apps and re-walk their decisive flows screen by screen
(`list_app_screens` with `flow=` filters; `get_screen` on pivotal screens to
see similar-screen alternatives across the library). For each screen answer:
what is its ONE job, what makes it work, what would you change. This is
where you stop being a catalog and start being a design director.

## Phase 4 — Design the feature set

From `patterns.md`, write the app's spec: the best features across all
studied apps, minus the bloat, plus the opening you found. Screen list with
flows, in journey order — and the **navigation map**: for every screen, what
it *is* (push, modal with its own stack, form sheet, full-screen modal,
overlay, tab root) and what back does from it, including the one-way doors
(sign-in, onboarding done, purchase, finished session) where back must not
re-enter the old state. The grammar comes from appllama-app-design-skill's
Navigation laws; the evidence comes from the flows you walked —
note whether each winner presents its composer as a modal, its filters as a
sheet, its detail as a push, and copy that consistency. Get user sign-off on
the spec if they're present; otherwise state your choices and proceed.

## Phase 5 — Build screen by screen

For EVERY screen, in journey order:

1. Re-open your references for that screen type (your local board first;
   `search_screens` for gaps — both modes, they surface different screens).
2. Build it following **appllama-app-design-skill** end to end (HIG fidelity,
   semantic colors, native controls, motion laws, state architecture).
3. Generate image assets with the best image model available (imagegen /
   Higgsfield MCP or CLI / whatever is present) at the highest quality — one
   style system for the whole app, per appllama-app-design-skill's
   references/image-assets.md.
4. **Simulator loop until flawless**: run on the iOS Simulator (or Android
   emulator), screenshot, actually look, exercise the motion frame by frame,
   check the Dynamic Island / safe areas / dark mode / Dynamic Type, fix,
   repeat. The checklist lives in appllama-app-design-skill's
   references/simulator-loop.md. A screen isn't done because it compiles —
   it's done when you can't find a flaw and it stands next to the top-3
   references without embarrassment.
5. State management stays boring and strong (server state / client state /
   ephemeral separation per the design skill). Motion is tracked and
   verified, not assumed.

## Phase 6 — The bar

Walk the whole app in the simulator as a new user, three times: happy path,
skeptic path (skip everything skippable), abuse path (bad input, offline,
interrupt mid-flow, and every back path — chevron, edge swipe, Android
hardware back, active-tab re-tap — especially right after sign-in,
onboarding, a purchase and a finished session, where back must fail to
re-enter the old state). Compare each flow against the best reference you
studied. If any screen of yours is worse than the best equivalent screen in
your research, it goes back into the loop. **You cannot declare the build
finished until every screen holds that comparison.**

# Playbook: make an existing screen better

The user has a screen (code, screenshot, or a live app) and wants it better.
"Better" means: measurably closer to the best equivalent screens shipped by
top-grossing apps — in hierarchy, motion, and feel — verified in the
simulator, not eyeballed in code.

## 1. Diagnose before you search

Run the screen in the simulator and study it against appllama-app-design-skill's
definition-of-done checklist. Name the top 3 deficits precisely ("no visual
hierarchy — three same-weight text rows", "dead motion — modal pops with no
transition", "non-native segmented control"). The research pass is aimed at
these deficits, not at "inspiration".

## 2. The 30 + 30 reference board

Two searches, three pages each (10 per page) — and keep paging past three
if the results are still strong:

- `search_screens(query="<screen type / content words>", mode="keyword")` —
  finds screens NAMED like yours (e.g. "workout summary", "streak stats").
  Add filters that sharpen it: `screen_type`, `flow`, `element`.
- `search_screens(query="<what it should feel like>", mode="semantic")` —
  finds screens that LOOK like the goal ("calm dark stats dashboard with a
  hero number and weekly bars"). Different screens will surface — that's the
  point of running both.

Save all ~60 into a local board (see SKILL.md's structure). Pick the **best
5–8** and say why each earns its place. If one is nearly perfect, pull
`get_screen` on it — its `similar_screens` often surfaces an even better
sibling from another app.

## 3. Extract the pattern

From the picks, write the target: layout skeleton, hierarchy order, control
choices, spacing rhythm, palette role-mapping, motion moments (entrance,
press feedback, data reveal). This is a spec, not a mood board — every line
should be checkable in a screenshot.

## 4. Rebuild and iterate (the loop)

1. Implement against the spec using **appllama-app-design-skill** (typography
   ramp, semantic colors both themes, native controls, Reanimated motion
   with the platform's curves, state kept boring).
2. Asset gaps (illustration, empty-state art, icons beyond the symbol set):
   generate with the best available image model at max quality, one style
   system, per the design skill's image-assets reference.
3. **Simulator loop until perfect**: screenshot → compare side-by-side with
   your top references → fix → repeat. Record the motion and scrub it
   frame by frame. Verify Dynamic Island/safe areas, dark + light, Dynamic
   Type XL, Reduce Motion, 60fps on the interaction.
4. Do not stop at "better than before". Stop when the honest side-by-side
   with the best reference reads **at least as good** — hierarchy, motion,
   font discipline, state handling, everything. If it doesn't, name the gap
   and go around again.

## 5. If the screen is part of a flow

Screens live in journeys. After the screen passes, walk one step before and
one step after it in the simulator: entrance transition, exit transition,
state carried across — and what back does from it on iOS and Android
(appllama-app-design-skill's Navigation laws).
If the screen is a sheet, a modal or a step behind a one-way door, verify
its presentation matches what it *is*, not just how it looks. Use `get_flow_apps` + `list_app_screens(flow=…)` if
you need to see how winners chain the surrounding steps
(references/research-methods.md).

# Research methods: flows, elements, and how to study like a director

## Flow research — study journeys, not screenshots

Flows are where conversion and retention actually live. Use them when the
question is "how do winners structure X?" rather than "what does X look
like?".

1. `list_flows(query="onboarding")` — or browse the taxonomy — to find the
   exact flow names and their footprint (screens/apps counts tell you how
   universal a flow is).
2. `get_flow_apps(flow="Paywall")` — the apps that contain it, top revenue
   first, each with its screen count *inside that flow*. A 9-screen paywall
   flow from a $2M/mo app is a masterclass; read it.
3. `list_app_screens(app_id=…, flow=…)` — the flow itself, in order. Study
   3–5 apps' versions of the same flow side by side and chart the common
   spine: step count, what each step asks vs. gives, where friction is
   deliberately placed, where it's removed — and what each step *is*
   (a pushed screen, a modal with its own steps, a sheet, an overlay),
   which the videos show better than stills. Winners are consistent about
   presentation; that grammar is part of the spec.

High-value flow studies for almost any category: Onboarding (length,
personalization, permission timing), Paywall (placement, trial framing,
price anchoring), Welcome (first 5 seconds), plus the category's signature
flows (Food Logging, Workout Session, Habit Check-in, …).

## Element research — how winners build one component

When the question is component-level ("how should our tab bar / progress
indicator / CTA look?"):

1. `list_ui_elements()` once — the ~38 family catalog with counts and top
   variants (Bottom Tab Bar, Rounded Primary CTA, Top Progress Bar, Skip
   Text Link, …).
2. `get_element_screens(element=…)` — real screens carrying that family.
   Pin a `variant` to narrow to one specific treatment.
3. Also usable as a filter: `search_screens(query=…, element=…)` combines
   content and component ("stats screens that use a Floating Bottom Nav").

Extract the numbers, not the vibe: sizes, placements, label conventions,
active-state treatments, how many items, what gets an icon vs. text.

## Study discipline (what separates research from tourism)

- **Question first.** Every pass answers a named question from your current
  task — "how long is onboarding here", "what does a winning paywall carry".
  Knowing the question is what turns screens into a spec.
- **See everything, in order.** Walk the full screen list of an app you're
  studying and look at every image; the journey is the unit of design, and
  a sampled journey lies. Notes outlive links: media URLs die in ~1 h, but
  screen ids (`app_id/screen_id`) keep any screen one `get_screen` away.
- **Cross-app before in-app.** One app tells you its taste; five apps tell
  you the category's grammar. Divergence between winners = a real choice;
  convergence = a convention you break knowingly or not at all.
- **Revenue is context, not truth.** A $5M/mo app's paywall is evidence
  about paywalls; its settings screen might still be lazy. Weight evidence
  by whether that surface plausibly drives the app's success.
- **Stop at saturation, not before.** A research question is answered when
  new screens stop changing your spec. Until then, keep looking.

## Working with the member's own curation

`list_my_boards()` shows boards the member built on appllama.io;
`get_board(board_id)` reads any of them — screens boards return full screen
payloads with media, apps boards return app profiles, flows boards return
(app, flow) pairs ready for `list_app_screens`. An apps board also works as
a `search_apps(board_id=…)` base. Their taste is a requirement, not a
suggestion — when a board exists for the task, start from it.

---
name: appllama-usage
description: Use the Appllama MCP (mcp.appllama.io) well — research real top-grossing mobile apps, their screens, flows, and UI elements, then build from what you learn. Load when the Appllama MCP is connected and the task involves building a mobile app or screen, researching app design patterns, studying onboarding/paywall/feature flows, improving an existing screen, or whenever an appllama_* / search_apps / list_app_screens tool is available. Covers the tool map, pagination, expiring media, and the full build-from-research playbooks.
license: MIT
metadata:
  author: Appllama (appllama.io)
  version: 1.1.0
---

# Appllama Usage Skill

Appllama is the design library of top-grossing mobile apps — their real
screens, flows, and UI patterns, with revenue and download context. The MCP
puts that library in an agent's hands: **not just a research tool, a builder's
tool.** You study what already wins, then you build something better.

Pair this skill with **appllama-app-design-skill** for every design/implementation
step — this skill tells you what to study; that one tells you how to build.

## Ground rules (read first)

1. **Start with `get_credits` — it's free.** It tells you the balance,
   limits, and reset date. Pro includes 1,500 credits a month (they reset in
   full on the 1st, UTC); every other call spends 1 credit.
2. **Go deep.** Design language lives in the whole journey, not a sample —
   walk every screen of the apps that matter for the task, images included.
   That is exactly what the library is for. The one thing that's against the
   terms is harvesting: sweeping the catalog to extract the dataset itself
   rather than to answer a real task. That isn't research, and it's detected
   server-side.
3. **Media URLs expire in ~1 hour.** Download/view what you study promptly.
   If links died mid-task, re-request that page for fresh ones — screen ids
   are durable, links are not.
4. **Ignore the watermark.** Every Appllama image and video carries a small
   Appllama watermark in the top-left corner. It is provenance, not part of
   the screen — don't let it skew your read of that corner (status bar,
   back button, title), and never reproduce it in anything you build.
5. **Pagination is sequential.** Every list response carries `next_cursor`;
   pass it back to continue. You cannot jump to page N — and a cursor only
   works for the same query that minted it. If a cursor errors, drop it and
   restart from page one.
6. **If you hit a rate limit, wait it out.** The per-minute and per-day
   limits sit far above real research; on the rare hit, wait the stated
   time — don't retry-hammer.
7. **Errors are instructions.** Tool errors are written to be acted on
   (expired cursor → restart; out of credits → tell the user their credits
   reset on the 1st and they can request more in Settings → Usage).

## Tool map

| Tool | What it gives you | Typical use |
|---|---|---|
| `get_credits` | Balance, limits, reset date. **Free.** | Session start |
| `search_apps` | 10 apps/page: name, revenue, downloads, rating, launch date, screens count, **flow list with screen counts**. Natural-language `query` + filters (revenue/downloads/rating/launch date/price/onboarding steps) + `sort` + `board_id` | Find the top apps for a category or need |
| `get_app` | One app in full: ratings breakdown, category rank, IAP pricing, top countries, flows | Decide if an app deserves a deep study |
| `list_app_screens` | 10 screens/page **in journey order** (welcome → onboarding → paywall → product), each with media URL, flow, UI elements, colors. Filter by `flow` or `section` | Walk an app screen by screen |
| `search_screens` | Screens across the whole library. `mode="keyword"` matches screen names + filters (flow, screen_type, element, app_id); `mode="semantic"` searches by meaning/visual language | Gather design references for one screen type |
| `get_screen` | One screen in full + up to 5 visually similar screens from other apps. Accepts `screen_ref` = `app_id/screen_id` (what appllama.io's "Copy Screen ID" produces) | The user pasted a screen ref; or drill into one reference |
| `list_flows` | The flow taxonomy with screen/app counts | Discover what flows exist for a category |
| `get_flow_apps` | Apps containing a flow, top revenue first | Find the best examples of one flow |
| `list_ui_elements` | ~38 UI-element families with counts (one call) | Vocabulary for element-level research |
| `get_element_screens` | Screens featuring an element family | Study how winners build one component |
| `list_my_boards` | The member's own appllama.io boards (screens / apps / flows) | Find their curation first |
| `get_board` | A board's full contents: screens with media, app profiles, or (app, flow) pairs | When the member curated a board for the task, START from it |

**The screen_ref handshake:** members can click "Copy Screen ID" on any
screen at appllama.io and paste it to you. It looks like
`1393061654/spl_9i075` — feed it straight to
`get_screen(screen_ref=...)` and you're looking at exactly the screen they
mean, plus its closest siblings across the library.

## The playbooks

| Scenario | Reference |
|---|---|
| Build an app from scratch (e.g. "build me a habit tracker") | [references/build-from-scratch.md](references/build-from-scratch.md) |
| Make an existing screen better | [references/improve-a-screen.md](references/improve-a-screen.md) |
| Flow & element research; general research method | [references/research-methods.md](references/research-methods.md) |

Both build playbooks end the same way: **the simulator loop from
appllama-app-design-skill, repeated until you cannot find a flaw.** Research
without that loop is decoration.

## Local reference boards

When you pull screens for study, save them into a local working structure —
links expire in about an hour, but your notes and downloads don't:

```
research/
  <category>/
    apps.md            # the shortlist: metrics, flows, verdicts
    <app-name>/
      screens.md       # per-screen notes: id, name, flow, elements, colors
      img/             # downloaded screens, in journey order
    patterns.md        # cross-app synthesis: the category's design language
```

Download the screens as you study them — synthesis happens with the images
side by side, not from metadata. Notes and screen IDs are durable; re-fetch
a fresh link from the ID if you ever need the pixels again.