Przejdź do treści
Biblioteka skilli
Programowanie · Nauka i wyjaśnianie

app-format

/app-format

Opisuje format pliku aplikacji brain: app.conf, role, playbooki, skille oraz wymogi, które sprawdza narzędzie przy instalacji.

Repozytorium
agent-brain ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
09.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 09.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Opisuje format pliku aplikacji brain: app.conf, role, playbooki, skille oraz wymogi, które sprawdza narzędzie przy instalacji.

Oryginalny opis (EN)

The file contract for a brain app — app.conf, its roles, playbooks and skills, and what brain app check enforces. Use when writing, reviewing or repairing an app, or when brain app install refused one.

Jak działa

  1. Layout
  2. app.conf
  3. Host commands: cli.sh
  4. Studio code: ui/main.js
  5. In the Studio
  6. What brain app check enforces
  7. Whose change is whose
  8. Writing one
  9. App-owned memory
  10. Optional project integrations and workspace catalogues
Sekcje z nagłówków SKILL.md, w oryginale · 248 linii, 2 399 słów
Podgląd SKILL.md
---
name: app-format
description: The file contract for a brain app — app.conf, its roles, playbooks and skills, and what brain app check enforces. Use when writing, reviewing or repairing an app, or when brain app install refused one.
---

# App format

An app is a domain for the brain — SEO, theses, websites — packaged as a folder. It is
installed with `brain app install <name>`, which copies the folder from its repo
(`APPS_SOURCE` in `system/brain.conf`, by default `pshiuu/agent-brain-apps`, one folder per
app) to `$BRAIN_SYSTEM/apps/<name>/` and records the commit in `system/apps.lock` (the
brain's own, not in the base's git).

The brain looks into every installed app the way it looks into `system/` itself: a
playbook, role or skill is found in the base first, then in the apps. Nothing is copied
into the base, so `brain app remove <name>` takes all of it out again. Knowledge the
projects learned stays in `memory/`; removing the app hides the pages tagged with it, and
`brain app forget <name>` moves those to `memory/archive/knowledge/` only when asked.

## Layout

```
seo/
  app.conf          the manifest (below)
  README.md         what the app is for; its page in the Studio and later the app store
  roles.conf        only this app's roles: role engine model [effort]
  roles/<role>.md   their instructions — both halves live in the app (role-format skill)
  playbooks/<name>/ phases, playbook.md, brief.md, inputs, contracts/ (playbook-format skill)
  skills/<name>/    its own skills, each with a SKILL.md
  skills.list       external skills it pulls in, same format as system/skills.list
  knowledge/*.md    starter knowledge: one topic per page, '# <title>' first. Read-only;
                    every project whose scope names the app reads it, an update replaces it.
                    What projects learn goes into memory/knowledge/, never here
  evals/<name>/     a playbook run for real on a fixed input (brain eval run <name>):
                    eval.conf ("playbook <name>"), brief.md (the whole brief), optional
                    sources/ and check.sh (the rubric: "pass|fail <what>" lines)
  test/*.sh         its own tests; `brain app test <name>` runs them (source test/lib.sh)
  cli.sh            optional host commands: `brain <name> <verb>` (below)
  ui/main.js        optional code for the Studio — installing it asks for trust
```

Everything but `app.conf` is optional: an app may be only roles and skills that other
apps build on.

## `app.conf`

One `key value` line each, read with awk like `roles.conf` — never sourced.

```
name      seo                    must equal the folder name
label     SEO & content          shown in the Studio
description Articles that …      one or two sentences for the store (else the README's first paragraph)
icon      file-text              a Phosphor icon name, for its tile in the store
version   1.2.0                  required
brain     >= 2                   the base version it works with; required
requires  web                    other apps it needs installed (space-separated)
kind      academy                a workspace kind it owns (KIND= in a project.env); needs cli.sh
```

What its sandboxes reach and what it needs from the human — each may repeat:

```
mcp      <name> <https-url>                         an MCP server its agents get
secret   <name> basic|bearer <check-url|-> <label>  the key of the mcp server of that name
setting  <key> toggle on|off <label>                a value its skills read
setting  <key> choice a,b,c <label>                 (the first option is the default)
setting  <key> text <default> <label>
allow    <host>[,<host>...]                         hosts its sandboxes may reach
```

