kirocrew-app-dev

KiroCrew App Development

Guide for building external KiroCrew apps that work reliably across KiroCrew versions without depending on buggy lifecycle hooks or skill scanner behavior.

When to Use

• User says "create a kirocrew app", "build an app", "make an app for kirocrew"
• User says "package this as an app", "publish this to the app store"
• User is building UI pages, crons, or skills that should be distributable

App Structure

my-app/
├── app.json              # Manifest (required)
├── ui/
│   ├── index.mjs         # ESM React component (default export)
│   └── icon.svg          # Sidebar icon (SVG or PNG)
├── skills/
│   └── my-skill/
│       └── SKILL.md      # Skill spec
├── scripts/
│   ├── install.sh        # Optional accelerator (NOT required)
│   └── uninstall.sh      # Cleanup script
└── README.md             # Optional docs

app.json Manifest

{
  "name": "my-app",
  "displayName": "My App",
  "version": "1.0.0",
  "description": "What it does in one sentence.",
  "author": "login",
  "tags": ["relevant", "tags"],
  "skills": [
    "skills/my-skill"
  ],
  "crons": [
    {
      "name": "my-cron",
      "message": "FIRST (self-heal, run these bash commands silently): ... THEN do the actual work.",
      "every": 900,
      "silent": true,
      "persistent_session": false
    },
    {
      "name": "market-open",
      "message": "Summarise the overnight tape.",
      "cron_expr": "30 9 * * 1-5",
      "timezone": "America/New_York",
      "skip_dates": ["2026-12-25"]
    }
  ],
  "permissions": {
    "mcpTools": ["local_knowledge_search", "send_message"],
    "network": true
  },
  "ui": {
    "entry": "index.mjs",
    "pages": [
      {
        "route": "/my-app",
        "label": "My App",
        "iconUrl": "icon.svg"
      }
    ]
  },
  "setup": {
    "onInstall": "scripts/install.sh",
    "onUninstall": "scripts/uninstall.sh"
  }
}

Critical Rules

Field	Rule	Why
skills	Use string paths ["skills/my-skill"]	Object format [{name, path}] breaks — parser stringifies dicts
permissions	Must be an object with keys api / events / mcpTools / storage / network / memory / cron — not a flat list	AppManifest.from_dict only calls Permissions.from_dict when the value is a dict; a list silently parses to an empty Permissions(), granting nothing
resources	Must be array of strings ["tool1", "tool2"]	Object format or nested arrays break resource resolution
ui.entry	Must be .mjs ESM module	.html not in allowed extensions
ui.pages[].iconUrl	Use icon.svg file path	String icon field only works for builtin apps
displayName	Required	Gateway uses it for UI display
version	Semver string	Used by update-check crons for comparison
crons[].timezone	IANA zone name; omit it only when the hour is zone-agnostic	An empty timezone falls back to the gateway config's zone and then to UTC, so "cron_expr": "0 6 * * *" without it fires at 06:00 UTC — the wrong calendar day for most users. A per-USER zone is not manifest data: pass timezone= to ctx.cron.add_job instead
crons[].skip_dates	Zero-padded YYYY-MM-DD, evaluated in timezone	"2026-1-1" parses but never matches the padded fire-time rendering, so the skip silently does nothing. Both fields are rejected at manifest validation, not at fire time