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.mdindex 655ac17..1b625da 100644--- a/.claude/skills/release/SKILL.md+++ b/.claude/skills/release/SKILL.md@@ -2,6 +2,8 @@name: releasedescription: 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-agentsdiff --git a/.github/workflows/docs.yml b/.github/workflows/docs.ymlindex 5b7f081..89e8df0 100644--- a/.github/workflows/docs.yml+++ b/.github/workflows/docs.yml@@ -57,11 +57,16 @@ jobs:cd docsuv 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 buildrun: |- 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 artifactuses: actions/upload-pages-artifact@v3diff --git a/README.md b/README.mdindex 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 demonstratFor 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 & CLIAtomic 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.mdindex 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 projecClaude 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```bashdiff --git a/context7.json b/context7.jsonnew file mode 100644index 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.pyindex 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 codeSOURCE_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!")