- A `secret` is always an MCP server's key, sent as `Authorization: Basic|Bearer <key>`;
  basic asks for a login and password and sends them base64'd. The Studio checks it with a
  GET to `<check-url>` (401/403 is a wrong key), `brain watch` stores it in sbx's secret
  store as `mcp:<name>:token` and registers the server. The agent never sees it. The
  server goes into new sandboxes only once its key is stored.
- An `mcp` line without a secret (a public or OAuth server), and every `allow`, is
  registered by `brain sync-sandbox`. A server name belongs to one app, and not to
  `system/sandbox.conf` too.
- Settings are written by the Studio to `$BRAIN_SYSTEM/config/<name>.conf`, one
  `<key> <value>` line each, outside the app's folder so an update keeps them. A key the
  file does not name has its default; say so in the skill that reads it.
- An app's `secret` and `setting` lines become a Settings section on its page in Admin → Apps.

An unknown key is ignored, so an app may carry lines a later base reads.

## Host commands: `cli.sh`

An app that does more than run playbooks brings a `cli.sh`. The launcher sources it when
it is needed and calls, by name:

| Function | When |
| --- | --- |
| `cmd_<name>` | `brain <name> <verb> [args]` — required in every `cli.sh` |
| `<name>_watch` | every `brain watch` tick (move in what the Studio staged, start a queued run) |
| `<name>_studio_new <slug> <stage-dir>` | the Studio's New form asked for the app's `kind`; `memory/.new/<slug>/` holds what the form wrote. Non-zero leaves `log` there as the error |

Everything else it defines starts with `<name>_`, so nothing it sources replaces a function
of the launcher. It may call these of the launcher's, and no others — the rest changes
without notice: `launch`, `role_cfg`, `sandbox_name`, `project_name`, `slug`, `fill_brief`,
`interactive`, `ask`, `info`, `die`, `terminal`, `running_projects`, `sbx`; and read
`BRAIN`, `SYS`, `MEM`, `DEV`, `PROJECT`, `PDIR`, `PHASE_TIMEOUT`, `MAX_PARALLEL`, `QUEUED`.

A `kind` is how a project that is not a playbook run belongs to the app: its `project.env`
says `KIND=<kind>`, the playbook commands refuse it and name the app, and the Studio's
project list leaves it out. Run markers for the run cap are `memory/projects/<p>/.<name>-running`.

## Studio code: `ui/main.js`

What `ui/app.json` cannot say — whole pages of the app's own — is an ES module the Studio
imports from `/apps/<name>/main.js` (put `{ "type": "module" }` in `ui/package.json` so node
tests can import it too). Its default export is called once with the kit:

