Contribute templates and Skills

Choose the right contribution path

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

• 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

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

Related guides

• Work with Templates, Work with Skills, and Manage Skill Versions
• Add an integration and Test a change

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.