---
title: Contribute templates and Skills
canonical: "https://agentbarn.dev/guides/develop/contribute-templates-and-skills"
pubDate: "2026-08-29T00:00:00.000Z"
updatedDate: "2026-09-09T09:19:24.000Z"
author: Agent Barn
description: "Contribute bootstrap Templates and isolated bundled Skills with missing-only seeding, immutable versions, exact Skill pins, scopes, runtime mounts, and review."
tags: [Develop and extend, How-to, "Template authors, Skill authors, and maintainers", contribute, Platform Template, Skill, aai-cli, template seed, Skill package, required Skills, versioning, GitHub, pull request]
categories: [Guides, Develop and extend]
---

Templates define reusable, versioned Agent configuration. Skills package versioned instructions and reference files that are mounted into an Agent workspace. Source-controlled seeds bootstrap missing Platform resources, while drafts and published database versions own their lifecycle after bootstrap.

Agent Barn has Platform, Organization, and Agent-private Skill scopes. Organization and Agent-private content is authored inside Agent Barn and is not automatically submitted upstream.

## Choose the right contribution path

| Goal | Correct path | Result |
| --- | --- | --- |
| Create a Template for one Organization | Organization Settings → Templates | Organization-owned Template lineage |
| Customize a Platform Template | Create an Organization fork | Independent Organization lineage |
| Update a Platform Template | Platform View → Platform Templates → draft and publish | Next immutable Platform Template Version |
| Add a new Template to the distributed catalogue | Add a source-controlled seed directory | Platform Template v1 only where the lineage is missing |
| Create an Organization Skill | Organization Settings → Skills → New Skill | Organization-owned draft; publishing creates v1 |
| Create an Agent-private Skill | Agent configuration → Skills → New Skill | Agent-owned draft; publishing creates v1 |
| Customize a visible Skill | Fork it into an allowed owning scope | Independent draft with exact source-version provenance |
| Create a custom Platform Skill | Platform View → Platform Skills → New Skill | Platform-owned draft; publishing creates v1 |
| Add bundled instructions for an aai-cli capability | Add an isolated `aai-<integration>` bundle | Built-in Platform Skill v1 only where its slug is missing |
| Add an unsupported external provider | Follow [Add an integration](/guides/develop/add-integration) first | Credential, validation, Runtime, UI, and Skill contracts |

**Note**

New custom Skills and forks begin with a draft and no published version. They do not create v1 immediately.

## Contribute Platform Template seeds

Prepare a focused branch from staging, follow repository contribution guidance, use fictional identifiers in examples, and never commit credentials or environment-specific secrets.

```
Template seed directory
        │
        ▼
API startup
        │
        ├── Template key is missing
        │       └── Create Platform Template v1
        │
        └── Template key already exists
                └── Make no changes

Future versions
        │
        ▼
Platform Administrator draft
        │
        ▼
Publish next immutable Platform Template Version
```

Template seeds live in `api/domains/templates/predefined/seeds/`; each directory name is its stable Platform Template key. The database becomes canonical after first seed. `_defaults` supplies omitted artifacts, so include only artifacts that intentionally differ.

The eight supported artifacts are `soul.md`, `identity.md`, `user.md`, `tools.md`, `agents.md`, `boot.md`, `bootstrap.md`, and `heartbeat.md`. Keep authoring safe: treat external content as untrusted data, make startup and heartbeat behavior idempotent, and require authorization for destructive actions.

## Define required Skills with exact pins

```
name: Incident Coordinator
description: Investigates reported incidents and coordinates verified updates.

required_skills:
  - Jira
  - any_of:
      - GitHub
      - Bitbucket
```

A string is independently required. An `any_of` entry is an at-least-one group. Names resolve against published global Platform Skills during first bootstrap; missing Skills are skipped rather than repaired later, so seed the Skill before the Template relies on it.

