{% extends "base.html" %} {% block title %}Authoring a Stack — Agentic Stacks{% endblock %} {% block meta_description %}Learn how to create an Agentic Stack — a git repository that teaches AI agents to operate in a specific domain. Covers skill design, manifest format, CLAUDE.md writing, and publishing.{% endblock %} {% block content %}

Authoring a Stack

A stack is a git repository that teaches an AI agent how to operate in a specific domain. When an agent reads your stack, it should become an expert operator — capable of deploying, managing, troubleshooting, and upgrading the target software.

Anatomy of a Stack

Every stack has these files at the root:

my-stack/
├── README.md       # Repo landing page
├── CLAUDE.md       # Agent entry point — persona, rules, routing
├── stack.yaml      # Machine-readable manifest
└── skills/         # Operational knowledge, organized by phase

Scaffold one with:

agentic-stacks create my-org/my-stack

Step 1: Design the Skill Hierarchy

Skills are directories of markdown files that teach the agent specific operations. Organize by what the operator is trying to do:

Phase Purpose Examples
FoundationUnderstanding and setupArchitecture, configuration, provisioning
DeployInitial deploymentBootstrap, networking, storage
PlatformPlatform layerGitOps, ingress, monitoring, security
OperationsDay-two managementHealth checks, scaling, upgrades, backup
DiagnoseTroubleshootingSymptom-based decision trees
ReferenceCross-cutting lookupsKnown issues, compatibility, decision guides

For complex stacks (10+ skills), use phase/domain nesting:

skills/
├── foundation/
│   ├── concepts/
│   └── infrastructure/
│       ├── README.md       # Overview + index
│       ├── aws.md          # Platform-specific
│       └── gcp.md
├── deploy/
│   ├── bootstrap/
│   ├── networking/
│   │   ├── README.md       # Decision matrix
│   │   ├── cilium.md       # Option deep dive
│   │   └── flannel.md
│   └── storage/
└── operations/
    ├── health-check/
    ├── upgrades/
    └── backup-restore/

Step 2: Write CLAUDE.md

CLAUDE.md is the agent's brain. It sets identity, enforces safety, and routes to skills.

# [Stack Name] — Agentic Stack

## Identity
[1-2 sentences establishing the agent's expertise]

## Critical Rules
[Numbered list of hard safety guardrails]

## Routing Table
| Operator Need | Skill | Entry Point |
|---|---|---|
| Deploy the cluster | bootstrap | skills/deploy/bootstrap |
| Troubleshoot issues | troubleshooting | skills/diagnose/troubleshooting |

## Workflows
### New Deployment
[Linear path through skills for first-time setup]

### Existing Deployment
[How to jump to the right skill for ongoing operations]

Writing Critical Rules

Critical rules prevent the agent from doing damage. Good rules are:

Step 3: Write stack.yaml

name: my-stack
owner: my-org
version: 0.1.0
description: >
  One paragraph describing what this stack teaches agents to operate.

repository: https://github.com/my-org/my-stack

target:
  software: target-software-name
  versions: ["1.x"]

skills:
  - name: skill-name
    entry: skills/path/to/skill
    description: One-line description

project:
  structure:
    - file-or-dir-in-operator-project

requires:
  tools:
    - name: tool-name
      description: What it's used for

depends_on: []

Tips: entry points to a directory, not a file. The directory's README.md is the entry point. description should help an agent decide whether to read the skill.

Step 4: Research and Verify

A stack is only as good as its accuracy. Before writing any skill:

  1. Fetch the target software's official documentation index (/llms.txt, /sitemap.xml, or GitHub source)
  2. Copy exact commands from the docs — do not reconstruct from memory
  3. Verify YAML field names, CLI flags, and config structure
  4. Note version-specific behavior
  5. Cross-reference with release notes and GitHub issues

Step 5: Write Skill Content

Optimize for how agents process information:

Known Issues Pattern

Version-specific bugs get their own files in skills/reference/known-issues/:

### [Short Description]

**Symptom:** What the operator sees
**Cause:** Why it happens
**Workaround:** Exact steps to fix it
**Affected versions:** x.y.z through x.y.w
**Status:** Open / Fixed in x.y.w

Step 6: Decision Guides and Compatibility

For stacks where operators must choose between components, provide structured decision aids in skills/reference/decision-guides/:

And compatibility matrices in skills/reference/compatibility/ mapping which versions of components work together.

Step 7: Validate Your Stack

agentic-stacks doctor

Before publishing, check:

Designing for Composition

Operators compose multiple stacks in a single project. To make your stack compose well:

Reference Implementations

Stack Complexity Pattern
openstack-kollaSimpleFlat phase-based (8 skills)
kubernetes-talosComprehensiveTwo-layer phase/domain (20 skills)
{% endblock %}