Aithos Selection

What this is

A curated knowledge base of AI primitives — prompts, skills, MCP server configs, agents, and workflows — used by Aithos to deliver AI consulting work for small and medium-sized enterprises. The repository is part working library, part portfolio asset, and part compounding leverage: every solved problem becomes a reusable ingredient for the next engagement.

Mental model

The repository encodes five layers. The first four are content the repo contains and reuse each other through manifest.yaml declarations; the fifth points outward.

Atoms (ingredients). Single-purpose, reusable units. Each atom lives in exactly one folder. Skills sit in skills/ (e.g. humanizer, the text-style cleanup skill), prompts in prompts/ (split between finished library/ items and parametric templates/), MCP server configs in mcp-servers/, Python utilities in tools/ (e.g. tools/install.py), and tool-specific operational playbooks in stack/.

Composites. Combinations of atoms that form a coherent unit but are not yet a full workflow. agents/ is the main composite folder: each agent is a subfolder with a system prompt (agent.md), a dependency manifest (manifest.yaml), and a README.md. Example: agents/example-echo-agent/.

Subagents. Claude Code subagent primitives (Anthropic format), invoked as /<name> once deployed under a project's .claude/agents/. Each subagent in subagents/ is a self-contained bundle with an entrypoint .md declaring tools, mcpServers, and skills dependencies, plus an Aithos-side manifest.yaml that mirrors those fields for indexing. Example: subagents/automation-architect/.

Recipes. Orchestrated workflows that solve a complete user-facing task. workflows/ contains Claude/agent-based workflows that may delegate to n8n flows. n8n-workflows/ holds standalone n8n exports that are not part of a Claude-orchestrated recipe.

References. Curated bookmarks to external resources — content the repo points to rather than contains. references/ is split into repos/ (GitHub repositories), articles/ (blog posts, papers, documentation), and templates/ (external n8n / skill / agent templates). References are never declared as uses: dependencies; they are pure curation.

Atoms are referenced by composites, subagents, and recipes through manifest.yaml, never by copying. See PRD.md for the strategic rationale and CLAUDE.md for the invariants every contributor (human or AI) must follow.

How to use this repo

For day-to-day contribution and editing rules, read CONTRIBUTING.md. It covers how to add new prompts (single-file and folder-as-prompt), MCP configs, stack notes, agents, subagents, workflows, and references, plus how to deploy skills and subagents with tools/install.py and how to use the _inbox/ quick-dump zone.

For the strategic spec, read PRD.md.

For the rules that bind every Claude Code session in this repo, read CLAUDE.md — it is auto-loaded by Claude Code.

Quick start for Claude Code sessions

The recommended way to start a session:

cd ~/projects/aithos-selection
claude

Claude Code auto-loads CLAUDE.md from the working directory. From there, ask for what you need — adding a new prompt, drafting an agent, processing the inbox — and Claude will follow the invariants in CLAUDE.md and the guides in CONTRIBUTING.md.

For evening maintenance — processing the inbox and syncing GitHub stars in one go — open a Claude Code session and say "run nightly sync". The librarian skill handles the rest.

To deploy a skill or subagent to its runtime location, use uv run python tools/install.py install <path> (symlink by default; --mode copy when the source path won't resolve at the target). See CONTRIBUTING.md → "Deploying skills and subagents".

To browse what already exists, open INDEX.md (auto-generated by tools/generate_index.py).

Folder map

.
├── CLAUDE.md                # Invariants for Claude Code sessions (auto-loaded)
├── PRD.md                   # Strategic spec for the repository
├── INDEX.md                 # Auto-generated catalogue (do not hand-edit)
├── CONTRIBUTING.md          # How to add and update content
├── README.md                # This file
├── _inbox/                  # Quick-dump zone (contents gitignored)
├── docs/                    # Meta-docs about the repo itself
│   └── schemas/             # YAML schemas for manifests and frontmatter
├── skills/                  # Claude Code skills (Anthropic format)
├── prompts/                 # Prompt library
│   ├── library/             # Finished, versioned prompts
│   └── templates/           # Parametric templates with {{variables}}
├── mcp-servers/             # MCP server configurations (one JSON per server)
├── tools/                   # Python utilities (index generator, validator, install script for deploying skills/subagents)
├── stack/                   # Operational playbooks (one Markdown per tool)
├── agents/                  # Agent definitions (system prompt + manifest)
├── subagents/               # Claude Code subagents (entrypoint + manifest)
├── workflows/               # Claude/agent-based workflows
├── n8n-workflows/           # Standalone n8n workflow exports
├── references/              # Curated bookmarks to external resources
│   ├── repos/               # GitHub repositories
│   ├── articles/            # Blog posts, papers, documentation pages
│   └── templates/           # External n8n / skill / agent templates
└── tasks/                   # Archived bootstrap phase specs (see tasks/README.md)