Collaboration Interest: AI Guidance for PostGIS in pg-aiguide

[Darafei "Komяpa" Praliaskouski]

Hi Mat,

I'd prefer you don't strip any lines - many of those aren't
"postgis-specific" but are very often created by LLMs around postgis code
and usage scenarios. If you think they need to be put elsewhere let's
reorganize upstream but not create silent forks where you bundle the file
and remove half of it.

In other news, there is now an H3 skill file too.
https://github.com/postgis/h3-pg/blob/main/docs/SKILL.md

On Mon, Jan 5, 2026 at 4:34 PM Mat Arye <mat+postgis at tigerdata.com> wrote:

> Hi,
>
> Sorry for the delay, but I wanted to close the loop. We now have a  PR for
> a PostGIS skill based on Darafei's excellent work in pg-aiguide:
> https://github.com/timescale/pg-aiguide/pull/62. (The only changes from
> the upstream version are the removal of non-PostGIS-specific advice, which
> we have elsewhere).
>
> Thanks again!
>
> -Mat
>
>
> On Sun, Nov 30, 2025 at 12:35 AM Darafei "Komяpa" Praliaskouski <
> me at komzpa.net> wrote:
>
>> Hi,
>>
>> I've compiled this list from all my notes, leaving only PostGIS (and a
>> bit of broader SQL) related things here.
>>
>> https://gitea.osgeo.org/postgis/postgis/src/branch/master/doc/SKILL.md
>>
>> Probably some more will surface once people start using these,
>> contributions are welcome :)
>>
>> On Wed, Nov 26, 2025 at 2:10 PM Mat Arye <mat+postgis at tigerdata.com>
>> wrote:
>>
>>> Hey,
>>>
>>> This sounds great. If the SKILL.md file is maintained in the postgis
>>> repository, it would be easy for us to include it in pg-aiguide as well.
>>> Happy to share our best practices on a call or review/give feedback on a PR
>>> if any of that would be helpful.
>>>
>>> Thanks,
>>> Mat
>>>
>>> On Tue, Nov 25, 2025 at 9:01 PM Darafei "Komяpa" Praliaskouski <
>>> me at komzpa.net> wrote:
>>>
>>>> Hi,
>>>>
>>>> Sounds good. I guess we're at a time when everyone tries to collect
>>>> their own library for AGENTS.md :)
>>>>
>>>> A list of things we put together for Kontur's systems, fixing stuff
>>>> actually done wrong by LLMs one at a time:
>>>> https://github.com/konturio/AGENTS.md/blob/main/AGENTS.raw.md
>>>>
>>>> What I also learned is that while LLM is randomly forgetful about these
>>>> spaced repetition helps keep the model's attention on them.
>>>> For small lists like ours I made a simple trigram based one,
>>>>
>>>> https://github.com/konturio/AGENTS.md/blob/main/scripts/spaced_repetition.py
>>>>
>>>> LLMs write okay-ish PostGIS SQL. Where they currently totally break is
>>>> h3, as the library changed all the function names
>>>> on v3 to v4 migration, and there are subtle name differences across
>>>> different versions. A skill will be more helpful there.
>>>>
>>>> Maybe we can start SKILL.md in postgis repo so that whoever wants to
>>>> drop it into their AI and generate less-wrong, more-blessed code with
>>>> typical user error types corrected?
>>>> We're already building a cheatsheet but some common mistakes can be
>>>> listed to un-learn them at LLMs.
>>>>
>>>> I'll be happy to start and maintain this doc, I'm already doing this
>>>> anyway for my use cases.
>>>>
>>>>
>>>> On Tue, Nov 25, 2025 at 9:50 PM Mat Arye <mat+postgis at tigerdata.com>
>>>> wrote:
>>>>
>>>>> Hi All,
>>>>>
>>>>> We've started a new open-source project at Tiger Data aimed at helping
>>>>> AI agents generate higher-quality Postgres code:
>>>>> https://github.com/timescale/pg-aiguide
>>>>> For broader context, here’s the announcement blog describing the
>>>>> approach and motivations:
>>>>>
>>>>> https://www.tigerdata.com/blog/we-taught-ai-to-write-real-postgres-code-open-sourced-it
>>>>>
>>>>> As part of this work, we're adding guidance modules for major Postgres
>>>>> extensions, and PostGIS is at the top of our list. I’m reaching out to ask
>>>>> whether anyone from the PostGIS community would be interested in
>>>>> collaborating.
>>>>>
>>>>> The core idea is to provide “skills” that capture best practices,
>>>>> common pitfalls, and domain-specific patterns so that AI agents can make
>>>>> better decisions. Here is an example skill:
>>>>>
>>>>> https://github.com/timescale/pg-aiguide/blob/main/skills/design-postgres-tables/SKILL.md
>>>>>
>>>>> If there’s interest, we’d be happy to set up a call to walk through
>>>>> the approach and answer questions.
>>>>>
>>>>> Beyond skills, the project also includes semantic search over
>>>>> documentation. We currently index Postgres and TimescaleDB docs, and we
>>>>> plan to include the PostGIS manual as well. We can handle the processing,
>>>>> but wanted to check whether there’s anything unusual about the HTML manual
>>>>> that we should be aware of. We’d also appreciate any guidance on which
>>>>> versions of the manual are most important to index.
>>>>>
>>>>> Thanks for your time, and we’d welcome any feedback or involvement
>>>>> from the community.
>>>>>
>>>>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/postgis-devel/attachments/20260109/3e559f30/attachment-0001.htm>