Claude skill for pretext authoring

[Rick Roesler]

Has anyone built this?

[Rob Beezer]

Not that I am aware of. But "they" should!

In the course of adding to the Guide, extending examples, and having Claude make
throw-away test documents, I imagine I have a pile of useful rules anhd hints
accumulated. I do not know enough yet about Skills to know if those could be
made available to somebody else usefully.

Rob


On 8/28/26 14:23, Rick Roesler wrote:
> Has anyone built this?
>
> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to pretext-dev...@googlegroups.com <mailto:pretext-
> dev+uns...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/pretext-
> dev/3debd105-533a-4c4a-8382-f81667fee2f2n%40googlegroups.com <https://
> groups.google.com/d/msgid/pretext-dev/3debd105-533a-4c4a-8382-
> f81667fee2f2n%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Rick Roesler]

I've spent quite a bit of time over the last few months developing skills for internal company use and for our customers. I can take a crack at this. My first pass will be just to have Claude crawl through all the existing documentation.

Skills are typically focused on a single task and triggered by a small set of utterances. I could imagine one or more skills that would scaffold a book, take some context and pretext-ize it, etc. In some of the work that I've done, I've created Claude plugins which are higher-level constructs that include skills and agents. I'll report back here with my ideas before I start working on it. And if anyone has suggestions, I'm eager to here them.

I expect that I'm on the verge of retirement and am looking forward to finally working on my algebra-based physics book concept. I was thinking about this while I was doing some Claude work. I would certainly build this for myself before I started anything, so why not build it for everyone?

[Rob Beezer]

Thanks, Rick. That sounds great (especially retirement!). Don't forget the
schema and all of the example documents - I think those might help where the
"real" documentation is not so good. Likely some inconsistencies, but it should
not affect much.

The pretext/pretext script will run validation (versus the schema, and also
apply a custom stylesheet for more complicated situations), and optionally
provide "terse" output for machine consumption. I would think you could have
Claude iterate with that tool until it got something error-free. And maybe
learned a few things.

Keep us posted. I can't imagine I am the only one looking to learn more about
all this in a PreTeXt context.

Rob

> <https://groups.google.com/d/msgid/pretext->
> > dev/3debd105-533a-4c4a-8382-f81667fee2f2n%40googlegroups.com
> <http://40googlegroups.com> <https://
> > groups.google.com/d/msgid/pretext-dev/3debd105-533a-4c4a-8382- <http://
> groups.google.com/d/msgid/pretext-dev/3debd105-533a-4c4a-8382->
> > f81667fee2f2n%40googlegroups.com?utm_medium=email&utm_source=footer
> <http://40googlegroups.com?utm_medium=email&utm_source=footer>>.

>
> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to pretext-dev...@googlegroups.com <mailto:pretext-
> dev+uns...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/pretext-

> dev/764d6bbc-d620-43bb-9898-81454d0a1a50n%40googlegroups.com <https://
> groups.google.com/d/msgid/pretext-dev/764d6bbc-
> d620-43bb-9898-81454d0a1a50n%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Charilaos Skiadas]