Persisted Template requirements pin exact `(skill_id, skill_version)` pairs. Bootstrap uses the published version available then. Publishing a later Skill Version never moves an existing Template requirement, and Agents retain exact Template and Skill pins until explicitly repinned.

Platform and Organization authoring APIs represent exact selections through `required_skill_ids`, `required_skill_groups`, and `required_skill_versions`.

```
Before using Jira, read:

`./skills/aai-jira/SKILL.md`
```

Use isolated mounted paths such as `./skills/aai-jira/SKILL.md`, `./skills/aai-github/SKILL.md`, and `./skills/aai-bitbucket/SKILL.md`. Template paths must resolve to real mounted Skill files.

## Bootstrap bundled aai-cli Skills once

```
Bundled aai-<integration> directory
        │
        ▼
API startup
        │
        ├── Platform Skill slug is missing
        │       └── Create built-in Platform Skill and publish v1
        │
        └── Platform Skill slug already exists
                └── Make no changes
```

**Bootstrap data, not reconciliation**

Bundled Skill files are bootstrap data, not an ongoing reconciliation source. Startup does not compare their files with existing published versions and does not publish a new version when checked-in Markdown changes.

-   Existing database content and versions are not overwritten.
-   Editing a checked-in bundle affects clean installations and environments where the slug does not exist.
-   Updating an already-seeded built-in lineage requires an explicit migration or release procedure.
-   Built-in `aai_cli` lineages are protected from ordinary editing and deletion.
-   Custom Platform Skills use the normal Platform draft and publish workflow.

## Contribute an isolated bundled Skill

```
api/domains/agents/aai_cli_skills/bundled/skills/
└── aai-acme/
    ├── SKILL.md
    └── references/
        └── command-reference.md
```

Use the stable `aai-<integration>` slug. Each bundle has exactly one root `SKILL.md`; supporting files stay beneath it, all files are UTF-8 text, references are relative to the root, content contains no credentials or environment-specific secrets, and commands match the pinned `aai-cli` implementation.

```
---
name: aai-acme
description: Use aai-cli to work with Acme resources through the configured Agent credential.
---

# aai-cli Acme

Use this skill when working with Acme through `aai-cli acme`.

Credentials are already configured by Agent Barn. Do not ask the user to provide tokens.

Confirm the active profile or pass `--profile`.

Successful output is JSON on stdout. Errors are structured JSON on stderr.

See [the command reference](references/command-reference.md) for supported commands, response shapes, and errors.
```

`references/command-reference.md` documents the canonical profile, real resource and command groups, required and optional flags, response shapes, pagination, downloads and output files, structured errors and exit codes, read versus mutation behavior, and provider limitations.

## Register bundles and preserve root isolation

Register bundles in `api/domains/agents/aai_cli_skills/__init__.py`:

```
_DISPLAY_NAMES = {
    "aai-acme": "Acme",
}

_COMMANDS = {
    "aai-acme": "acme",
}

_REQUIRED_PROVIDERS = {
    "aai-acme": [SecretProvider.ACME],
}
```

`_DISPLAY_NAMES` provides the catalogue label, `_COMMANDS` the real command group, and `_REQUIRED_PROVIDERS` credential requirements. The bundle directory supplies the immutable Skill slug and root; do not import Python Skill modules or append file dictionaries manually.

`"aai-acme": []` means no Agent Secret is required. It does not auto-mount the Skill: credential-free bundles remain available as Platform Skills and must be assigned explicitly. Bundles with non-empty requirements can auto-mount when all required providers are configured.

```
Hermes:
  /workspace/skills/aai-acme/SKILL.md

OpenClaw:
  /home/node/.openclaw/workspace/skills/aai-acme/SKILL.md

Template and tools pointer:
  ./skills/aai-acme/SKILL.md
```

Stored paths are relative to their own Skill root. Runtime materialization prefixes every file with that root and carries exact Agent-pinned Skill Versions. Same relative filenames under different roots do not collide; actual full-path collisions are reported, and a display-name change never moves a root.

