Using Coding Agents
We acknowledge that AI tools are now a core part of many workflows. To prevent common pitfalls when using coding agents on TEI Publisher projects, we have curated and tested specific agentic skills for key tasks. The instructions cover best practices for customization and development workflows, i.e. explain which files are safe to modify, when and where to add custom files and, critically, what not to touch.
Unfortunately using agentic assistance does not remove neither the need for modelling and an engineering mindset nor standards compliance, governance and sustainability concerns.
Never blindly trust your agent and always review the result. Coding agents have a strong tendency to focus on the immediate problem at hand, messing-up other parts of the application in the process. By design they lean towards the statistically most common solution and care less about standards compliance, interoperability or respecting community best practices. As a result, the application may look great on the surface, but will not be easy to maintain in the future and cease to integrate with the broader network of TEI Publisher-based applications.
Agents can be great at coding, but they don't see the big picture or follow a vision. This still is and always should remain your job.
Jinks includes the set of guidelines and skills into every generated application. They assume that you keep the application code in a
Claude Code and Cursor will automatically pick up the instructions and skills when the agent is pointed at the application directory. For other agent types you need to check their documentation.
The relevant files are:
- AGENTS.md
-
Key information which should always be read by an agent.
- CLAUDE.md
-
Points to AGENTS.md
- .claude/skills
-
Basic set of skills. Both, Cursor and Claude, will find them in this location.
Using the Karl Barth sermons example from the gentle introduction, we would proceed as follows:
-
create the application skeleton via the Jinks web version or the command line client. Enable only the demo data profile, but nothing else.
-
download the generated application .xar (see
instructions above ) and unpack it into a directory (it's a ZIP archive). -
Point your agent at this directory: when using an IDE like Visual Studio Code or Cursor, just opening the directory in the editor should be enough. The included agents should pick up the instructions and skills automatically.
We strongly recommend working with AI agents in small, incremental steps, ensuring a competent guidance and critical review at every stage. To manage this process with confidence, break down your vision into small tasks, covering a single new feature or fix. When accomplished, commit the results to source control in logical chunks, related to a single task.
Based on the Karl Barth example, here are some prompts which should work well:
-
"switch the base, heading and content font to Albert Sans"
-
"use the attached portrait image as the splash image, the given logo file as the logo, and the remaining photo as the menubar background image"
-
"style the bible-quote epigraph at the head of each sermon"
-
"review the general spacing/typography: for example, the opener sits too close to the following text and the final hymns section isn't visually set off"
-
"bible references in the text should link to an external Bible reader: https://www.bibleserver.com/LUT/<target>, built from the reference's @target attribute"
-
"enable the 'registers' feature/profile so the app gets a sidebar listing people and places"
Jinks and TEI Publisher are designed with flexibility, interoperability, and sustainability in mind. To maintain these standards, reviewers should ensure that automated solutions do not just solve an immediate technical problem, but accord with the architectural principles above. This is a particular concern for any contributions to be incorporated into the framework.