AI coding agent skills for the Heretek Swarm project.
These skills provide structured guidance for AI assistants (Claude, GSD, Copilot, Cursor, etc.) working on the Heretek Swarm codebase. Each skill is a self-contained SKILL.md file that loads domain-specific conventions, architecture notes, file paths, and patterns so the agent can work accurately without guessing.
Heretek Swarm is a self-governing collective of 23 specialized AI agents built on Python 3.11+, FastAPI, React 19, and NATS JetStream. It runs 6 Docker containers (7 logical services) including PostgreSQL, Redis, Qdrant, NATS, an API server, a React dashboard, and an embedded Cognee memory engine.
| Layer | Tech |
|---|---|
| Backend | Python 3.11+, FastAPI, SQLAlchemy, asyncpg |
| Frontend | React 19, TypeScript, Vite, Zustand, Tailwind CSS |
| Messaging | NATS JetStream (mTLS) with A2A protocol |
| Memory | Cognee (knowledge graph + vectors), PostgreSQL, Qdrant |
| State | PostgreSQL (primary), Redis (cache), Qdrant (semantic) |
| Observability | structlog, Prometheus, OpenTelemetry |
| Infrastructure | Docker Compose, Alembic migrations |
| Skill | Use When |
|---|---|
| heretek-agent-development | Creating agent actors, implementing behaviors, working with the actor/mixin architecture (23 agents, 10 mixins) |
| heretek-api-development | Building FastAPI endpoints, adding routers, implementing auth middleware (27 routers, 175+ endpoints) |
| heretek-backend-development | General Python backend work — project structure, async patterns, codebase conventions (412 .py files, ~184K LOC) |
| heretek-contributing | Preparing PRs, following commit conventions, running linters, understanding the review process |
| heretek-debugging | Diagnosing failures, tracing issues through structured logs, profiling performance |
| heretek-docker-operations | Docker Compose management, building images, volume persistence, container health checks |
| heretek-frontend-development | React components, Zustand stores, Vite config, TypeScript patterns (93 components, 12 domains) |
| heretek-memory-system | Cognee-backed memory — knowledge graphs, vector search, access patterns, pre-fetching |
| heretek-migration | Alembic database migrations, code migrations, rollback procedures |
| heretek-monitoring | Structured logging (structlog), Prometheus metrics, OpenTelemetry tracing, health endpoints |
| heretek-nats-messaging | Inter-agent communication via NATS — pub/sub, JetStream persistence, queue groups, mTLS |
| heretek-security | Zero-trust auth, JWT hardening, API key management, input validation, SOPS secrets |
| heretek-state-management | PostgreSQL, Redis, and Qdrant operations — connections, caching, vector search patterns |
| heretek-testing | pytest + vitest patterns, test fixtures, mocking strategies, integration test setup |
Each skill is a single SKILL.md file with YAML frontmatter:
---
name: heretek-agent-development
description: >-
Agent development for Heretek Swarm's 23-agent system.
---When an AI coding assistant loads a skill, it gains:
- File paths — exact locations of relevant code, configs, and tests
- Conventions — naming, patterns, and anti-patterns specific to this codebase
- Architecture notes — how components connect, dependency chains, common pitfalls
- Code examples — real patterns from the project, not generic templates
Copy the skills/ directory into your agent's skill path:
# For GSD / Claude
cp -r skills/ ~/.gsd/agent/skills/
# For project-local skills
cp -r skills/ .claude/skills/heretek-skills/
├── README.md # This file
├── LICENSE # MIT
└── skills/
├── heretek-agent-development/ # 23-agent actor system
├── heretek-api-development/ # FastAPI routers & endpoints
├── heretek-backend-development/ # Python backend patterns
├── heretek-contributing/ # Contribution guidelines
├── heretek-debugging/ # Troubleshooting patterns
├── heretek-docker-operations/ # Docker Compose & containers
├── heretek-frontend-development/ # React/TypeScript dashboard
├── heretek-memory-system/ # Cognee memory engine
├── heretek-migration/ # Alembic & code migrations
├── heretek-monitoring/ # Observability stack
├── heretek-nats-messaging/ # NATS JetStream messaging
├── heretek-security/ # Zero-trust security
├── heretek-state-management/ # PostgreSQL, Redis, Qdrant
└── heretek-testing/ # pytest & vitest patterns
| Repo | Description |
|---|---|
| Heretek-AI/heretek-swarm | The main Swarm platform — 23 agents, API, dashboard, infrastructure |
| Heretek-AI/heretek-skills | This repo — AI coding skills for the Swarm codebase |
MIT — see LICENSE.