# Agent App Agent App is a draft companion standard in the Agent Skills ecosystem for packaging installable agent applications. It describes how a user-facing agent app composes Agent Skills, Agent Knowledge templates, tool requirements, scene entries, artifact contracts, evals, and presentation metadata without moving agent execution into the cloud. Agent Skills answer **how to do work**. Agent Knowledge answers **what trusted knowledge assets are**. Agent App answers **which capabilities, knowledge templates, tools, UI entries, deliverables, and quality gates make up an installable application**. ## Core boundary | Standard | Owns | Entry point | Runtime behavior | | --- | --- | --- | --- | | Agent Skills | Executable workflows, scripts, tools, templates, and procedural instructions. | `SKILL.md` | Activated by the agent after trust checks. | | Agent Knowledge | Source-grounded knowledge assets, status, provenance, and safe context. | `KNOWLEDGE.md` | Loaded as fenced data; never executed. | | Agent App | Installable application composition, dependencies, scenes, permissions, artifact contracts, evals, and presentation. | `APP.md` | Resolved by the host; execution still happens in the host agent runtime through Skills, Knowledge, Tools, and Runtime. | ## Pack shape ```text my-agent-app/ ├── APP.md # required: manifest + app guide ├── skills/ # optional: bundled or referenced Agent Skill packages ├── knowledge-templates/ # optional: required knowledge slots and starter templates ├── workflows/ # optional: scene and workflow definitions ├── tools/ # optional: tool requirements and permission hints ├── artifacts/ # optional: output contracts and viewer hints ├── evals/ # optional: readiness and quality checks ├── assets/ # optional: icons, examples, templates, screenshots └── examples/ # optional: sample workspaces, prompts, and expected outputs ``` ## Runtime contract Compatible hosts should: 1. Discover apps by `APP.md`. 2. Load only catalog metadata first. 3. Install or activate an app only after user, tenant, or workspace consent. 4. Resolve declared Skills, Knowledge templates, Tools, Artifacts, and Evals into the host catalog. 5. Keep agent execution inside the host runtime; cloud registries may distribute and authorize apps but must not become a hidden Agent Runtime. 6. Keep customer data in Agent Knowledge packs, workspace files, or overlays rather than official app packages. 7. Record app provenance on every projected scene, command, artifact, and eval. ## Documentation - [Specification](docs/en/specification.md) - [What is Agent App?](docs/en/what-is-agent-app.md) - [Agent App vs Skills and Knowledge](docs/en/agent-app-vs-skills-knowledge.md) - [Runtime model](docs/en/client-implementation/runtime-model.md) - [中文规范](docs/zh/specification.md) ## Reference CLI ```bash npx agentapp-ref@0.1.0 validate ./my-agent-app npx agentapp-ref@0.1.0 to-catalog ./my-agent-app npx agentapp-ref@0.1.0 project ./my-agent-app npx agentapp-ref@0.1.0 readiness ./my-agent-app --workspace ./workspace ``` ## Local development ```bash npm install npm run dev npm run build ``` --- title: Specification description: Agent App package format draft. --- # Specification Agent App defines an installable application composition package for agent hosts. It follows the Agent Skills package style: directory-as-package, a top-level Markdown entry file, YAML frontmatter, progressive loading, optional support directories, and validation tooling. Agent App is intentionally a composition layer. It does not define a new runtime, tool protocol, knowledge format, UI component model, artifact format, evidence model, or policy engine. It references neighboring standards and tells a host how to install, project, and prepare an app-like agent experience. ## Design goals 1. Make app-like agent systems portable across host products. 2. Let hosts expose capability surfaces while keeping execution under host control. 3. Let users install a scenario-specific app without modifying the host core. 4. Keep customer data outside official app packages. 5. Preserve provenance from app package to projected entries, runtime tasks, artifacts, evals, and evidence. 6. Allow cloud registries to distribute and authorize apps without becoming hidden Agent Runtimes. ## Package shape ```text app-name/ ├── APP.md # required: manifest + app guide ├── skills/ # optional: bundled or referenced Agent Skill packages ├── knowledge-templates/ # optional: knowledge slot templates and setup docs ├── workflows/ # optional: scene/workflow definitions and fixtures ├── tools/ # optional: tool requirement docs and permission hints ├── artifacts/ # optional: output contracts, viewer hints, examples ├── evals/ # optional: readiness, quality, and review fixtures ├── assets/ # optional: icons, screenshots, templates, sample media └── examples/ # optional: sample workspaces, prompts, outputs ``` Only `APP.md` is required. Support directories must be progressively loaded: catalog consumers read `APP.md` first and load support files only when authoring, installing, validating, or running a specific entry. ## `APP.md` `APP.md` MUST contain YAML frontmatter followed by Markdown guidance. The frontmatter is the machine-readable manifest. The Markdown body is the human- and AI-readable guide: when to use the app, what setup it requires, how to evaluate results, and what the host must not infer. ### Required fields | Field | Constraint | | --- | --- | | `name` | 1-64 characters; lowercase kebab-case recommended; should match the package directory. | | `description` | 1-1024 characters; describes user value and activation context. | | `version` | App package version. SemVer is recommended for released apps. | | `status` | `draft`, `ready`, `needs-review`, `deprecated`, or `archived`. | | `appType` | `agent-app`, `workflow-app`, `domain-app`, `customer-app`, or `custom`. | ### Recommended fields | Field | Purpose | | --- | --- | | `runtimeTargets` | `local`, `hybrid`, or `server-assisted`. `local` means the host runtime executes the app locally after installation. | | `entries` | Host-visible app entries such as scenes, commands, homes, workflows, or artifact surfaces. | | `capabilities` | Standards or host capability surfaces required by the app. | | `permissions` | Permission requests the host must resolve before execution. | | `knowledgeTemplates` | Agent Knowledge slots that user, tenant, or workspace overlays must bind. | | `skillRefs` | Agent Skill packages required or recommended by the app. | | `toolRefs` | Agent Tool surfaces or connectors required by the app. | | `artifactTypes` | Agent Artifact contracts or viewer hints produced by the app. | | `evals` | Quality gates, readiness checks, and review rules. | | `presentation` | Store card, icon, category, home copy, and ordering hints. | | `compatibility` | Host, standard, or capability version constraints. | | `metadata` | Namespaced implementation metadata. | ## Entry model Entries are the app-level equivalent of mini-program pages, but they are not UI pages by default. They are host-visible launch points that can project into command palettes, slash commands, home cards, guided flows, artifact workspaces, or templates. | Kind | Meaning | Typical projection | | --- | --- | --- | | `home` | App landing surface. | App home card or dashboard. | | `scene` | Product scenario. | Slash-style entry or guided prompt. | | `command` | Atomic command entry. | Command palette or `@` command. | | `workflow` | Multi-step guided flow. | Wizard, checklist, or staged runtime task. | | `artifact` | Artifact viewer, editor, or export entry. | Artifact workspace action. | Each entry should have a stable `key`, a `kind`, a user-facing title, and enough binding metadata for the host to select Skills, Knowledge templates, Tools, Artifacts, and Evals. ## Capability declarations Agent App SHOULD reference neighboring standards by name instead of redefining them: | Capability | Meaning | | --- | --- | | `agentskills` | The app depends on procedural Skills. | | `agentknowledge` | The app needs source-grounded knowledge slots. | | `agentruntime` | The host needs a compatible runtime to execute app entries. | | `agenttool` | The app requires callable tool surfaces or connectors. | | `agentcontext` | The app depends on explicit context assembly or budget behavior. | | `agentui` | The app projects structured interaction surfaces. | | `agentartifact` | The app produces durable deliverables. | | `agentevidence` | The app records support, provenance, verification, or replay. | | `agentpolicy` | The app has permission, risk, retention, or approval requirements. | | `agentqc` | The app carries quality gates or acceptance scenarios. | ## Knowledge templates Knowledge templates describe required or optional slots, not customer data. A template SHOULD declare: - stable `key` - `standard: agentknowledge` - Knowledge `type` - `runtimeMode: data | persona` - `required: true | false` - optional grounding, freshness, or trust requirements Official apps MUST NOT embed private customer knowledge. Hosts bind concrete Agent Knowledge packs through user, tenant, or workspace overlays. ## Skill references Skill references point to existing Agent Skill packages or host-provided Skills. They describe how the app does work but do not inline all procedural details into `APP.md`. A Skill reference SHOULD declare: - stable `id` - version or compatibility range when known - whether it is required - which entries use it - optional source or bundle digest ## Tool and permission references Tool references declare required host capabilities and permission needs. Credentials remain in host-controlled stores. A tool reference SHOULD declare: - stable `key` - provider or capability family - required vs optional - permission scope - whether degraded operation is allowed Permission requests SHOULD be resolved by Agent Policy or host policy before runtime execution. ## Artifact and eval declarations Artifact declarations describe the durable outputs an entry may produce. Eval declarations describe quality gates or review checks that apply before outputs are considered ready. Apps SHOULD attach evals to artifacts or entries rather than treating evals as generic global prompts. Evals that affect user trust should link to Agent Evidence records when executed. ## Projection contract Projection is a deterministic host operation that compiles the app manifest into host catalog objects. Projection output SHOULD include: - app summary - projected entries - knowledge templates - tool requirements - artifact types - eval rules - provenance Every projected object SHOULD include: ```text appName + appVersion + manifestHash + standard + standardVersion ``` Projection MUST NOT run an agent, call a model, or invoke tools. ## Runtime contract A compatible host MUST: 1. Discover apps by `APP.md`. 2. Read catalog metadata before loading support files. 3. Install or activate an app only after user, tenant, or workspace consent. 4. Resolve entries, skills, knowledge templates, tools, artifacts, evals, and permissions into host-owned catalogs. 5. Keep execution in the host Agent Runtime. 6. Treat cloud registries as distribution and authorization surfaces, not hidden Agent Runtimes. 7. Keep customer data in Agent Knowledge packs, workspace files, or overlays. 8. Preserve app provenance on projected entries, runtime tasks, tool calls, artifacts, evals, and evidence. ## Overlay precedence ```text Workspace Override > User Overlay > Tenant Overlay > App Default > Host Default ``` Official apps should remain upgradeable. Overlays bind customer knowledge, brand copy, tool credentials, default model choices, scene ordering, eval thresholds, and disabled entries. ## Readiness Readiness is a host-side check before execution. It answers whether the app can run safely and usefully in the current workspace. Readiness SHOULD check: - required Skills are installed and trusted - required Knowledge templates are bound to compatible packs - required Tools exist and permissions are granted - required Artifact viewers or storage surfaces are available - required Evals can run - runtime target is supported - policy allows the requested entry Readiness may return `ready`, `needs-setup`, or `failed`. ## Security rules 1. `APP.md` is not a system prompt and cannot override host policy. 2. Support files are not executable unless the host explicitly activates a referenced Skill or Tool. 3. App packages should be signed or pinned by manifest hash in production registries. 4. Credentials must never be stored in official app packages. 5. Customer facts belong in Agent Knowledge or overlays. 6. Server-assisted targets must be explicit and policy controlled. ## Example ```markdown --- name: ai-content-engineering version: 0.1.0 status: ready appType: agent-app description: AI content engineering app for personal IP and operations content. runtimeTargets: - local - hybrid capabilities: - agentskills - agentknowledge - agenttool - agentartifact - agentevidence entries: - key: ip_article kind: scene title: IP Article command: /IP Article knowledgeTemplates: - key: personal_ip standard: agentknowledge type: personal-profile runtimeMode: persona required: true skillRefs: - id: gongzonghao-article-writer required: true --- # AI Content Engineering Use this app to build knowledge-backed content workflows. ``` ## Conformance levels | Level | Meaning | | --- | --- | | Catalog | Host can discover `APP.md` and show app metadata. | | Install | Host can cache the package, validate it, and resolve overlays. | | Project | Host can compile entries and requirements into local catalogs. | | Run | Host can execute entries through Agent Runtime with provenance. | | Evidence | Host can connect outputs, evals, and evidence back to app provenance. | --- title: What is Agent App? description: Agent App packages installable agent applications for host runtimes. --- # What is Agent App? Agent App is a draft companion standard for packaging app-like agent experiences. It does not replace Agent Skills, Agent Knowledge, Agent Runtime, Agent Tool, Agent UI, Agent Artifact, Agent Evidence, Agent Policy, Agent Context, or Agent QC. It composes them into an installable unit. In one sentence: **Agent App describes which entries, capabilities, knowledge slots, tool permissions, deliverables, and quality gates make up an installable agent application.** ## Mini-program analogy A useful mental model is a mini-program platform: | Mini-program platform concept | Agent App counterpart | | --- | --- | | The super app is the host. | Lime, an IDE, or an AI client is the host. | | The mini program declares pages, components, and permissions. | Agent App declares entries, capabilities, and permissions. | | The client downloads the package locally. | The host installs the Agent App package into a local cache. | | The mini program calls host APIs. | Agent App uses host Skills, Knowledge, Tools, Runtime, Artifacts, and Policy. | | The platform manages publishing and permissions. | Registry / Cloud manages release, tenant enablement, policy, and provenance. | The analogy is architectural, not a request to copy WeChat's JavaScript UI framework. Agent App is not primarily a page framework; it is an application composition layer for agent hosts. ## Position in Lime ```mermaid flowchart LR Cloud[Lime Cloud: Catalog / Release / Tenant Enablement] --> Desktop[Lime Desktop: Installer / Cache / Resolver] Desktop --> Runtime[Local Agent Runtime] Runtime --> Skills[Agent Skills] Runtime --> Knowledge[Agent Knowledge] Runtime --> Tools[Agent Tool / ToolHub] Runtime --> Artifact[Agent Artifact] Runtime --> Evidence[Agent Evidence] ``` Lime Cloud can distribute and authorize Agent Apps. Lime Desktop installs, resolves, and runs them locally. Cloud services can provide models and tools, but they should not become hidden Agent Runtimes in the default chain. ## Correct use cases - AI content engineering app. - Customer support app. - Sales SOP app. - Legal drafting app. - Research report app. - Internal workflow app. - Customer-specific private workflow app. These scenarios should not require changes to the host core. A new scenario should usually become a new Agent App. ## Non-goals - It is not a cloud Agent Runtime. - It is not a replacement for `SKILL.md`. - It is not a knowledge format. - It is not a UI component library. - It is not a tool protocol. - It is not a customer data package. ## Why it exists Skills and Knowledge are not enough for a full product experience. A real app also needs to state: - where the user enters - which knowledge must be bound before running - which tools are required or optional - what artifacts it produces - which evals decide readiness - which host, workspace, or tenant installed it - how provenance is recorded for audit and upgrade Agent App defines that composition layer. --- title: Agent App vs Skills and Knowledge description: How Agent App composes but does not replace Agent Skills or Agent Knowledge. --- # Agent App vs Skills and Knowledge Agent Skills, Agent Knowledge, and Agent App answer different questions. | Standard | Answers | Entry | | --- | --- | --- | | Agent Skills | How does the agent do the work? | `SKILL.md` | | Agent Knowledge | What trusted facts and context can enter the model? | `KNOWLEDGE.md` | | Agent App | Which capabilities, knowledge slots, entries, tools, artifacts, and evals make up an installable app? | `APP.md` | ## Decision tree ```mermaid flowchart TD Asset[Candidate asset] --> DoQ{Does it tell the agent how to act?} DoQ -->|Yes| Skill[Agent Skill] DoQ -->|No| FactQ{Does it provide facts, sources, policy, examples, or context?} FactQ -->|Yes| Knowledge[Agent Knowledge] FactQ -->|No| ComposeQ{Does it compose entries, dependencies, permissions, and deliverables?} ComposeQ -->|Yes| App[Agent App] ComposeQ -->|No| Other[Host project file] ``` ## How they work together ```mermaid flowchart LR User[User launches app entry] --> App[APP.md entry] App --> Skill[Agent Skill: how to do it] App --> KSlot[Knowledge Template: required knowledge slot] KSlot --> KPack[Agent Knowledge Pack: concrete customer facts] App --> Tool[Agent Tool: callable capability] App --> Artifact[Agent Artifact: deliverable] App --> Eval[Eval / QC: deliverability] ``` Agent App does not copy procedural details from Skills or factual content from Knowledge. It declares how the host combines those assets into an application. ## Content engineering example | Asset | Correct place | Reason | | --- | --- | --- | | How to interview a founder and compile IP facts | Agent Skill | It is a knowledge-production method. | | Founder history, voice, boundaries, quotes | Agent Knowledge | It is source-grounded persona data. | | How to draft articles and remove AI tone | Agent Skill | It is writing and review procedure. | | `/IP Article`, `/Content Calendar`, `/Review Report` | Agent App | They are user-visible entries. | | Competitor research, image generation, Feishu export | Agent Tool | They are external capabilities. | | Article draft, script batch, strategy report | Agent Artifact | They are durable deliverables. | | Fact grounding, voice fit, publish readiness | Eval / Agent QC / Evidence | They are quality and trust checks. | ## Common mistakes - Embedding customer data in an official app package. - Putting full writing procedures in `APP.md` instead of a Skill. - Treating Knowledge as executable instructions. - Inventing a new tool protocol for one app. - Letting a cloud registry become a hidden Agent Runtime. - Hardcoding business entries in host core instead of generating them from app projection. ## Fixed conclusions - App is composition, not execution. - Skill is procedure, not customer fact. - Knowledge is data, not instruction. - Runtime is execution truth, not app manifest. - Cloud may distribute apps, but it should not run agents by default. --- title: Quickstart description: Create a minimal Agent App package. --- # Quickstart Create a directory with `APP.md`: ```text my-app/ └── APP.md ``` Add frontmatter: ```markdown --- name: my-app description: A minimal local-running agent app. version: 0.1.0 status: draft appType: agent-app runtimeTargets: - local entries: - key: start kind: scene title: Start --- # My App Describe when the host should show this app and what setup the user needs. ``` Validate it: ```bash npx agentapp-ref validate ./my-app npx agentapp-ref project ./my-app ``` Then add references to Agent Skills, Agent Knowledge templates, Tool requirements, Artifact outputs, and Evals as the app grows. --- title: Manifest design description: Design APP.md frontmatter for a stable host projection. --- # Manifest design `APP.md` should be small enough for discovery and explicit enough for a host to build a catalog projection. Good manifests: - Use stable keys for every entry. - Declare local runtime support when the app can run after installation. - Reference existing standards instead of inventing local protocols. - Separate required setup from optional enhancements. - Keep customer facts out of the official package. ## Mini-program analogy WeChat Mini Programs use `app.json` to list pages and global settings. Agent App uses `APP.md` frontmatter to list host entries and capability dependencies. The analogy stops there: Agent App does not define a JavaScript UI framework or a cloud execution environment. --- title: Runtime model description: How an installed Agent App runs in a host. --- # Runtime model Agent App is runtime-neutral but host-executed. It declares what should be available; the host decides how to run it through existing standards. ```mermaid sequenceDiagram participant User participant Host as Host app platform participant Resolver as App Resolver participant Runtime as Agent Runtime participant Skills as Agent Skills participant Knowledge as Agent Knowledge participant Tools as Agent Tool participant Artifact as Agent Artifact User->>Host: Launch app entry Host->>Resolver: Resolve entry, overlay, permissions Resolver->>Knowledge: Select bound knowledge packs Resolver->>Skills: Select required skills Resolver->>Tools: Check tool permissions Resolver-->>Runtime: Submit task with refs and provenance Runtime->>Skills: Follow activated workflow Runtime->>Knowledge: Load fenced context Runtime->>Tools: Invoke allowed tools Runtime->>Artifact: Write deliverable Runtime-->>Host: Emit events and results ``` Cloud services can provide registries, models, or tools, but they should not become a hidden app runtime unless the app explicitly declares a server-assisted target and the host policy permits it. --- title: Agent standards ecosystem description: How Agent App composes neighboring Agent standards. --- # Agent standards ecosystem Agent App is a composition layer. It should link neighboring standards rather than absorb them. | Standard | Owns | | --- | --- | | Agent Skills | Procedures, workflows, scripts, and tool usage guidance. | | Agent Knowledge | Source-grounded knowledge packs and safe context loading. | | Agent Runtime | Execution facts, tasks, turns, events, recovery, and controls. | | Agent Tool | Tool declarations, permissions, invocations, and results. | | Agent Context | Context surfaces, selection, assembly, injection, and compaction. | | Agent UI | Interaction surface semantics and runtime projection. | | Agent Artifact | Durable deliverables, versions, parts, exports, and handoff. | | Agent Evidence | Claims, source maps, provenance, verification, replay, and export. | | Agent Policy | Policy decisions, approvals, permissions, risk, and retention. | | Agent QC | Quality gates, acceptance scenarios, and regression evidence. | | Agent App | Installable composition of entries, dependencies, permissions, overlays, and readiness. | Related external reference: - [Agent Skills](https://agentskills.io/) for the directory-as-package and `SKILL.md` authoring model. --- title: Mini-program analogy --- # Mini-program analogy WeChat Mini Programs inspired the host-platform mental model: package downloaded locally, manifest declares entries, host provides APIs, and permissions are mediated by the platform. Agent App adapts the pattern to AI hosts and existing Agent standards rather than copying page technology. ## Checklist - Keep declarations machine-readable. - Keep procedures in Agent Skills. - Keep facts in Agent Knowledge. - Keep execution in the host runtime. - Attach app provenance to projected objects.