Skip to content

Building AI agents, atomically

Add cross-tool AI distribution: npx skills path, llms.txt index, Context7 config

Eigenwiseffcdca567bd4
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
index 655ac17..1b625da 100644
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@@ -2,6 +2,8 @@
name: release
description: Release a new version of atomic-agents to PyPI and GitHub. Use when the user asks to "release", "publish", "deploy", or "bump version" for atomic-agents.
allowed-tools: Read, Bash, Grep, Glob
+metadata:
+ internal: true
---
# Release Process for atomic-agents
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 5b7f081..89e8df0 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -57,11 +57,16 @@ jobs:
cd docs
uv run make html
+ - name: Place llms files at site root
+ run: |
+ cp docs/llms.txt docs/llms-*.txt docs/_build/html/
+
- name: Verify llms files in build
run: |
- echo "Checking for llms files in build directory:"
+ echo "Checking for llms files at site root:"
+ ls -lh docs/_build/html/llms*.txt
+ echo "Checking for llms files in _static (download links):"
ls -lh docs/_build/html/_static/llms-*.txt || echo "Files not in _static"
- ls -lh docs/_build/html/_downloads/*/llms-*.txt || echo "Files not in _downloads"
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
diff --git a/README.md b/README.md
index 094ed79..d0fed80 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,9 @@ Built on [Instructor](https://github.com/jxnl/instructor) and [Pydantic](https:/
- [Examples \& Documentation](#examples--documentation)
- [Quickstart Examples](#quickstart-examples)
- [Complete Examples](#complete-examples)
+ - [AI-Assisted Development](#ai-assisted-development)
+ - [Agent skills (Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, ...)](#agent-skills-claude-code-cursor-copilot-codex-windsurf-gemini-cli-)
+ - [Docs for LLMs](#docs-for-llms)
- [🚀 Version 2.0 Released!](#-version-20-released)
- [Key Changes in v2.0:](#key-changes-in-v20)
- [⚠️ Upgrading from v1.x](#️-upgrading-from-v1x)
@@ -293,6 +296,35 @@ In addition to the quickstart examples, we have more complex examples demonstrat
For a complete list of examples, see the [examples directory](/atomic-examples/).
+## AI-Assisted Development
+
+Building with an AI coding assistant? Atomic Agents ships first-class support so your assistant knows the framework's current API and conventions instead of guessing.
+
+### Agent skills (Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, ...)
+
+Six [agent skills](https://agents.md/) cover the framework: an auto-triggering `framework` guide with progressive-disclosure references, four creation workflows (`create-atomic-schema`, `create-atomic-agent`, `create-atomic-tool`, `create-atomic-context-provider`), and a `new-app` project scaffolder.
+
+**Claude Code** (also gets the `atomic-explorer` and `atomic-reviewer` subagents):
+
+```
+/plugin marketplace add eigenwise/atomic-agents
+/plugin install atomic-agents@eigenwise
+```
+
+**Any other skills-compatible assistant:**
+
+```bash
+npx skills add eigenwise/atomic-agents
+```
+
+See [claude-plugin/atomic-agents](./claude-plugin/atomic-agents/README.md) for details.
+
+### Docs for LLMs
+
+The [documentation site](https://eigenwise.github.io/atomic-agents/) publishes LLM-ready bundles: [llms-full.txt](https://eigenwise.github.io/atomic-agents/llms-full.txt) (docs + source + examples), plus separate [docs](https://eigenwise.github.io/atomic-agents/llms-docs.txt), [source](https://eigenwise.github.io/atomic-agents/llms-source.txt), and [examples](https://eigenwise.github.io/atomic-agents/llms-examples.txt) bundles. Point your assistant at one of these when it needs the full picture.
+
+Atomic Agents is also indexed on [Context7](https://context7.com/eigenwise/atomic-agents) for assistants with the Context7 MCP server.
+
## Atomic Forge & CLI
Atomic Forge is a collection of tools that can be used with Atomic Agents to extend its functionality. Current tools include:
diff --git a/claude-plugin/atomic-agents/README.md b/claude-plugin/atomic-agents/README.md
index c41e088..24eabc3 100644
--- a/claude-plugin/atomic-agents/README.md
+++ b/claude-plugin/atomic-agents/README.md
@@ -54,6 +54,16 @@ To require this plugin for everyone who opens a given repo, add it to the projec
Claude Code prompts each teammate to install on first trust of the folder.
+### Other coding assistants (Cursor, Copilot, Codex, Windsurf, Gemini CLI, ...)
+
+The skills follow the cross-tool [agent skills](https://agents.md/) format, so any skills-compatible assistant can install them without the Claude Code plugin system:
+
+```bash
+npx skills add eigenwise/atomic-agents
+```
+
+This installs the six skills (framework guide, four create-* workflows, new-app scaffolder). The `atomic-explorer` and `atomic-reviewer` subagents are Claude Code plugin features and don't travel this path.
+
### Local dev
```bash
diff --git a/context7.json b/context7.json
new file mode 100644
index 0000000..12a1fda
--- /dev/null
+++ b/context7.json
@@ -0,0 +1,16 @@
+{
+ "$schema": "https://context7.com/schema/context7.json",
+ "projectTitle": "Atomic Agents",
+ "description": "Lightweight, modular Python framework for building agentic AI applications with typed Pydantic schemas and Instructor",
+ "branch": "main",
+ "excludeFolders": [".claude", ".github", "docs/_build", "**/__pycache__"],
+ "excludeFiles": ["CHANGELOG.md"],
+ "rules": [
+ "Import from the top-level package: from atomic_agents import AtomicAgent, AgentConfig, BaseIOSchema, BaseTool. Legacy paths like atomic_agents.lib.* were removed in v2.",
+ "Construct agents as AtomicAgent[InputSchema, OutputSchema](config=AgentConfig(...)). The type parameters carry runtime information, so write them explicitly.",
+ "Always wrap the provider SDK client with Instructor (instructor.from_openai, instructor.from_anthropic, ...) before passing it as AgentConfig.client.",
+ "Every BaseIOSchema subclass requires a non-empty docstring; the docstring and Field descriptions flow into the LLM prompt.",
+ "Provider parameters (temperature, max_tokens, reasoning_effort) go in AgentConfig.model_api_parameters, not on the agent.",
+ "For Gemini set assistant_role='model' and match AgentConfig.mode to the Instructor factory mode; Anthropic requires max_tokens in model_api_parameters."
+ ]
+}
diff --git a/scripts/generate_llms_files.py b/scripts/generate_llms_files.py
index 6fb2294..c497de7 100644
--- a/scripts/generate_llms_files.py
+++ b/scripts/generate_llms_files.py
@@ -22,11 +22,14 @@ ATOMIC_EXAMPLES_DIR = PROJECT_ROOT / "atomic-examples"
SINGLEHTML_DIR = DOCS_DIR / "_build" / "singlehtml"
# Output files
+OUTPUT_INDEX = DOCS_DIR / "llms.txt"
OUTPUT_DOCS = DOCS_DIR / "llms-docs.txt"
OUTPUT_SOURCE = DOCS_DIR / "llms-source.txt"
OUTPUT_EXAMPLES = DOCS_DIR / "llms-examples.txt"
OUTPUT_FULL = DOCS_DIR / "llms-full.txt"
+SITE_URL = "https://eigenwise.github.io/atomic-agents"
+
# File extensions to include in source code
SOURCE_CODE_EXTENSIONS = {'.py', '.md', '.txt', '.yml', '.yaml', '.toml', '.cfg', '.ini', '.json'}
@@ -240,6 +243,46 @@ def generate_full_content() -> str:
return content
+def generate_index() -> str:
+ """Generate the llms.txt index per the llmstxt.org spec: a small Markdown
+ navigation file at the site root pointing to the full bundles and key pages."""
+ return f"""# Atomic Agents
+
+> Atomic Agents is a lightweight, modular Python framework for building agentic AI applications
+> as composable, schema-driven building blocks. Built on Instructor and Pydantic: every agent is
+> a typed transformer from an input schema to an output schema, with full developer control and
+> no hidden abstractions. Provider-agnostic (OpenAI, Anthropic, Groq, Gemini, Ollama, and more).
+
+Key API facts: import from the top-level `atomic_agents` package (`AtomicAgent`, `AgentConfig`,
+`BaseIOSchema`, `BaseTool`) and from `atomic_agents.context` (`ChatHistory`,
+`SystemPromptGenerator`, `BaseDynamicContextProvider`). Agents are constructed as
+`AtomicAgent[InputSchema, OutputSchema](config=AgentConfig(...))` with an Instructor-wrapped
+client. Every `BaseIOSchema` subclass requires a docstring. Python 3.12+.
+
+## Documentation
+
+- [Quickstart guide]({SITE_URL}/guides/quickstart.html): first agent, providers, streaming
+- [Tools guide]({SITE_URL}/guides/tools.html): BaseTool, Atomic Forge, MCP interop
+- [Orchestration guide]({SITE_URL}/guides/orchestration.html): multi-agent patterns
+- [Memory guide]({SITE_URL}/guides/memory.html): ChatHistory, persistence, custom backends
+- [Hooks guide]({SITE_URL}/guides/hooks.html): telemetry, retries, error handling
+- [API reference]({SITE_URL}/api/index.html): full API documentation
+
+## Bundles
+
+- [llms-full.txt]({SITE_URL}/llms-full.txt): complete documentation, framework source code, and all examples in one file
+- [llms-docs.txt]({SITE_URL}/llms-docs.txt): documentation only
+- [llms-source.txt]({SITE_URL}/llms-source.txt): framework source code only
+- [llms-examples.txt]({SITE_URL}/llms-examples.txt): runnable example projects only
+
+## Optional
+
+- [GitHub repository](https://github.com/eigenwise/atomic-agents): source, issues, discussions
+- [Agent skills](https://github.com/eigenwise/atomic-agents/tree/main/claude-plugin/atomic-agents): installable skills for coding assistants (`npx skills add eigenwise/atomic-agents`)
+- [PyPI package](https://pypi.org/project/atomic-agents/): `pip install atomic-agents`
+"""
+
+
def write_to_file_and_copy(output_file: Path, content: str):
"""Write content to file and copy to HTML build directory if it exists."""
with open(output_file, "w", encoding="utf-8") as f:
@@ -277,6 +320,10 @@ def main():
print("\nGenerating llms-full.txt...")
full_content = generate_full_content()
write_to_file_and_copy(OUTPUT_FULL, full_content)
+
+ # Generate the spec-compliant index
+ print("\nGenerating llms.txt index...")
+ write_to_file_and_copy(OUTPUT_INDEX, generate_index())
print("\n" + "=" * 40)
print("Successfully generated all llms.txt files!")