If you have worked with AI coding assistants on a real codebase, you have probably seen both sides of the experience. On a good day, they help you move faster, explain unfamiliar areas of a project, and scaffold the first draft of something useful. On a bad day, they confidently blur together concepts that should stay separate, pull in the wrong examples, or answer a library question with a command line workflow that only looks correct on the surface.
That gap is exactly what we set out to close for Web3j.
Over the past few weeks, we added a new AI-facing documentation layer to the Web3j repository: a portable skill package in SKILL.md format together with a repo-level AGENTS.md file for coding assistants. The goal was simple. If someone asks an AI tool how to build with Web3j, the assistant should respond the way a maintainer or experienced contributor would, using the right boundaries, right examples, and right defaults.
Web3j is not only a Java and Android integration library for Ethereum and Ethereum-compatible networks. It also sits in a larger ecosystem that includes command line tooling, contract wrapper generation, testing tools, OpenAPI support, privacy integrations, and a growing set of companion projects. That breadth is a strength for developers. It can also be where AI tools start making mistakes.
We saw a few failure modes:
The fix was not to produce more prose for humans to read. It was to give AI tools a better map of the project.
The first piece is a portable skill package under .agents/skills/web3j/.
At the center is a lean SKILL.md file that acts as the routing layer. It tells an assistant when to reach for getting started guidance, when to switch to CLI documentation, when to use smart contract references, and when to load companion docs for tools like OpenAPI or Unit.From there, the skill fans out into focused reference files. Instead of one long, catch-all document, each topic has a specific home:
web3j new, web3j import, web3j audit and wallet managementThe second piece is AGENTS.md at the repository root.
This file is aimed at coding assistants working directly in the repo. It gives them project context, setup commands, module boundaries, test expectations, canonical code paths, and safe defaults for how to explore and change the codebase. In practice, it answers a question that every contributor eventually asks: “If I need the real example, where should I look first?”
One of the most useful parts of this work was making the library and CLI boundary explicit.
Web3j has both:
That distinction is obvious to maintainers. It is not always obvious to an AI model. So we encoded it directly into the skill and agent files. If the user asks how to add Web3j to a Gradle project, the assistant should answer with library dependencies and Java usage. If the user asks how to scaffold a new project or audit a Solidity contract, it should answer with CLI commands. If both are relevant, it should separate them clearly instead of mixing them into a single confusing answer.
That sounds small, but it changes the quality of the response immediately.
Another lesson came up quickly: AI tools are much more useful when they can point to a concrete starter instead of describing one.We already had strong repo-grounded integration tests, but we wanted AI-facing starter assets that were easy to copy and adapt. So we added runnable example scaffolds for event subscriptions and then expanded that work with a fuller ERC20 example.
That ERC20 starter brings several parts of the Web3j ecosystem together in one place:
It is not meant to be flashy. It is meant to be reliable. When someone asks an assistant for a basic ERC20 example with Web3j or for a quick event-listening scaffold that actually runs, the assistant now has a concrete answer path instead of a hand-wavy one.
We also reviewed the Web3j v5.0.3 documentation and updated the skill package to match it where it mattered. That included:
This matters because AI-facing documentation can drift just as easily as user-facing documentation. If the assistant is working from stale assumptions, it will produce stale answers. The only way around that is to treat AI guidance as real project documentation that deserves maintenance.
There is also a contributor story here, not just a consumer story.
The new contribution guidance inside the skill package points assistants toward the same expectations human contributors follow today: bring a real reproducer when reporting a bug, use Spotless for formatting and take feature proposals through the community discussion path before opening a GitHub issue.
That might seem secondary, but it is part of the same goal. If we are going to let AI tools participate in open source workflows, they should be taught the workflow not just the API surface.
Why this is worth doing nowAI coding tools are no longer a novelty in developer workflows. They are already being used to explore repos, explain APIs and draft new code. The question is not whether they will show up in a project like Web3j. The question is whether they will show up with context.
By adding skills and agent files directly to the repository, we are making that context explicit.
We are telling assistants:
There is more we can do to improve runnable scaffolds, expand example coverage and keep the skill package aligned with future releases. There is also room to keep refining how AI tools navigate the Web3j ecosystem, especially as more companion libraries and workflows mature.
Web3j has always tried to make Ethereum development more approachable for Java and Android developers. Extending that same practicality to AI-assisted workflows feels like a natural next step.
If you are using Web3j with AI tooling today, we would love to hear where it helps, where it still stumbles and what examples you want to see next.
Have a question or want to get involved? Join us on Discord or open an issue on GitHub. Web3j is an LF Decentralized Trust project.