Heretek Skills

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.

---

The Swarm at a Glance

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

---

Skills

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

---

How Skills Work

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

Installation

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/

---

Project Structure

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

---

Related Repos

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

---

License

MIT — see LICENSE.