I don’t really know much about Claude skills specifically as I don’t use Claude myself, but I would say that in this direction something that would help me at least is if we introduced an AGENTS.md file ( https://agents.md/ ) at the project’s root directory, to orient agents around the codebase. This way any of us using AI agents can all share one well-designed file that is part of an open standard, rather than our own versions.

Charilaos Skiadas
Department of Mathematics
Hanover College

To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/MTAwMDAyLUZZMWVBVzY.1787958129%40pnsh.

[Rick Roesler]

Charilaos, I agree on AGENTS.md.

We should distinguish between two different audiences:

• Contributors to pretext,  pretext-cli, and any other actively-maintained repo: An AGENTS.md in the repo would orient a coding agent that is working on the repo itself. Using pretext as an example: how to run the tests, where the schema, XSL and Python live, the rebase-onto-master workflow from CONTRIBUTING.md, what not to touch.
• Authors and co-authors using PreTeXt: The AGENTS.md belongs in an author's book repo. It orients an agent that is helping write a book: this is a PreTeXt project, the source lives in source/, validate with pretext validate <target> before building, never edit generated output, here are this book's targets and conventions. This is one of the things that my pretext-authoring plugin would create as part of a book repo scaffold.

Rob: I'd be happy to author an AGENTS.md for the pretext repo. 

Oscar/Steven: same for pretext-cli

[Andrew Scholer]

I think a common set of instructions would be a great help.

But I don't think we want to check AGENTS.md into git. Doing that makes it much more fiddly to maintain your own local modified version. 

Maybe an AGENTS.shared.md file that is checked into git with AGENTS.md in the .gitignore?

An individual's AGENTS.md file could reference the shared instructions file but then specify extra considerations (like local build instructions).

Andrew

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/93d5c42c-6ca9-4559-8d45-9f218b4a30a7n%40googlegroups.com.

[Rick Roesler]

Andrew,

I agree with the concern. A contributor with local build quirks or personal preferences genuinely does want additions that don't go upstream.

The good news is that Claude and Codex already support a personal layer for exactly this purpose.

• Codex
  • ~/.codex/AGENTS.md is a personal file that applies to all your projects.
  • You can have AGENTS.md files in any folder from the repo root down to the current folder; these are concatenated.
  • Any folder can include an AGENTS.override.md which is used instead of  that folder's AGENTS.md. AGENTS.override.md is intended to be gitignored.
• Claude Code
  • ~/.claude/CLAUDE.md is a personal file that applies to all your projects.
  • You can have CLAUDE.md files in any folder from the repo root down to the current folder; these are concatenated.
  • Any folder can include a CLAUDE.local.md that is loaded in addition to that folder's CLAUDE.md. CLAUDE.local.md is meant to be gitignored.

NOTE: I'm really only familiar with Claude and Codex. The Codex support for AGENTS.override.md seems to be Codex-specific. I don't see any spec support for a local or personal file in the https://agents.md spec.

Best practice is to include an AGENTS.md and CLAUDE.md at the repo root (and in as many folders as makes sense). These should be committed and treated like CONTRIBUTING.md: canonical, maintained by the repo maintainers, and the only thing a fresh clone needs. The repo should add CLAUDE.local.md and AGENTS.override.md to .gitignore so nobody commits their personal layer by accident.

NOTE: Claude doesn't read AGENTS.md on its own. But the CLAUDE.md can be a single line "@AGENTS.md" that imports the AGENTS.md file, so really only one file needs to be maintained.

Rick

[Rick Roesler]

Andrew,

I agree with the concern. A contributor with local build requirements or personal preferences needs modifications that don't go upstream.

The good news is that Claude and Codex already support a personal layer for exactly this.

Codex

• The top-level AGENTS.md (in your .claude folder) is a personal file that applies to all your projects.

• You can have AGENTS.md files in any folder from the repo root down to the current folder; these are concatenated.

• Any folder can include an AGENTS.override.md which is used instead of that directory's AGENTS.md. AGENTS.override.md is intended to be gitignored.

Claude

• The top-level CLAUDE.md (in your .claude folder) is a personal file that applies to all your projects.

• You can have CLAUDE.md files in any folder from the repo root down to the current folder; these are concatenated.
• Any folder can include a CLAUDE.local.md that is loaded in addition to that folder's CLAUDE.md. CLAUDE.local.md is meant to be gitignored.

Best practice is to include an AGENTS.md at the repo root (and in as many folders as makes sense). These should be committed and treated like CONTRIBUTING.md: canonical, maintained by the repo maintainers, and the only thing a fresh clone needs. The repo should add CLAUDE.local.md and AGENTS.override.md to .gitignore so nobody commits their personal layer by accident.

NOTES:

• I'm really only familiar with Claude and Codex. The Codex support for AGENTS.override.md seems to be Codex-specific. I don't see any spec support for a local or personal file in the agents.md spec. I think Cursor handles this personalization via Rules.
• Claude Code doesn't read AGENTS.md natively, but CLAUDE.md can be a single line "@AGENTS.md" that imports the AGENTS.md file, so really only one file needs to be maintained.

Rick

On Saturday, August 29, 2026 at 5:08:29 PM UTC-7 asch...@chemeketa.edu wrote:

[Rick Roesler]

I created Issue 3210 for the AGENTS.md files and PR 3211

[Rob Beezer]

Dear Rick,

Sorry for the long delay in getting to this one. A variety of PreTeXt stuff has
been keeping me hopping.

I like the idea of providing some guidance for how the repo is organized and how
to interact with it. I have a branch for The Guide, called something like
"developer-conventions" which I think intersects with this some (other parts are
more about using GitHub itself, etc).

Should we put comments on the PR, so that your assistant can consider them for
possible changes? Would that be the best way to go?

For example, we really have very little use for straight xsltproc anymore, but
a lot of this persists in the Guide. So we should not perpetuate it in this
guidance (and when I read through this a while ago I think I saw a bit too much
about xsltproc). There were some other similar itmes like that.

So I need to read throught this again, even more carefuylly, and suggest some
adjustments.

Thanks,
Rob


On 9/5/26 9:59 PM, Rick Roesler wrote:
> I created Issue 3210 <https://github.com/PreTeXtBook/pretext/issues/3210> for
> the AGENTS.md files and PR 3211 <https://github.com/PreTeXtBook/pretext/pull/3211>

>
> On Monday, August 31, 2026 at 12:56:35 PM UTC-7 Rick Roesler wrote:
>
> Andrew,
>
> I agree with the concern. A contributor with local build requirements or
> personal preferences needs modifications that don't go upstream.
>
> The good news is that Claude and Codex already support a personal layer for
> exactly this.
>
> Codex
>

> * The top-level AGENTS.md (in your .claude folder) is a personal file that

> applies to all your projects.
>

> * You can have AGENTS.md files in any folder from the repo root down to

> the current folder; these are concatenated.
>

> * Any folder can include an AGENTS.override.md <http://AGENTS.override.md>

> which is used instead of that directory's AGENTS.md. AGENTS.override.md

> <http://AGENTS.override.md> is intended to be gitignored.
>
>
> Claude
>
> * The top-level CLAUDE.md (in your .claude folder) is a personal file that

> applies to all your projects.
>

> * You can have CLAUDE.md files in any folder from the repo root down to

> the current folder; these are concatenated.

> * Any folder can include a CLAUDE.local.md <http://CLAUDE.local.md> that

> is loaded in addition to that folder's CLAUDE.md. CLAUDE.local.md

> <http://CLAUDE.local.md> is meant to be gitignored.

>
> Best practice is to include an AGENTS.md at the repo root (and in as many
> folders as makes sense). These should be committed and treated like
> CONTRIBUTING.md: canonical, maintained by the repo maintainers, and the only

> thing a fresh clone needs. The repo should add CLAUDE.local.md <http://
> CLAUDE.local.md> and AGENTS.override.md <http://AGENTS.override.md>

> to .gitignore so nobody commits their personal layer by accident.
>
> NOTES:
>

> * I'm really only familiar with Claude and Codex. The Codex support for
> AGENTS.override.md <http://AGENTS.override.md> seems to be Codex-

> specific. I don't see any spec support for a local or personal file in
> the agents.md spec. I think Cursor handles this personalization via Rules.

> * Claude Code doesn't read AGENTS.md natively, but CLAUDE.md can be a

> single line "@AGENTS.md" that imports the AGENTS.md file, so really only
> one file needs to be maintained.
>
>
> Rick
>
> On Saturday, August 29, 2026 at 5:08:29 PM UTC-7 asch...@chemeketa.edu wrote:
>
> I think a common set of instructions would be a great help.
>
> But I don't think we want to check AGENTS.md into git. Doing that makes
> it much more fiddly to maintain your own local modified version.
>

> Maybe an AGENTS.shared.md <http://AGENTS.shared.md> file that is checked

> into git with AGENTS.md in the .gitignore?
>
> An individual's AGENTS.md file could reference the shared instructions
> file but then specify extra considerations (like local build instructions).
>
> Andrew
>
> On Sat, Aug 29, 2026 at 4:43 PM Rick Roesler <yourphys...@gmail.com> wrote:
>
> Charilaos, I agree on AGENTS.md.
>
> We should distinguish between two different audiences:
>

> * *Contributors to pretext,  pretext-cli, and any other actively-
> maintained repo:* An AGENTS.md in the repo would orient a coding

> agent that is working on the repo itself. Using pretext as an
> example: how to run the tests, where the schema, XSL and Python
> live, the rebase-onto-master workflow from CONTRIBUTING.md, what
> not to touch.

> * *Authors and co-authors using PreTeXt:* The AGENTS.md belongs in

> an author's book repo. It orients an agent that is helping write
> a book: this is a PreTeXt project, the source lives in source/,
> validate with pretext validate <target> before building, never
> edit generated output, here are this book's targets and
> conventions. This is one of the things that my pretext-authoring
> plugin would create as part of a book repo scaffold.
>

> *Rob*: I'd be happy to author an AGENTS.md for the pretext repo.
> *Oscar/Steven*: same for pretext-cli

> On Saturday, August 29, 2026 at 11:23:39 AM UTC-7 cski...@gmail.com
> wrote:
>
> I don’t really know much about Claude skills specifically as I
> don’t use Claude myself, but I would say that in this direction
> something that would help me at least is if we introduced an

> AGENTS.md file ( https://agents.md/ <https://agents.md/> ) at

>>>    <https://groups.google.com/d/msgid/pretext- <https://
>>> groups.google.com/d/msgid/pretext->>
>>>     > dev/3debd105-533a-4c4a-8382-
>>> f81667fee2f2n%40googlegroups.com <http://40googlegroups.com>
>>>    <http://40googlegroups.com <http://40googlegroups.com>>
>>> <https://
>>>     > groups.google.com/d/msgid/pretext-
>>> dev/3debd105-533a-4c4a-8382- <http://groups.google.com/d/
>>> msgid/pretext-dev/3debd105-533a-4c4a-8382-> <http://
>>> groups.google.com/d/msgid/pretext-
>>> dev/3debd105-533a-4c4a-8382- <http://groups.google.com/d/
>>> msgid/pretext-dev/3debd105-533a-4c4a-8382->>
>>>     > f81667fee2f2n%40googlegroups.com?
>>> utm_medium=email&utm_source=footer
>>> <http://40googlegroups.com?utm_medium=email&utm_source=footer>
>>>    <http://40googlegroups.com?
>>> utm_medium=email&utm_source=footer

>>> <http://40googlegroups.com?utm_medium=email&utm_source=footer>>>.
>>> --
>>> You received this message because you are subscribed to the
>>> Google Groups "PreTeXt development" group.
>>> To unsubscribe from this group and stop receiving emails from
>>> it, send an email to pretext-dev...@googlegroups.com
>>> <mailto:pretext- dev+uns...@googlegroups.com>.
>>> To view this discussion visit https://groups.google.com/d/

>>> msgid/pretext- <https://groups.google.com/d/msgid/pretext->
>>> dev/764d6bbc-d620-43bb-9898-81454d0a1a50n%40googlegroups.com
>>> <http://40googlegroups.com> <https:// groups.google.com/d/
>>> msgid/pretext-dev/764d6bbc- <http://groups.google.com/d/
>>> msgid/pretext-dev/764d6bbc->
>>> d620-43bb-9898-81454d0a1a50n%40googlegroups.com?
>>> utm_medium=email&utm_source=footer

>>> <http://40googlegroups.com?utm_medium=email&utm_source=footer>>.
>>
>> --
>> You received this message because you are subscribed to the
>> Google Groups "PreTeXt development" group.
>> To unsubscribe from this group and stop receiving emails from

>> it, send an email to pretext-dev...@googlegroups.com.
>> To view this discussion visit https://groups.google.com/d/
>> msgid/pretext-dev/MTAwMDAyLUZZMWVBVzY.1787958129%40pnsh

>> <https://groups.google.com/d/msgid/pretext-dev/
>> MTAwMDAyLUZZMWVBVzY.1787958129%40pnsh>.

>
> --
> You received this message because you are subscribed to the Google
> Groups "PreTeXt development" group.
> To unsubscribe from this group and stop receiving emails from it,
> send an email to pretext-dev...@googlegroups.com.
>
> To view this discussion visit https://groups.google.com/d/msgid/

> pretext-dev/93d5c42c-6ca9-4559-8d45-9f218b4a30a7n%40googlegroups.com
> <https://groups.google.com/d/msgid/pretext-
> dev/93d5c42c-6ca9-4559-8d45-9f218b4a30a7n%40googlegroups.com?

> utm_medium=email&utm_source=footer>.
>
> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to pretext-dev...@googlegroups.com <mailto:pretext-
> dev+uns...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/

> d93bd523-2cc8-4f5a-931f-eabf50120ce1n%40googlegroups.com <https://
> groups.google.com/d/msgid/pretext-dev/d93bd523-2cc8-4f5a-931f-
> eabf50120ce1n%40googlegroups.com?utm_medium=email&utm_source=footer>.