Should agentic skill files be elsewhere ?

[Darafei "Komяpa" Praliaskouski]

Hi,

First, about why it is like this now.

AGENTS.md: I set it up like this when making web-based hosted `codex` to
cleanly implement tasks. It starts with almost empty docker every time and
if you don't steer it to install dependencies or run tests it tends to skip
those and leave fixes half baked. This is what protects postgis from a
storm of bad AI PRs.

skills: started from
https://lists.osgeo.org/pipermail/postgis-devel/2025-November/030663.html
where Mat Arye requested the input on the skills of postgis to be included
into their pg-aiguide mcp. I've pulled up the postgis-related AGENTS lines
that I have on my production workflows and added it there. Later they had
feedback that some of it was overlapping the postgres skills they have
elsewhere, thus the split.

Now, the concerns I heard:

 - Paul's concern is that AGENTS is too specific. I agree it might be, but
it did not cause any problems for me so far - it clearly marks assumptions
at the top and agents nowadays (7 months is a lot of time...) seem smart
enough to see if it's not their precise case. What happens in practice is
that it skips over the parts of installing dependencies if they're
available through other means and on the developer machine that ends up
fine. If you have observed actual issues, I'd be happy to adjust it.

 - Sandro's concern that skills need to be moved elsewhere. I agree here
that location is up for discussion. In general, it is no different from the
docs and probably can live under docs.

The reason we need separate "kind" of docs for LLMs is because they are
different kind of consumer: normal users "don't know anything" when
starting to work with PostGIS and need basic introduction. LLMs "have seen
it all" around the internet, and instead need to rapidly unlearn the bad
and obsolete examples and be guided toward latest best practices, while
specifically calling out the ones replaced by it. There's too many
ST_Buffer(geom,0) on the internet to get it to pick ST_MakeValid as a first
option without it. I think it may be useful for humans too, as a cheat
sheet or something like that.

I don't think it belongs in a separate repo any more than docs belong to a
separate repo (and I hope this will not trigger "let's move docs out to
separate repo").

Another thing that may be useful to get raised: how tied are we to having
docs as xml? I think gdal moved to rst and it has made it a little easier
to navigate the sources of the docs on the file level.

Thanks,
Darafei.


On Tue, Jun 9, 2026 at 1:36 PM Sandro Santilli <strk at kbt.io> wrote:

> On Mon, Jun 08, 2026 at 11:01:06AM -0700, Paul Ramsey wrote:
>
> > I do know I was a little nonplussed to read it and find it spelling out
> > in specificity a development setup that… was nothing like what I do,
> > and therefore would lead any agent I happened to use absolutely astray.
>
> That spelling is also present in AGENTS.md since its introduction
> in commit d7c5ead4d9998d34b6a7753bf757981ffdefb326 (Sat Oct 18 00:15:20
> 2025 +0400)
>
> The file format is documented in https://agents.md/, which rightfully
> doesn't mention a specific tool, so I'd be in favor of steering that
> file ALSO in a way that is more open-source and local-inference-first
> friendly.
>
> Darafai: what do you think ? Since it was you introducing both AGENTS.md
> and the skill/s directory, I'd prefer if was you driving any change.
>
> --strk;
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/postgis-devel/attachments/20260609/20443e62/attachment-0001.htm>