## Publish custom content through Platform authoring

```
Create lineage
  → initial draft
  → edit files and metadata
  → publish immutable v1
  → start another draft
  → publish immutable v2
```

Every published version contains exactly one root `SKILL.md`, is immutable, and each lineage has at most one mutable draft. Publishing never moves Agent or Template pins; forks record exact source Skill and version. Deletion is blocked while a version is pinned or referenced, and built-in aai-cli lineages cannot be deleted.

Platform Administrators manage database-owned resources at `/dashboard/platform/templates`, `/dashboard/platform/templates/{template_key}`, `/dashboard/platform/skills`, and `/dashboard/platform/skills/{skill_id}`. Templates use one draft, optional restore from history, all eight artifacts, exact Skill Versions, then the next immutable publish. Custom Platform Skills use draft lineages, `SKILL.md`, references, description, provider metadata, and immutable publishes. Ordinary authoring does not mutate checked-in built-ins.

## Respect file constraints and test contracts

| Constraint | Limit |
| --- | --- |
| Files per Skill Version | 200 |
| Maximum content per file | 1 MB |
| Maximum content per Skill Version | 5 MB |
| Maximum path length | 512 characters |

Paths must be relative, cannot contain `.` or `..` segments, be absolute, or end in `/`; may contain letters, digits, dots, dashes, and underscores; are unique case-insensitively; and cannot include `__MACOSX` or `._` metadata. Every published Skill Version contains exactly one root `SKILL.md`.

```
api/tests/unit/test_aai_cli_skills.py
api/tests/unit/test_template_skill_paths.py
api/tests/integration/test_templates.py
api/tests/integration/test_skills.py
api/tests/integration/test_agents.py
```

Document coverage for missing and untouched Template seeds, defaults, exact requirement pins, unresolved Skills, and real paths; bundled root files, metadata, isolated manifests, and missing-only seeding; plus custom drafts, immutable versions, and consumers that stay pinned. Do not execute these tests for this documentation change.

## Troubleshoot bootstrap and pinning

### Editing a Template seed did not update the Template

Use a Platform draft

This is expected. Seeds create missing Platform lineages at v1 only. Use the Platform Template draft and publish flow for later versions.

### Editing a bundled Skill did not publish another version

Use an explicit release procedure

This is expected. Bundled files bootstrap missing built-in Platform Skill slugs only. Existing database versions are not reconciled at startup; updating an already-seeded built-in requires an explicit migration or release procedure.

### A Template references a missing Skill file

Use the isolated mount path

Correct the Template to use `./skills/aai-jira/SKILL.md`. Do not restore a shared `./skills/aai-cli/` layout.

### Skill assignment reports missing credentials

Configure required providers

Configure every declared required provider. Do not remove requirements merely to bypass validation.

## Related guides

-   [Work with Templates](/guides/templates-and-skills/templates), [Work with Skills](/guides/templates-and-skills/skills), and [Manage Skill Versions](/guides/templates-and-skills/skill-versions)
-   [Add an integration](/guides/develop/add-integration) and [Test a change](/guides/develop/testing)

## Organization Template authoring

Both Platform and Organization Templates use a draft-and-publish workflow. A lineage has at most one mutable draft in its owning scope. Saving a draft preserves work without creating a published Template Version. Publishing creates the next immutable version and clears the draft. Agents continue to use their exact pinned published version until explicitly repinned.

New Organization Templates begin as draft-only lineages. They become selectable as published Templates after their first publication. Organization Members can read and use published Templates but cannot author shared definitions. Organization Owner/Admin manage Organization Templates; Platform authoring requires Platform Administrator authority.

Use Settings → Templates and the dedicated lineage detail/editor. Start or continue a draft, edit metadata, all eight Markdown artifacts, and exact required Skill Versions, then save. Publish separately and explicitly select the published version on each Agent that should use it.