---
title: Resource packaging and distribution
description: Package employee, team, app or SKILL definitions and files for recipients.
lastVerified: 2026-10-23
---

# 6.9 Resource packaging and distribution

This page explains file organization shared by the four resource types. Finish an [employee](https://docs.teloa.ai/v/0.2.8/markdown/en/develop/employees.md), [team](https://docs.teloa.ai/v/0.2.8/markdown/en/develop/teams.md), [app](https://docs.teloa.ai/v/0.2.8/markdown/en/develop/apps.md) or [SKILL](https://docs.teloa.ai/v/0.2.8/markdown/en/develop/skills.md) example first, then update and distribute it here.

## Two file layers

| File | Purpose |
| --- | --- |
| `employee.json`, `team.json`, `app.json` or `skill.json` | Importable share containing actual file bodies |
| `sources/teloa.json` | Internal manifest listing resources, versions, paths and relationships |
| `sources/roles/`, `skills/` and other files | Editable sources incorporated when repackaged |

[Download the four examples](https://docs.teloa.ai/v/0.2.8/markdown/en/guides/sharing.md#offline-sharing). Each ZIP includes complete JSON, `sources/` and `pack.mjs`. The share and internal manifest are different JSON documents.

## A complete internal manifest

The app example's `sources/teloa.json` declares one skill:

```json
{
  "format": "teloa.business-package/v2",
  "id": "example-app-brief",
  "version": "1.0.1",
  "title": "Evidence brief app",
  "description": "A local authoring example with no account connection or automatic execution.",
  "domain": "general",
  "scope": "general",
  "resources": [
    {
      "id": "evidence-brief",
      "kind": "skill",
      "title": "evidence-brief",
      "version": "1.0.1",
      "required": true,
      "source": {
        "kind": "local",
        "path": "skills/evidence-brief/SKILL.md"
      }
    }
  ],
  "relations": [],
  "entrypoints": [
    "evidence-brief"
  ]
}
```

Its body is `sources/skills/evidence-brief/SKILL.md`. Employees and teams additionally declare roles and connect methods through `role-skill`. See the [format reference](https://docs.teloa.ai/v/0.2.8/markdown/en/develop/formats.md) for other resources and fields.

`teloa.business-package` is the internal manifest name, not a fifth product type. The outer `subject` identifies employee, team, app or SKILL: exactly one employee, at least two team members, no employees in an app, or exactly one skill for a standalone SKILL.

## Repackage edited sources

After changing an employee definition, run from the extracted directory:

```sh
node pack.mjs employee.json
```

Use `app.json`, `team.json` or `skill.json` for the other subjects. The helper refreshes bodies of files already listed in the share:

```js
import {readFile, writeFile, realpath} from 'node:fs/promises'
import {resolve, sep} from 'node:path'
const file = process.argv[2]
if (!file) throw Error('Usage: node pack.mjs employee.json')
const share = JSON.parse(await readFile(file, 'utf8'))
const sourceRoot = await realpath('sources')
for (const item of share.files) {
  if (typeof item.path !== 'string' || item.path.includes('\\') ||
      /[\x00-\x1f\x7f]/.test(item.path) ||
      item.path.split('/').some(part => !part || part === '.' || part === '..')) {
    throw Error('Unsafe source path')
  }
  const source = await realpath(resolve(sourceRoot, item.path))
  if (!source.startsWith(sourceRoot + sep)) throw Error('Source escapes the package')
  item.text = await readFile(source, 'utf8')
}
const manifest = JSON.parse(share.files.find(f => f.path === 'teloa.json').text)
share.id = manifest.id
share.version = manifest.version
await writeFile(file, JSON.stringify(share, null, 2) + '\n')
```

When adding a resource, update inner `resources` and `relations`, the outer `files` list and the actual source files. Increase the package version after changing content; also update changed resource versions and pinned references. The helper synchronizes package identity/version, not every resource's version.

## Format validation {#validate-authoring-examples}

From a dependency-prepared Teloa source root, copy share JSON files into the current directory. List just one subject to check one file; this example checks all four:

```sh
node --input-type=module <<'JS'
import {readFileSync} from 'node:fs'
import {readTemplateShare} from './packages/contract/src/template-share.mjs'
for (const subject of ['employee', 'team', 'app', 'skill']) {
  const value = JSON.parse(readFileSync(`${subject}.json`, 'utf8'))
  console.log(readTemplateShare(value).subject)
}
JS
```

Expect `employee`, `team`, `app`, `skill`. This validates the format without adding or executing it. Without a source environment, choose a share JSON in **Employees > Import template** to inspect its preview.

## Receive and distribute

Inspect members, methods, material and provenance, then explicitly add to a test business area. Employees start paused. Follow readiness states to configure models, install capabilities, connect accounts and grant permissions. Complete the tutorial's small task before distributing through [offline files or online links](https://docs.teloa.ai/v/0.2.8/markdown/en/guides/sharing.md).

A share is limited to 8 MiB serialized JSON and 2 MiB per file body. Exclude passwords, model keys, account sessions and execution grants; check distribution rights for the included text and materials.

## Complete business configuration

Internal v2 organizes ordinary resources, v3 adds pinned model dependencies and v4 adds complete business configuration. Choose the required capabilities rather than incrementing format numbers as a publishing ritual. Complete configuration includes objects, views, pages and dashboards, without real records, sync accounts or action grants. See [format reference](https://docs.teloa.ai/v/0.2.8/markdown/en/develop/formats.md).

For an inner resource directory or ZIP, use **Marketplace > Create > Import template** and include its manifest and files. For the share JSON used here, use **Employees > Import template**. These entrypoints read different file structures.