From ffcdca567bd460af080734598762112a9af6857e Mon Sep 17 00:00:00 2001 From: Eigenwise Date: Sat, 18 Jul 2026 10:24:13 +0200 Subject: [PATCH 1/2] Add cross-tool AI distribution: npx skills path, llms.txt index, Context7 config The plugin's skills already follow the cross-tool agent-skills format, and npx skills discovers them through .claude-plugin/marketplace.json. Tested against this repo: all six plugin skills surface. The maintainer release skill leaked into that discovery too, so it now carries metadata.internal: true (hidden from distribution, still loads locally). README gains an AI-Assisted Development section: plugin install for Claude Code, npx skills for everything else, llms bundle links, and Context7. The plugin README documents the npx path alongside the existing install routes. The docs site served its llms bundles only under /_static/ (verified: root URLs 404 live). generate_llms_files.py now also emits a spec-compliant llms.txt index (small markdown nav with key API facts, guide links, and bundle links; all URLs verified against the live site), and CI copies index + bundles to the site root where the convention expects them. context7.json at the repo root controls Context7 indexing and surfaces the v2 API rules (top-level imports, generics, Instructor-wrapped client, docstring requirement, provider knobs) to assistants that pull docs from there. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/skills/release/SKILL.md | 2 ++ .github/workflows/docs.yml | 9 +++-- README.md | 32 ++++++++++++++++++ claude-plugin/atomic-agents/README.md | 10 ++++++ context7.json | 16 +++++++++ scripts/generate_llms_files.py | 47 +++++++++++++++++++++++++++ 6 files changed, 114 insertions(+), 2 deletions(-) create mode 100644 context7.json diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index 655ac179..1b625da2 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 5b7f0816..89e8df09 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 094ed797..d0fed80d 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 c41e0886..24eabc33 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 00000000..12a1fda4 --- /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 6fb22945..c497de70 100644 --- a/scripts/generate_llms_files.py +++ b/scripts/generate_llms_files.py @@ -22,11 +22,14 @@ 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!") From 25531d918689b632e2f6b9731d58f3800375867e Mon Sep 17 00:00:00 2001 From: Eigenwise Date: Sat, 18 Jul 2026 10:25:08 +0200 Subject: [PATCH 2/2] Update codebase map for llms.txt index and context7.json Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/.codebase-info/.map-state.json | 6 +++--- .claude/.codebase-info/directory-structure.md | 3 ++- .claude/.codebase-info/tech-landscape.md | 6 +++--- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/.claude/.codebase-info/.map-state.json b/.claude/.codebase-info/.map-state.json index 4d85b422..268e8a2f 100644 --- a/.claude/.codebase-info/.map-state.json +++ b/.claude/.codebase-info/.map-state.json @@ -2,7 +2,7 @@ "tool": "codebase-mapper", "version": "2.8.0", "mappedAt": "2026-07-18", - "gitCommit": "7e85456d9984483b29211bff1dd98820409e9635", + "gitCommit": "ffcdca567bd460af080734598762112a9af6857e", "documents": [ "architecture.md", "tech-landscape.md", @@ -18,8 +18,8 @@ "hashes": { "INDEX.md": "17eaa0ba82f159465e126597aac349c6e4429330887b58742636734e15854313", "architecture.md": "7c908f047e6b0f08824ccd7c3f674ad47bd547dde234d0bd424a6d2784c0cbb6", - "tech-landscape.md": "a9052f4bba3742e79556a49c888424e6d9de424970e9def440c7124f45ec6a41", - "directory-structure.md": "ecf7e3357b41a83e7f31e760db41ef0bcb4fdbc6f1d61bbb4daf896f425d6657", + "tech-landscape.md": "cad1a11e5e63013a10cf07657d248196d0e3e4e14203eba7b777c1c123628198", + "directory-structure.md": "7d04bf29e9005508af316e29ded0c2f082a8dca561a279faecbc682f3bf5db6f", "entry-points.md": "6bd4ccae3d975196e03fc2c4e86007eba89f1f6427232fd8adce78ec97d6b432", "modules.md": "1238c76664edb1c1667fda23f39507bcab5b760b57a3a3728d7104b2cf8032e7", "communication.md": "49741a7455b0f162881e1cfb2d797dc8e3832cc8782796bbcb8a10529f2c5a0b", diff --git a/.claude/.codebase-info/directory-structure.md b/.claude/.codebase-info/directory-structure.md index 592fc545..31ad83d7 100644 --- a/.claude/.codebase-info/directory-structure.md +++ b/.claude/.codebase-info/directory-structure.md @@ -22,8 +22,9 @@ atomic-agents/ # repo root (uv workspace) ├── atomic-examples/ # 16 runnable example apps (each its own project) ├── docs/ # Sphinx + MyST documentation (api/, guides/, examples/) ├── guides/ # DEV_GUIDE.md and contributor guides -├── scripts/ # generate_llms_files.py (llms-*.txt bundles for the docs site) +├── scripts/ # generate_llms_files.py (llms.txt index + llms-*.txt bundles) ├── pyproject.toml # package metadata, deps, [tool.black], uv workspace +├── context7.json # Context7 indexing config + v2 API rules for AI assistants ├── build_and_deploy.ps1 # version bump + uv build/publish ├── AGENTS.md # the project's own design philosophy (imported by CLAUDE.md) └── README.md diff --git a/.claude/.codebase-info/tech-landscape.md b/.claude/.codebase-info/tech-landscape.md index ecd868d0..7b7d928b 100644 --- a/.claude/.codebase-info/tech-landscape.md +++ b/.claude/.codebase-info/tech-landscape.md @@ -39,9 +39,9 @@ `pytest --cov=atomic_agents` across `atomic-agents`, `atomic-assembler`, `atomic-examples`, `atomic-forge`. - `docs.yml` — on push to `main`: build Sphinx docs, run - `scripts/generate_llms_files.py` (produces `llms-*.txt`), deploy to GitHub Pages. - The docs version needs no sync step — `docs/conf.py` reads it from the root - `pyproject.toml` via `tomllib`. + `scripts/generate_llms_files.py` (spec-compliant `llms.txt` index + `llms-*.txt` + bundles, copied to the site root), deploy to GitHub Pages. The docs version needs + no sync step — `docs/conf.py` reads it from the root `pyproject.toml` via `tomllib`. - **Release:** `build_and_deploy.ps1 [--dry]` bumps the version in `pyproject.toml`, then `uv sync` → `uv build` → `uv publish` (requires a `PYPI_TOKEN`). - **Distribution:** PyPI package `atomic-agents`; the `atomic` console script ships with it.