Sync the hosted neon skill and drop git SHA pins

[andrelandgraf]

Problem

Agents that load https://neon.com/docs/ai/skills/neon/SKILL.md are told to run neon link --agent. That flag is gone from the CLI. Those steps fail.

The claimable reference does the same after the human signs in with neon auth: neon link --agent, then neon env pull.

Diagnosis

public/docs/ai/skills/ is a committed copy of upstream skill trees. website#5646 set the neon skill's ref to 5460c18205b8f7a5bb3bafa173b82e5f53d7f605 so the hosted files could match agent-skills#99 before that work was on main. agent-skills#100 then dropped --agent from neon link on main. The pin left neon.com on the old commit.

config/skills.json had a ref field. src/scripts/sync-skills.js and scripts/check-skills-sync.mjs fetched it. That is how a hosted skill sits on a SHA while main moves.

The user-facing interface

Hosted SKILL.md useful CLI commands:

neon link

Hosted references/claimable-neon.md, after claim, once the human has signed in with neon auth:

When `reconciled` is true, the pre-claim `DATABASE_URL` no longer works. Auth and Data API URLs stay if they were granted. The human signs in with `neon auth`. Then the agent runs `neon link` and `neon env pull` to write the new `DATABASE_URL`. `neon link` discovers the project after that sign-in.

neon init --agent in that skill is unchanged:

npx neon@latest init --agent

config/skills.json:

{
  "primary": "neon-postgres",
  "skills": [
    { "name": "neon-postgres" },
    { "name": "neon-postgres-egress-optimizer" },
    { "name": "neon-postgres-branches" },
    { "name": "neon" },
    {
      "name": "neon-postgres-agent-platforms",
      "repo": "neondatabase/neon-for-agent-platforms"
    },
    { "name": "neon-object-storage" },
    { "name": "neon-ai-gateway" },
    { "name": "neon-functions" }
  ]
}

neon-postgres-agent-platforms still sets repo and tracks that repo's main.

Sync and the drift check fetch main. A present ref field throws, including "main":

config/skills.json skill "neon" has "ref": "main". Hosted skills always track main; remove the field.

Also in here

Neon skill digests in public/.well-known/agent-skills/index.json and public/docs/.well-known/agent-skills/index.json match the updated SKILL.md bytes.

The Skills Read-Only workflow comment no longer describes a pin in config/skills.json.

scripts/check-skills-sync.mjs uses the same resolveSkillRef helper as src/scripts/sync-skills.js.

Verification

npm run test:unit:run -- src/scripts/sync-skills.test.js

11 passed. Cases added:

• resolveSkillRef returns main when the skill has no ref
• it throws when ref is present, including "main", a SHA, null and undefined
• config/skills.json has no ref key on any skill

GITHUB_TOKEN=... node scripts/check-skills-sync.mjs

All 8 configured skills match upstream main. neon is 2 files from neondatabase/agent-skills@main. neon-postgres-agent-platforms is 28 files from neondatabase/neon-for-agent-platforms@main.

Live neon.com URLs were not fetched. They update when this deploys.

For your attention

• A hosted skill change has to be on the source repo's main before sync. Putting ref in config/skills.json fails sync and the drift check.
• Skill listings outside this repo are out of scope.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
neon-next	Ready	Preview	Aug 26, 2026 11:30pm