| Kit | What it does |
| --- | --- |
| `route(key, fn, active?)` | `#/<key>/<a>/<b>/<c>` renders `fn(a, b, c)`; `active(a)` names the nav item it lights up. The Studio's own keys are taken |
| `nav({ label, items })` | a sidebar group; `items()` runs on every render and returns `[{ href, label, icon, key, n }]` |
| `state`, `refresh()`, `render()` | the live `/api/state` (`state.apps[].projects` lists a kind's projects with their run markers); reload it; draw again |
| `read(project, paths, where)` | many files or folders (`dir/`) in one call. `where`: `work` (the project's folder under `~/dev`), `memory` (its folder in `memory/projects/`) or `app` (the app's own folder, project `null`). Text files come with their content, others with their size; outside the scope is refused |
| `request(project, file, { content \| data, prev, against })` | stages `.<name>-request` (one at a time), `inbox/<file>` (`data`, base64) or `<name>.staged` (with `prev`: refused when the workspace's `against` file changed) in `memory/projects/<p>/`. `<name>_watch` in `cli.sh` takes it from there |
| `create(name, files)` | a new project of the app's kind: `memory/.new/<slug>/` with `files` and the request; `<name>_studio_new` makes it |
| `api`, `upload`, `inputsForm`, `projectTable`, `sorted`, `status`, `titleOf`, `clientName`, `newButton` | the rest of the cockpit, for an app built on the Studio's own pages (the clients app) |
| `frame`, `head`, `card`, `pad`, `table`, `td`, `rowLink`, `empty`, `note`, `toast`, `keep`, `link`, `btn`, `withIcon`, `tagOf`, `watchingNote`, `human`, `ago`, `$`, `icon`, `md`, `graphView`, `readB64` | the Studio's own building blocks, so an app's pages look like the rest |

The cockpit runs no app code on its server: it serves `ui/` as files and answers the two
endpoints above. In the browser the code can call every cockpit API, which is why install
asks for trust. Parse in pure functions that take a `read`, and test them in node against
the cockpit's real `appRead` (the academy's `test/ui.test.mjs` does).

## In the Studio

Admin → Apps lists the installed apps and what `APPS_SOURCE` offers (`memory/.apps-catalog`,
written by `brain watch` / `brain app catalog`: version, label, the first paragraph of the
README, and whether the app brings Studio code, commands or settings). An app installed from
anywhere else (a private repo, a developer's folder) is checked against that source by the
same **Check for updates** (`memory/.apps-updates`), and its Update comes from there too. Install, update,
revert and remove are staged as `memory/.apps-request` and run by `brain watch`; the trust
question becomes a confirm dialog. Install from a repo scans any other repo
(`scan <source>` → `memory/.apps-scan`, same format) and installs what it found with
`from <source> <path>` in the request, trust required. An app at a repo's root, alone in its
own repo, is found by its app.conf `name`. Each app has a page there: its tile, its actions, its
settings and its README rendered, so write the README for the person deciding to install it.

## What `brain app check` enforces

Install and update refuse an app that fails any of these; nothing is left behind.

- `app.conf` exists, `name` matches the folder, `version` is set, `brain >= N` is met.
- Every app in `requires` is installed.
- Every role has both halves inside the app: its `roles.conf` line and `roles/<role>.md`.
  A half in another app or in the base would break the day that one is removed.
- Every skill folder has a `SKILL.md`.
- Every playbook passes `brain playbook check` (its roles resolve across base and apps).
- No playbook, role or skill name is also defined by the base or another app. A name is
  never overridden; rename yours.
- `cli.sh` parses, defines `cmd_<name>`, and defines nothing outside `cmd_<name>` and `<name>_*`.
- `mcp`, `secret`, `setting` and `allow` lines have the shape above; every secret names an
  mcp line of the app; no server name is also another app's or in `system/sandbox.conf`.
- A `kind` has a `cli.sh` to run it, is owned by no other app and is no playbook's name.
- An app with `ui/main.js` installs only after the human trusts it: that code runs in the
  Studio with everything the Studio may do.

## Whose change is whose

An installed app exists three times, and each copy has one owner:

| Copy | Changed by | Where |
| --- | --- | --- |
| the app as published | its developer, by pushing to the apps repo | the repo; `system/apps.lock` pins a commit |
| the app as this brain runs it | this brain: `brain evolve`, Adjust playbook, a model changed in Roles | `system/apps/<name>/` |
| the app as installed, untouched | nobody | `system/apps/.base/<name>/` |

What a brain learns from its runs stays in that brain: `system/apps/` is not in git and
never goes back upstream on its own. `brain app update <name>` merges each file three
ways (base → this brain, base → new version), so local changes survive an update; when
both changed the same lines it stops and installs nothing. `brain app diff <name>` shows
this brain's changes, `brain app revert <name> [file]` drops them, and for the app's
developer `brain app promote <name> [file]` merges them into the apps repo checkout named
by `APPS_DEV` — to read, commit and push, so everyone gets them with their next update.

## Writing one

1. Start from a folder in `pshiuu/agent-brain-apps`, or `brain app install x --from <dir>`
   while you build it — a local folder installs without a repo.
2. Name roles and playbooks for the app (`seo-writer`, not `writer`): names are global.
3. `brain app check <dir>` until it passes, then `brain app test <name>`.


## App-owned memory

The Studio kit also supports `read(null, paths, 'data')` to read
`memory/apps/<app>/`, and `request(null, '.<app>-request', { content })`
to stage an app-wide request there. A pending or claimed request returns 409.
The host app watcher claims and validates it; the Studio never executes host commands.
Use this for workspace registries and context shared by tasks on one app checkout,
while keeping each task's brief and phase evidence in `memory/projects/<task>/`.

Promotion resolves the installed source against APPS_DEV checkouts (space or colon
separated), and refuses an unrelated or ambiguous checkout. A local source promotes
back to its original folder.


## Optional project integrations and workspace catalogues

A host-created project may declare `INTEGRATIONS=agencyos-sync` in project.env.
For several providers, quote the value: `INTEGRATIONS='app-one app-two'`.
Before each `brain run` phase, the launcher calls `<app>_project_check <project>`
from that installed app's cli.sh. Nonzero prevents engine launch. Removing a linked
integration therefore requires unlinking the project explicitly first. Unlinked
projects remain independent. Hooks must start with the app's name. They may prepare
the project's own checkout on this machine (the github app puts it on the task's branch)
but change nothing remote: updates elsewhere remain staged requests. A playbook links
every project made from it with `INTEGRATIONS=<app>` in its `playbook.env`, which
`brain new` copies into `project.env`. The header points engines to the project's
`integration-context.md`. Both engines receive the same context.

An explicitly linked integration may use the ordinary kit read/request methods for
that project's memory; it gains no access to unlinked projects.

A domain app may declare `workspaces <relative-json-path>` in app.conf. Its host code
maintains that JSON in its app data folder, as a list of `{id,label,path,kind,playbooks}`.
Paths identify local code folders, not credentials or commands. Consumers revalidate
the path against their configured workspace roots and discover available playbooks
from installed apps. Catalogues are optional suggestions, never a hard dependency.


## Optional Studio panels

`kit.provide(slot, render)` registers this app once for a named panel slot. The render
function receives a frozen context and returns a DOM node, null, or a promise. It uses
its own kit for scoped reads and staged requests. `await kit.contributions(slot, context)`
returns `{app,content}` or `{app,error}` for each installed provider; one provider failure
does not break another. With no provider installed the result is an empty list.

The `workspace-tasks` slot receives `{path,kind,label}` for the selected code checkout.
Domain apps render contributed panels beside their own local execution history. The
provider owns remote task identity, task routing, workflow selection and update checks;
the domain app does not import private integration code or copy its remote task database.


## Host-only API credentials

`host-credential <name> keypair <site-setting> <label>` asks, on the app's page in Admin,
for an API key and secret that the app's own host code (`cli.sh`) uses: unlike a `secret`,
it is no MCP key and never reaches sbx or an agent. `<site-setting>` names the app's
`setting` that holds the site the pair belongs to; it must be saved first.
The cockpit stages the pair as an exclusive 0600 file,
`$BRAIN/.credentials-inbox/<app>/<name>.request` (gitignored, mounted into no sandbox,
refused by every cockpit read). The app's `<name>_watch` checks it, keeps it wherever it
keeps keys (the macOS Keychain, say), deletes the file and writes only
`{site, connected, message}` to `memory/apps/<app>/<name>-connection.json`, which Admin
shows. The pair is never copied to project memory, settings, logs or a response.

Wersje

W bazie nie ma innych skilli o nazwie app-format.

Migawka bazy z 13.11.2026 · wersja paczki 27dfcbce2a85 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100playbook-format
    Określa format pliku playbooka mózgu (fazy, playbook.md, brief.md) i zasady, dzięki którym playbook faktycznie się uruchamia.
  • 100role-format
    Opisuje, jak pisać rolę mózgu tak, by Claude i Codex ją wykonywały, z dwiema częściami roli, wpływem sformułowań na pracę i kontraktami z BRAIN.md.
  • 94captn-brain
    Optymalizuje kontekst i zużycie tokenów w CLI CaptN-BRAIN, najpierw metodami deterministycznymi.
  • 100brain-sync
    Aktualizuje repozytorium brain w tym samym porządku: pokazuje stan, uruchamia kontrole, zapisuje zmiany w historii i wysyła je po zgodzie.
  • 100brain-dump-review
    Przegląda zgłoszenia Brain Dump wyłącznie przez polecenia CLI, śledząc ustalenia, poprawki i generowanie dema po zakończeniu implementacji, bez MCP.
  • 100contribute
    Prowadzi od pomysłu na zmianę w INITE Brain, opisanego zwykłymi słowami, do zielonego pull requesta, także osoby, które nie programują.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.