Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →Important: Neon is no longer just a Serverless Postgres provider. Neon is the backend for apps and agents with Serverless Postgres, Auth, Functions, Storage, and an AI Gateway: instant, branchable, serverless.
SkillScore96/100
Test results 96
3/3 safety checks passed
13%96%of test cases passed +83 pts
Passed 22 of 23 test cases with the skill, and 3 of 23 without it.
19 fixed3 passed either way1 still failing0 broke
One test taskI want to make sure all my installed Neon agent skills are updated to the latest version before starting a new work session. What command using the skills CLI updates all Neon skills?
Adds every file the skill has, pinned so you can update it. No account needed.
pip install "decimalai>=0.15"
decimalai skills add neon
claude --plugin-dir "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents"The same install from Python, for a notebook or a setup script.
pip install "decimalai>=0.15"from decimalai import skillpkg
# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("neon")
if result.exit_code:
raise SystemExit(result.problems)
print("Added. Start Claude Code with the command below.")claude --plugin-dir "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents"Type these in a Claude Code session. No account or API key. It writes the skill and any files it bundles, and asks first when its safety rating isn't Passed.
/plugin marketplace add decimal-labs/decimalai-claude-plugins
/plugin install decimalai@decimalai/decimalai:install neonThe plugin needs python3 and curl on your machine.
No Python or account. Claude Code picks it up in its next session.
curl -fsSL --create-dirs -o .claude/skills/neon/SKILL.md https://app.decimal.ai/s/neon/SKILL.md.claude/skills/neon/SKILL.mdThis gets SKILL.md only. The skill's 1 other file is not included.
agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[claude-agent-sdk]"
decimalai skills add neonimport asyncio
from claude_agent_sdk import ClaudeAgentOptions
from decimalai.claude_agent_sdk import agent_config
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
async def main():
question = "Hello!"
async with support.run(question) as run: # one user message, one run
async for message in run.query(options=ClaudeAgentOptions(max_turns=6)):
print(message)
# In a notebook or async code: await main()
asyncio.run(main())Prefer its own loader? ClaudeAgentOptions(plugins=[skills_plugin()], skills="all") reads the same folder. Use one or the other: a skill delivered both ways reaches the prompt twice.
The same install from Python, for a notebook or a setup script. agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[claude-agent-sdk]"from decimalai import skillpkg
# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("neon")
if result.exit_code:
raise SystemExit(result.problems)
import asyncio
from claude_agent_sdk import ClaudeAgentOptions
from decimalai.claude_agent_sdk import agent_config
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
async def main():
question = "Hello!"
async with support.run(question) as run: # one user message, one run
async for message in run.query(options=ClaudeAgentOptions(max_turns=6)):
print(message)
# In a notebook or async code: await main()
asyncio.run(main())Prefer its own loader? ClaudeAgentOptions(plugins=[skills_plugin()], skills="all") reads the same folder. Use one or the other: a skill delivered both ways reaches the prompt twice.
No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.
.agents/skills/neon/SKILL.mdimport asyncio
from pathlib import Path
from claude_agent_sdk import ClaudeAgentOptions, query
skill = Path(".agents/skills/neon/SKILL.md").read_text()
options = ClaudeAgentOptions(system_prompt=f"You are a helpful agent.\n\n{skill}", max_turns=6)
async def main():
async for message in query(prompt="Hello!", options=options):
print(message)
# In a notebook or async code: await main()
asyncio.run(main())This gets SKILL.md only. The skill's 1 other file is not included.
agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[openai-agents]"
decimalai skills add neonfrom agents import Agent, Runner
from decimalai.openai_agents import agent_config
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
agent = Agent(
name=support.name,
instructions=support.instructions, # your prompt, then the skill list
tools=[*support.tools], # your tools, then load_skill
)
# In a notebook or async code: result = await Runner.run(agent, "Hello!")
result = Runner.run_sync(agent, "Hello!")Using SandboxAgent? capabilities=[Shell(), decimalai.openai_agents.sandbox_skills()] points its own loader at the same folder.
The same install from Python, for a notebook or a setup script. agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[openai-agents]"from decimalai import skillpkg
# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("neon")
if result.exit_code:
raise SystemExit(result.problems)
from agents import Agent, Runner
from decimalai.openai_agents import agent_config
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
agent = Agent(
name=support.name,
instructions=support.instructions, # your prompt, then the skill list
tools=[*support.tools], # your tools, then load_skill
)
# In a notebook or async code: result = await Runner.run(agent, "Hello!")
result = Runner.run_sync(agent, "Hello!")Using SandboxAgent? capabilities=[Shell(), decimalai.openai_agents.sandbox_skills()] points its own loader at the same folder.
No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.
.agents/skills/neon/SKILL.mdfrom pathlib import Path
from agents import Agent, Runner
skill = Path(".agents/skills/neon/SKILL.md").read_text()
agent = Agent(name="support", instructions=f"You are a helpful agent.\n\n{skill}")
# In a notebook or async code: result = await Runner.run(agent, "Hello!")
result = Runner.run_sync(agent, "Hello!")This gets SKILL.md only. The skill's 1 other file is not included.
agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[openai]"
decimalai skills add neonimport json
from openai import OpenAI
from decimalai.openai import agent_config
client = OpenAI()
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
def lookup_order(order_id: str) -> str:
return f"Order {order_id} shipped yesterday."
# Your tools, as Chat Completions takes them, and what answers each.
TOOLS = [{"type": "function", "function": {
"name": "lookup_order",
"description": "Look up the status of an order.",
"parameters": {"type": "object", "properties": {"order_id": {"type": "string"}},
"required": ["order_id"]},
}}]
FUNCTIONS = {"lookup_order": lookup_order}
question = "Where is order A1001?"
with support.run(question) as run: # one user message, one run
# run.system is your prompt, then the skill list.
messages = [{"role": "system", "content": run.system}, run.message]
while True:
reply = client.chat.completions.create(
model="gpt-5.4-mini",
messages=messages,
tools=[*TOOLS, *run.tools], # your tools, then load_skill
).choices[0].message
messages.append(reply)
if not reply.tool_calls:
break
for call in reply.tool_calls:
# load_skill is answered by the run; your own tools by FUNCTIONS.
function = FUNCTIONS.get(call.function.name)
messages.append(run.tool_result(call) or {
"role": "tool", "tool_call_id": call.id,
"content": function(**json.loads(call.function.arguments)) if function
else f"There is no tool named {call.function.name!r}.",
})
print(reply.content)
# The Responses API takes run.response_tools instead of run.tools.The same install from Python, for a notebook or a setup script. agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[openai]"from decimalai import skillpkg
# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("neon")
if result.exit_code:
raise SystemExit(result.problems)
import json
from openai import OpenAI
from decimalai.openai import agent_config
client = OpenAI()
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
def lookup_order(order_id: str) -> str:
return f"Order {order_id} shipped yesterday."
# Your tools, as Chat Completions takes them, and what answers each.
TOOLS = [{"type": "function", "function": {
"name": "lookup_order",
"description": "Look up the status of an order.",
"parameters": {"type": "object", "properties": {"order_id": {"type": "string"}},
"required": ["order_id"]},
}}]
FUNCTIONS = {"lookup_order": lookup_order}
question = "Where is order A1001?"
with support.run(question) as run: # one user message, one run
# run.system is your prompt, then the skill list.
messages = [{"role": "system", "content": run.system}, run.message]
while True:
reply = client.chat.completions.create(
model="gpt-5.4-mini",
messages=messages,
tools=[*TOOLS, *run.tools], # your tools, then load_skill
).choices[0].message
messages.append(reply)
if not reply.tool_calls:
break
for call in reply.tool_calls:
# load_skill is answered by the run; your own tools by FUNCTIONS.
function = FUNCTIONS.get(call.function.name)
messages.append(run.tool_result(call) or {
"role": "tool", "tool_call_id": call.id,
"content": function(**json.loads(call.function.arguments)) if function
else f"There is no tool named {call.function.name!r}.",
})
print(reply.content)
# The Responses API takes run.response_tools instead of run.tools.No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.
.agents/skills/neon/SKILL.mdfrom pathlib import Path
from openai import OpenAI
client = OpenAI()
skill = Path(".agents/skills/neon/SKILL.md").read_text()
reply = client.chat.completions.create(
model="gpt-5.4-mini",
messages=[
{"role": "system", "content": f"You are a helpful agent.\n\n{skill}"},
{"role": "user", "content": "Hello!"},
],
).choices[0].messageThis gets SKILL.md only. The skill's 1 other file is not included.
agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[anthropic]"
decimalai skills add neonimport anthropic
from decimalai.anthropic import agent_config
client = anthropic.Anthropic()
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
question = "Hello!"
with support.run(question) as run: # one user message, one run
answer = client.beta.messages.tool_runner(
model="claude-haiku-5-5",
max_tokens=4096,
system=run.system, # your prompt, then the skill list
tools=[*run.tools], # your tools, then load_skill
messages=[{"role": "user", "content": question}],
).until_done()The same install from Python, for a notebook or a setup script. agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[anthropic]"from decimalai import skillpkg
# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("neon")
if result.exit_code:
raise SystemExit(result.problems)
import anthropic
from decimalai.anthropic import agent_config
client = anthropic.Anthropic()
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
question = "Hello!"
with support.run(question) as run: # one user message, one run
answer = client.beta.messages.tool_runner(
model="claude-haiku-5-5",
max_tokens=4096,
system=run.system, # your prompt, then the skill list
tools=[*run.tools], # your tools, then load_skill
messages=[{"role": "user", "content": question}],
).until_done()No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.
.agents/skills/neon/SKILL.mdfrom pathlib import Path
import anthropic
client = anthropic.Anthropic()
skill = Path(".agents/skills/neon/SKILL.md").read_text()
reply = client.messages.create(
model="claude-haiku-5-5",
max_tokens=4096,
system=f"You are a helpful agent.\n\n{skill}",
messages=[{"role": "user", "content": "Hello!"}],
)This gets SKILL.md only. The skill's 1 other file is not included.
agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[google-genai]"
decimalai skills add neonfrom google import genai
from google.genai import types
from decimalai.google_genai import agent_config
client = genai.Client()
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
def lookup_order(order_id: str) -> str:
return f"Order {order_id} shipped yesterday."
# Your functions, as declarations for the model, and what answers each.
TOOLS = [{"function_declarations": [{
"name": "lookup_order",
"description": "Look up the status of an order.",
"parameters_json_schema": {"type": "object", "properties": {"order_id": {"type": "string"}},
"required": ["order_id"]},
}]}]
FUNCTIONS = {"lookup_order": lookup_order}
question = "Where is order A1001?"
with support.run(question) as run: # one user message, one run
config = types.GenerateContentConfig(
system_instruction=run.system, # your prompt, then the skill list
tools=[*TOOLS, *run.tool_params], # your functions, then load_skill
)
contents = [{"role": "user", "parts": [{"text": run.message}]}]
while True:
response = client.models.generate_content(
model="gemini-3.5-flash", contents=contents, config=config,
)
if not response.function_calls:
break
contents.append(response.candidates[0].content)
parts = []
for call in response.function_calls:
# load_skill is answered by the run; your own functions by FUNCTIONS.
# A loop of your own rather than automatic function calling, which
# raises KeyError when the model asks for a function you did not pass.
function = FUNCTIONS.get(call.name)
parts.append(run.tool_result(call) or {"function_response": {
"name": call.name, "id": call.id,
"response": {"result": function(**(call.args or {})) if function
else f"There is no function named {call.name!r}."},
}})
contents.append({"role": "user", "parts": parts})
print(response.text)The same install from Python, for a notebook or a setup script. agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[google-genai]"from decimalai import skillpkg
# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("neon")
if result.exit_code:
raise SystemExit(result.problems)
from google import genai
from google.genai import types
from decimalai.google_genai import agent_config
client = genai.Client()
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
def lookup_order(order_id: str) -> str:
return f"Order {order_id} shipped yesterday."
# Your functions, as declarations for the model, and what answers each.
TOOLS = [{"function_declarations": [{
"name": "lookup_order",
"description": "Look up the status of an order.",
"parameters_json_schema": {"type": "object", "properties": {"order_id": {"type": "string"}},
"required": ["order_id"]},
}]}]
FUNCTIONS = {"lookup_order": lookup_order}
question = "Where is order A1001?"
with support.run(question) as run: # one user message, one run
config = types.GenerateContentConfig(
system_instruction=run.system, # your prompt, then the skill list
tools=[*TOOLS, *run.tool_params], # your functions, then load_skill
)
contents = [{"role": "user", "parts": [{"text": run.message}]}]
while True:
response = client.models.generate_content(
model="gemini-3.5-flash", contents=contents, config=config,
)
if not response.function_calls:
break
contents.append(response.candidates[0].content)
parts = []
for call in response.function_calls:
# load_skill is answered by the run; your own functions by FUNCTIONS.
# A loop of your own rather than automatic function calling, which
# raises KeyError when the model asks for a function you did not pass.
function = FUNCTIONS.get(call.name)
parts.append(run.tool_result(call) or {"function_response": {
"name": call.name, "id": call.id,
"response": {"result": function(**(call.args or {})) if function
else f"There is no function named {call.name!r}."},
}})
contents.append({"role": "user", "parts": parts})
print(response.text)No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.
.agents/skills/neon/SKILL.mdfrom pathlib import Path
from google import genai
from google.genai import types
client = genai.Client()
skill = Path(".agents/skills/neon/SKILL.md").read_text()
response = client.models.generate_content(
model="gemini-3.5-flash",
contents="Hello!",
config=types.GenerateContentConfig(system_instruction=f"You are a helpful agent.\n\n{skill}"),
)This gets SKILL.md only. The skill's 1 other file is not included.
agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[langchain]" langchain-openai
decimalai skills add neonfrom langchain.agents import create_agent
from decimalai.langchain import agent_config
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
agent = create_agent(
"openai:gpt-5.4-mini",
tools=[], # your tools; the middleware adds load_skill
middleware=[support.middleware], # your prompt, the skill list and load_skill
)
result = agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})The same install from Python, for a notebook or a setup script. agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[langchain]" langchain-openaifrom decimalai import skillpkg
# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("neon")
if result.exit_code:
raise SystemExit(result.problems)
from langchain.agents import create_agent
from decimalai.langchain import agent_config
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
agent = create_agent(
"openai:gpt-5.4-mini",
tools=[], # your tools; the middleware adds load_skill
middleware=[support.middleware], # your prompt, the skill list and load_skill
)
result = agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.
.agents/skills/neon/SKILL.mdfrom pathlib import Path
from langchain.agents import create_agent
skill = Path(".agents/skills/neon/SKILL.md").read_text()
agent = create_agent("openai:gpt-5.4-mini", tools=[], system_prompt=f"You are a helpful agent.\n\n{skill}")
result = agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})This gets SKILL.md only. The skill's 1 other file is not included.
CrewAI's own skill loader reads the installed folder. No DecimalAI account needed.
pip install "decimalai>=0.16" "crewai>=1.15.27"
decimalai skills add neonimport decimalai.crewai
from crewai import Agent, Crew, Task
agent = Agent(
role="Support", goal="Help the customer", backstory="A support agent.",
llm=llm, # your own CrewAI LLM
skills=decimalai.crewai.skills(), # the installed folder
tools=decimalai.crewai.skill_tools(), # reads a skill's files, runs its scripts
)
task = Task(description="Hello!", expected_output="an answer", agent=agent)
Crew(agents=[agent], tasks=[task]).kickoff()The same install from Python, for a notebook or a setup script. CrewAI's own skill loader reads the installed folder. No DecimalAI account needed.
pip install "decimalai>=0.16" "crewai>=1.15.27"from decimalai import skillpkg
# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("neon")
if result.exit_code:
raise SystemExit(result.problems)
import decimalai.crewai
from crewai import Agent, Crew, Task
agent = Agent(
role="Support", goal="Help the customer", backstory="A support agent.",
llm=llm, # your own CrewAI LLM
skills=decimalai.crewai.skills(), # the installed folder
tools=decimalai.crewai.skill_tools(), # reads a skill's files, runs its scripts
)
task = Task(description="Hello!", expected_output="an answer", agent=agent)
Crew(agents=[agent], tasks=[task]).kickoff()No DecimalAI package. CrewAI's own loader reads the folder, and nothing pins or updates it.
.agents/skills/neon/SKILL.mdfrom pathlib import Path
from crewai import Agent, Crew, Task
agent = Agent(
role="Support", goal="Help the customer", backstory="A support agent.",
llm=llm, # your own CrewAI LLM
skills=[Path(".agents/skills")],
)
task = Task(description="Hello!", expected_output="an answer", agent=agent)
Crew(agents=[agent], tasks=[task]).kickoff()This gets SKILL.md only. The skill's 1 other file is not included.
agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[adk]"
decimalai skills add neonfrom decimalai.adk import DecimalAIPlugin, agent_config
from google.adk.agents import LlmAgent
from google.adk.apps import App
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
agent = LlmAgent(
name="support", # ADK needs a Python identifier
model="gemini-3.5-flash",
instruction=support.instruction, # your prompt, then the skill list
tools=[*support.tools], # your tools, then load_skill
)
# DecimalAIPlugin makes each invocation of runners built from this App one trace.
app = App(name="support", root_agent=agent, plugins=[DecimalAIPlugin()])Prefer ADK's own loader? SkillToolset(skills=decimalai.adk.skills(), ...) reads the same folder. Use one or the other: a skill delivered both ways reaches the prompt twice.
The same install from Python, for a notebook or a setup script. agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[adk]"from decimalai import skillpkg
# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("neon")
if result.exit_code:
raise SystemExit(result.problems)
from decimalai.adk import DecimalAIPlugin, agent_config
from google.adk.agents import LlmAgent
from google.adk.apps import App
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
agent = LlmAgent(
name="support", # ADK needs a Python identifier
model="gemini-3.5-flash",
instruction=support.instruction, # your prompt, then the skill list
tools=[*support.tools], # your tools, then load_skill
)
# DecimalAIPlugin makes each invocation of runners built from this App one trace.
app = App(name="support", root_agent=agent, plugins=[DecimalAIPlugin()])Prefer ADK's own loader? SkillToolset(skills=decimalai.adk.skills(), ...) reads the same folder. Use one or the other: a skill delivered both ways reaches the prompt twice.
No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.
.agents/skills/neon/SKILL.mdfrom pathlib import Path
from google.adk.agents import LlmAgent
skill = Path(".agents/skills/neon/SKILL.md").read_text()
agent = LlmAgent(
name="support",
model="gemini-3.5-flash",
instruction=lambda context: f"You are a helpful agent.\n\n{skill}",
)This gets SKILL.md only. The skill's 1 other file is not included.
agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[pydantic-ai]"
decimalai skills add neonfrom pydantic_ai import Agent
from decimalai.pydantic_ai import agent_config
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
agent = Agent(
"openai:gpt-4o-mini",
name=support.name,
tools=[], # your tools; the capability adds load_skill
capabilities=[support], # your prompt, the skill list and load_skill
)
# In a notebook or async code: result = await agent.run("Hello!")
result = agent.run_sync("Hello!")On the Pydantic AI harness, decimalai.pydantic_ai_harness.skills(project) uses its own loader instead.
The same install from Python, for a notebook or a setup script. agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.
pip install "decimalai[pydantic-ai]"from decimalai import skillpkg
# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("neon")
if result.exit_code:
raise SystemExit(result.problems)
from pydantic_ai import Agent
from decimalai.pydantic_ai import agent_config
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")
agent = Agent(
"openai:gpt-4o-mini",
name=support.name,
tools=[], # your tools; the capability adds load_skill
capabilities=[support], # your prompt, the skill list and load_skill
)
# In a notebook or async code: result = await agent.run("Hello!")
result = agent.run_sync("Hello!")On the Pydantic AI harness, decimalai.pydantic_ai_harness.skills(project) uses its own loader instead.
No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.
.agents/skills/neon/SKILL.mdfrom pathlib import Path
from pydantic_ai import Agent
skill = Path(".agents/skills/neon/SKILL.md").read_text()
agent = Agent("openai:gpt-4o-mini", instructions=f"You are a helpful agent.\n\n{skill}")
# In a notebook or async code: result = await agent.run("Hello!")
result = agent.run_sync("Hello!")This gets SKILL.md only. The skill's 1 other file is not included.
Deep Agents' own skill loader reads the installed folder. No DecimalAI account needed.
pip install "decimalai>=0.16" deepagents
decimalai skills add neonimport decimalai.deepagents
from deepagents import create_deep_agent
agent = create_deep_agent(model=model, **decimalai.deepagents.skills())
agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})The default backend reads files but has no shell. To run a skill's scripts, pass skills(backend=LocalShellBackend(...)).
The same install from Python, for a notebook or a setup script. Deep Agents' own skill loader reads the installed folder. No DecimalAI account needed.
pip install "decimalai>=0.16" deepagentsfrom decimalai import skillpkg
# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("neon")
if result.exit_code:
raise SystemExit(result.problems)
import decimalai.deepagents
from deepagents import create_deep_agent
agent = create_deep_agent(model=model, **decimalai.deepagents.skills())
agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})The default backend reads files but has no shell. To run a skill's scripts, pass skills(backend=LocalShellBackend(...)).
No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.
.agents/skills/neon/SKILL.mdfrom pathlib import Path
from deepagents import create_deep_agent
skill = Path(".agents/skills/neon/SKILL.md").read_text()
agent = create_deep_agent(model=model, system_prompt=f"You are a helpful agent.\n\n{skill}")
agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})This gets SKILL.md only. The skill's 1 other file is not included.
Its own skill loader reads the installed folder. No DecimalAI account needed.
pip install "decimalai>=0.16" agent-framework
decimalai skills add neonimport asyncio
from agent_framework import Agent
from decimalai.agent_framework import skills
agent = Agent(client=client, instructions="You are a helpful agent.", context_providers=[skills()])
asyncio.run(agent.run("Hello!"))It caches skills by default, so restart the process after decimalai skills update.
The same install from Python, for a notebook or a setup script. Its own skill loader reads the installed folder. No DecimalAI account needed.
pip install "decimalai>=0.16" agent-frameworkfrom decimalai import skillpkg
# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("neon")
if result.exit_code:
raise SystemExit(result.problems)
import asyncio
from agent_framework import Agent
from decimalai.agent_framework import skills
agent = Agent(client=client, instructions="You are a helpful agent.", context_providers=[skills()])
asyncio.run(agent.run("Hello!"))It caches skills by default, so restart the process after decimalai skills update.
No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.
.agents/skills/neon/SKILL.mdimport asyncio
from pathlib import Path
from agent_framework import Agent
skill = Path(".agents/skills/neon/SKILL.md").read_text()
agent = Agent(client=client, instructions=f"You are a helpful agent.\n\n{skill}")
asyncio.run(agent.run("Hello!"))This gets SKILL.md only. The skill's 1 other file is not included.
Strands' own skill loader reads the installed folder. No DecimalAI account needed.
pip install "decimalai>=0.16" strands-agents
decimalai skills add neonfrom decimalai.strands import skills
from strands import Agent
from strands.vended_tools import file_editor, shell
agent = Agent(
model=model, # always pass one: the default is Amazon Bedrock
system_prompt="You are a helpful agent.",
tools=[file_editor, shell],
plugins=[skills()],
)
agent("Hello!")Strands loads an agent's skills once, so build the agent again after decimalai skills update.
The same install from Python, for a notebook or a setup script. Strands' own skill loader reads the installed folder. No DecimalAI account needed.
pip install "decimalai>=0.16" strands-agentsfrom decimalai import skillpkg
# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("neon")
if result.exit_code:
raise SystemExit(result.problems)
from decimalai.strands import skills
from strands import Agent
from strands.vended_tools import file_editor, shell
agent = Agent(
model=model, # always pass one: the default is Amazon Bedrock
system_prompt="You are a helpful agent.",
tools=[file_editor, shell],
plugins=[skills()],
)
agent("Hello!")Strands loads an agent's skills once, so build the agent again after decimalai skills update.
No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.
.agents/skills/neon/SKILL.mdfrom pathlib import Path
from strands import Agent
skill = Path(".agents/skills/neon/SKILL.md").read_text()
agent = Agent(model=model, system_prompt=f"You are a helpful agent.\n\n{skill}")
agent("Hello!")This gets SKILL.md only. The skill's 1 other file is not included.
Adds every file the skill has, pinned so you can update it. Cursor, Copilot, Cline and Warp read this folder by themselves.
pip install "decimalai>=0.15"
decimalai skills add neonNo Python or account. Cursor, Copilot, Cline and Warp read this folder by themselves.
curl -fsSL --create-dirs -o .agents/skills/neon/SKILL.md https://app.decimal.ai/s/neon/SKILL.md.agents/skills/neon/SKILL.mdThis gets SKILL.md only. The skill's 1 other file is not included.
Give its text to your model as instructions. No account or package needed.
This gets SKILL.md only. The skill's 1 other file is not included.
Raw files: /s/neon/SKILL.md · /s/neon.json
Fetch the file and give its text to your model as instructions. No account or package needed.
curl -fsSL https://app.decimal.ai/s/neon/SKILL.mdcurl -fsSL https://app.decimal.ai/s/neon.jsonThis gets SKILL.md only. The skill's 1 other file is not included.
You don't need a DecimalAI account.
Saved prompts and skills, pinned versions, and traces of this skill in your runs. DecimalAI does not run your agent.
Claude Code reads files from your project, so DecimalAI config does not apply there.
On Claude Agent SDK: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.
On OpenAI Agents: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.
On OpenAI SDK: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.
On Anthropic: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.
On Gemini API: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.
On LangChain: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.
On CrewAI: set DECIMAL_API_KEY and add decimalai.init(crewai=True) to record runs and skill use. The skill version stays in your repo.
On Google ADK: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.
On Pydantic AI: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.
On Deep Agents: set DECIMAL_API_KEY and add decimalai.init(langchain=True) to record runs and skill use. The skill version stays in your repo.
On Microsoft Agent Framework: set DECIMAL_API_KEY and add decimalai.init(otel=True, agent_name="support") to record runs and skill use. The skill version stays in your repo.
On Strands: set DECIMAL_API_KEY and add decimalai.init(otel=True, agent_name="support") to record runs and skill use. The skill version stays in your repo.
Editors read files from your project, so DecimalAI config does not apply there.
Anywhere else: record a use with decimalai.log_skill_activation() inside a trace.
Important: Neon is no longer just a Postgres provider. Neon is a complete set of cloud backend primitives built around Lakebase Postgres, for developers, startups, and agent platforms, from Databricks — bundling Lakebase Postgres, Auth (managed Better Auth), long-running Functions, Object Storage, and an AI Gateway, all instant, branchable, and serverless.
Lakebase Postgres is the database itself. It is one product, reached two ways: through Neon, with a free plan and the full set of backend primitives above, or through Databricks, alongside the rest of the Databricks suite. Same infrastructure, same features, same engineering team. Call the database Lakebase Postgres, and use "Neon" for the brand and for this access path — not as a name for the database.
A Neon branch is an isolated, copy-on-write clone of your data, taken from its current state or from a past state within your project's retained history window. You can freely modify or delete it. It shares data with its parent until writes cause it to diverge, and those writes are stored independently as deltas.
Neon bundles several backend primitives for building apps and agents that all branch together:
Object Storage, Functions, and AI Gateway are in public beta.
Beta access features are currently available on projects in us-east-2 and eu-central-1. Before guiding a user through any of these services, confirm they are working in one of these regions. If not, they will need to create a new project in a supported region.
Neon is not a place to host your app frontend. Neon provides the backend primitives (Lakebase Postgres, Auth, Object Storage, Functions, AI Gateway) that compose with the application platform you already use.
Recommended architectures:
Full-stack app on Vercel (or Netlify) augmented with Neon — the app framework (Next.js, TanStack Start, etc.) owns your UI and routes and talks directly to your Neon services (Lakebase Postgres, Auth, Object Storage, Functions, AI Gateway).
Reach for Neon Functions when you outgrow the host's limits — a WebSocket or SSE server, long-running agents, or an MCP server that risks timing out on short, lambda-style serverless functions. As long as there is an active connection, a Neon Function can run up to 24 hours without interruption, with the added benefit of running close to your data.
Move your whole backend control plane onto Neon Functions — especially useful when the frontend is client-only rather than full-stack: TanStack Router, React Router in client mode, and similar SPAs hosted on Vercel or Netlify. The client talks directly to Neon Functions, where you build REST APIs and request/response agents. Secure these functions like any standalone REST API — verify a JWT or API key at the top of each handler (see the neon-functions skill).
Because Functions are just your backend, they compose with a full-stack app that already has one (Next.js route handlers, etc.), too.
The Neon documentation is the source of truth for all Neon-related information. Always verify claims against the official docs before responding. Neon features and APIs evolve, so prefer fetching current docs over relying on training data.
Look the page up before you fetch it — don't guess URLs! The docs index lists every available page with its URL and a short description:
https://neon.com/docs/llms.txt
Any Neon doc page can be fetched as markdown in two ways:
.md to the URL (simplest): https://neon.com/docs/introduction/branching.mdtext/markdown on the standard URL: curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branchingBoth return the same markdown content. Use whichever method your tools support.
Neon provides a set of agent skills in addition to the official documentation. When a task matches one of the rows below, work from that skill rather than from this overview. You may have some of these skills already installed, or you may need to install them.
The skills below live in the neondatabase/agent-skills repo:
| Skill | Use it for |
|---|---|
neon-postgres | Working with databases, including connections, schemas, queries, search, and autoscaling: SQL development, schema design, performance optimization, and scaling decisions. |
neon-postgres-branches | Choosing or creating the right branch type for dev, preview, test, or CI workflows. Use this skill as a slash command. |
neon-object-storage | Storing and serving files (uploads, images, blobs), including branching them with the database. |
neon-functions | Deploying long-running or streaming serverless functions — APIs, agents, SSE/WebSocket servers. |
neon-ai-gateway | Calling an LLM or routing across model providers with one credential, including discovering the branch's servable models at runtime via the OpenAI-compatible /v1/models endpoint. |
neon-postgres-egress-optimizer | Diagnosing or fixing excessive Postgres egress (network data-transfer) costs in a codebase. |
For guidance on agent platforms that provision and operate Lakebase Postgres on Neon at scale, use neon-postgres-agent-platforms, which lives in a separate repo: neondatabase/neon-for-agent-platforms.
First check whether the target skill is already installed and accessible (for example, it appears in the available skills list or its SKILL.md is present). If it is, use it directly. If it is not installed, install it via the skills CLI, if available, with npx/bunx:
npx skills add neondatabase/agent-skills -s <skill-name>
Replace <skill-name> with the skill you need (for example, neon-object-storage, neon-functions, or neon-ai-gateway). Useful flags:
-g — install globally instead of into the current project.-y — non-interactive mode (skip prompts).-a <agent-name> — pick the target agent(s) for non-interactive mode.For example, to install the object storage skill globally for a specific agent without prompts:
npx skills add neondatabase/agent-skills -s neon-object-storage -g -y -a <agent-name>
If you don't have access to the skills CLI, you can visit https://neon.com/.well-known/agent-skills for a registry of all available Neon skills and fetch them manually.
Keep the skills up to date: for every new session, update them so you are working with the latest best practices.
Use the same method that was used to install them. With the skills CLI, run the install command above with update in place of add, or run npx skills update to update all Neon skills. If the skills were installed via a plugin, they are updated automatically.
Before npx neon@latest init --agent, check whether the CLI is already authenticated:
NEON_API_KEY is setnpx neon@latest profile list -o json lists a profile whose account is not -A DEFAULT row with account: "-" and file: "missing" is not an account. If neon is not installed, or npx neon@latest profile list cannot run, that is not an account.
If none of those hold, follow Starting without a Neon account.
The easiest way to get started with Neon is to use our CLI and the project bootstrap wizard:
npx neon@latest init --agent
Use the --agent flag to run in a non-interactive, state-machine mode.
This init command will guide you through installation of suggested Neon development tools. Everything is customizable. The defaults are:
If init is run in an empty project, it will run the bootstrap command, offering to install one of our project templates.
Prefer the CLI over the MCP server unless the user instructs otherwise, the CLI is unavailable or blocked in your environment, or it is not authenticated, since it provides more capabilities, including deploying Neon Functions.
The above init command will install the Neon CLI, but the CLI can also be installed manually with npm i -g neon or bun i -g neon. For full CLI installation options, see https://neon.com/docs/cli/install.md
These commands are included in the init command but can be run manually as needed.
neon link — Interactively links the workspace to a Neon org, project, and branch, writing the IDs to a git-ignored .neon file. Run once per project. Once linked, project- and branch-scoped commands no longer need --project-id or --branch (for example, neon branch list).
neon checkout <branch-name> — Pins a different branch in .neon, creating it if it doesn't exist yet, and pulls that branch's env. It drives the Branch-First Dev Flow described below.
neon config init — Initializes a neon.ts file, which declares how you provision and manage Neon services, in the root of the project.
neon env pull — Fetches the current branch's Neon environment variables (DATABASE_URL, …) into your existing .env, or .env.local if you don't have one (override the target with --file). No branch ID needed; it reads .neon. link and checkout run this for you by default, so you rarely call it directly.
Without neon.ts it pulls the vars of every service the branch actually has (Postgres, plus Neon Auth, the Data API, and bucket AWS_* once provisioned); with neon.ts it pulls only the services declared there and errors if the branch is missing one — and the AI Gateway vars are never pulled unless neon.ts declares aiGateway.
The above init command will install the Neon MCP server globally, but it can also be installed manually using: npx -y add-mcp https://mcp.neon.tech/mcp -g -n Neon -y -a <agent-name> or through your IDE plugin.
For all available plugins, see: https://neon.com/docs/ai/ai-agents-tools.md
For full MCP server installation options, see https://neon.com/docs/ai/connect-mcp-clients-to-neon.md
Useful MCP tools to initialize a project:
list_projects — Lists the first 10 Neon projects in your account, providing a summary of each project. If you can't find a specific project, increase the limit by passing a higher value to the limit parameter.create_project — Creates a new Neon project in your Neon account. A project acts as a container for branches, databases, roles, and computes.get_connection_string — Returns your database connection string.If the Getting Started account check found credentials, use them. If a command waits on a browser (Awaiting authentication in web browser) or authentication fails, stop and ask the user to sign in (neon auth) or mint an API key. Prefer that over Claimable Neon unless they say otherwise.
If they cannot sign in or provide a key right now, ask before using Claimable Neon. Continue only after they say yes. That is a temporary workaround.
If there is no Neon account yet, follow references/claimable-neon.md. Do not run neon init --agent or neon auth on this path; those need a human Neon account. If neon claim is missing, the reference has the REST fallback. Unclaimed projects expire at project_expires_at (72 hours today). Claim codes expire in expires_in (15 minutes today). Add Auth or the Data API with neon.ts and neon deploy before or after claim.
Requests for neon.new, Claimable Postgres, claimable.neon.tech, instant Postgres, or a no-signup database are the same path.
neon.ts is Neon's branch config and infrastructure-as-code file: declare which Neon services your project's branches should have, get type-safe env vars, and program branch settings — all in TypeScript. It's the config layer for your Neon services, and it composes with the branch-first loop below. Add it with @neon/config:
npm i @neon/config
// neon.ts
import { defineConfig } from "@neon/config/v1";
export default defineConfig({
preview: {
aiGateway: true,
buckets: {
images: {
access: "private",
},
},
functions: {
imagegen: {
name: "AI SDK image agent",
source: "src/index.ts",
},
},
},
});
Every project ships with Lakebase Postgres; neon.ts lets you also declare Neon Auth and the Data API today, with Functions, buckets, and the AI Gateway under a preview block — every service for the branch composes in one file:
// neon.ts
export default defineConfig({
auth: true,
dataApi: true,
preview: {
functions: {},
buckets: {},
aiGateway: true, // see the neon-ai-gateway skill
},
});
Reconcile the declaration from the CLI — the Neon equivalent of terraform status / plan / apply:
neon status # print the branch's live config (read-only). Alias for `neon config status`.
neon config plan # dry-run diff of what apply would change (read-only)
neon deploy --env <file> # apply neon.ts. Pass --env when Function env reads process.env. Alias for `neon config apply`
apply / deploy provision the declared services and then pull the branch's env into your local .env.local (e.g. Pulled 5 Neon variables into .env.local: DATABASE_URL, …), so your local env always matches what's deployed.
neon deployneon deploy is the preferred full deployment: it applies neon.ts (services and functions) to the linked branch. neon deploy --env <file> loads that file into process.env before evaluating neon.ts, then uploads those values as Function env. Use it every time Function env reads process.env.
<file> is the gitignored file neon env pull already writes (.env if that file exists, otherwise .env.local). Env pull writes Neon-managed vars only (DATABASE_URL, NEON_AI_GATEWAY_*, …). Add every key under preview.functions.*.env to that file yourself, then pass the same path to --env.
Every declared Function env key must be a defined string. undefined (an unset process.env.X) means you listed a key you want written but the value is missing: defineConfig throws. Omit the key from neon.ts if you do not want to write it. Never coerce a missing process.env value to an empty string: that uploads "" and deletes the live key. An empty assignment in the file (KEY=) is also "". If TypeScript needs a type assertion, use process.env.X! and make sure the file actually has the value.
Use neon functions deploy when you are not applying neon.ts: a single function by slug, or a targeted --env KEY=VALUE update (that flag is not a file path).
@neon/env's parseEnv takes your neon.ts config object and returns a parsed, typed env object, validated against the services you declared. The shape of env follows your config, and missing variables are flagged with clear errors.
npm i @neon/env
import { parseEnv } from "@neon/env";
import config from "./neon";
const env = parseEnv(config);
console.log(env.postgres.databaseUrl);
console.log(env.auth.baseUrl);
By default parseEnv requires every variable your config implies. When one of your apps only uses a subset, for example when you need to read DATABASE_URL but never the unpooled URL, pass an array of env-var keys to require and validate only those. The keys are typesafe: autocomplete only offers variables your config enables, and the returned shape is narrowed to exactly what you selected (so unselected variables are neither enforced nor present).
import { parseEnv } from "@neon/env";
import config from "./neon";
// Only DATABASE_URL is required and returned; DATABASE_URL_UNPOOLED is not enforced.
const { postgres } = parseEnv(config, ["DATABASE_URL"]);
console.log(postgres.databaseUrl);
// Selecting across services — only these keys are validated.
const env = parseEnv(config, ["DATABASE_URL", "NEON_AUTH_BASE_URL"]);
console.log(env.postgres.databaseUrl, env.auth.baseUrl);
Beyond services, neon.ts can program what configuration new branches receive via the branch property — a function of the branch being evaluated that returns its settings:
// neon.ts
import { defineConfig } from "@neon/config/v1";
export default defineConfig({
auth: true,
dataApi: true,
branch: (branch) => {
if (branch.exists) {
// leave existing branches untouched
return {};
}
if (branch.name.startsWith("dev")) {
return {
ttl: "7d", // clean up the branch after 7 days
postgres: {
computeSettings: {
autoscalingLimitMinCu: 0.25, // scale to zero
autoscalingLimitMaxCu: 1, // keep it cheap
suspendTimeout: "5m",
},
},
};
}
return {};
},
});
The branch function receives the target branch (its name, whether it exists yet, whether it's the default, and more) and returns the tuning you want. Here new dev-* branches get a 7-day TTL so they clean themselves up, plus a cheap scale-to-zero compute profile, while existing branches and everything else fall through to the defaults. Because neon checkout applies this policy on create, a fresh dev-* branch comes up with these settings already in place.
Because neon.ts is TypeScript, the compiler catches invalid infrastructure before you ever deploy — and Neon encodes the actual rules (and their fixes) into the types, so the error tells you what to do rather than failing with a useless Type 'true' is not assignable to type 'never'. The canonical case: the Data API verifies requests with Neon Auth by default, so enabling it on its own is a type error on dataApi:
export default defineConfig({
dataApi: true, // type error: `dataApi` (default authProvider 'neon') requires Neon Auth
});
The message names both fixes, so pick one:
// 1. Enable Neon Auth (the default Data API auth provider):
export default defineConfig({ auth: true, dataApi: true });
// 2. Or verify a third-party IdP instead of Neon Auth:
export default defineConfig({
dataApi: {
authProvider: "external",
jwksUrl: "https://your-idp/.well-known/jwks.json",
},
});
Treat a neon.ts type error as the config telling you which services must go together — read the message, it spells out the valid combinations.
See https://neon.com/docs/reference/neon-ts.md for documentation on the neon.ts file.
Neon branches enable a branch-first development flow, which we recommend when using Neon services. This and neon.ts above are the two halves of the recommended setup — neon.ts declares what every branch should have, and the branch-first loop is how you move between those branches day to day. Each works on its own, and they compose.
Create a Neon branch any time you would create a git branch. Use the following commands if you have CLI access:
neon checkout <branch-name> — Creates the branch if it doesn't exist, or checks out the existing one, by updating only the branch pointer in .neon. Run without a name for an interactive picker. It does not touch code or local Postgres.neon env pull — Fetches the current branch's Neon environment variables into your .env (see Useful CLI Commands above). link and checkout run this for you by default, so you rarely call it directly.neon diff — Shows the schema diff between the child branch and its parent. Run this to see what changes have been made to the schema since the last branch was created and before you commit your changes.neon link # once; also pulls the linked branch's env
neon checkout dev-add-search # per feature; also pulls the branch's env
Because link and checkout pull env by default, the branch's DATABASE_URL lands in your local .env automatically — build against it, then checkout the next branch and repeat. As the agent, drive this loop yourself: run checkout between tasks.
When a neon.ts is present, neon checkout applies your policy as it creates a branch, so a fresh branch comes up with its declared settings and services already in place. That create-apply does not load --env; if Function env reads process.env, run neon deploy --env <file> after checkout (add --update-existing if checkout already created the branch). Checking out an existing branch never reconciles it — apply config changes to it explicitly with neon deploy --env <file> (alias for neon config apply). The bundled env pull also checks neon.ts against the linked branch and fails fast if the branch is missing a declared service, pointing you at neon deploy --env <file> to provision it, so your local env and the remote branch never drift apart silently.
If env vars are injected at runtime instead of written to disk — or you simply don't want secrets in the working tree — pass --no-env-pull to link / checkout and supply the env another way:
neon-env run -- <your dev command> (from @neon/env) fetches the branch's vars from your neon.ts and injects them into the child process at runtime — no .env file needed. This is the runtime counterpart to the on-disk env pull.neon-env export (from @neon/env) prints the branch's env to stdout as dotenv lines or, with --format json, JSON — for piping into another env manager rather than running a command. For example, varlock can bulk-load it from a .env.schema with @setValuesBulk(exec("neon-env export --format json"), format=json).fetchEnv from @neon/env is the programmatic version of the same thing: resolve the branch's env in code at runtime instead of shelling out to neon-env run.neon dev injects the same vars into your local dev server — it's part of Neon Functions local development (a public beta feature).When an agent should not write a local .env, instruct it (for example in your AGENTS.md) to run neon checkout <branch> --no-env-pull and rely on runtime injection.
For reading env you already have on disk (typed and validated against your neon.ts), use parseEnv — see Type-safe env vars with parseEnv above.
Neon exposes branch-scoped logs. Today they cover Neon Functions and Object Storage only. Postgres computes and the AI Gateway are coming; until then, neither emits records. Logs are region-gated like the other beta services above. us-east-2 and eu-central-1 are enabled today. A branch that can't serve logs at all answers 404 with reason: telemetry_not_enabled (the message says whether it's the wrong region or a branch not collecting telemetry yet), versus a 200 empty result when the branch is enabled but has no records in the window; an unknown branch answers reason: branch_not_found.
Use Neon CLI 3.1 or newer first. Decide which branch you are querying. Without --branch, the CLI uses the branch pinned in .neon, or the project's default branch when the workspace isn't linked. A deployed function or bucket usually lives on a different branch than the one checked out for development, so an empty result is more often the wrong branch than a missing log.
neon logs query --since 1h
neon logs query --branch production --source function --minimum-severity error --since 6h
neon logs query --source storage --since 1h --output json
neon logs fields
neon logs field-values service_name --since 1h
--source accepts function, storage, and pg_endpoint, but only function and storage return records today — pg_endpoint is accepted and comes back empty until Postgres logs ship. The window defaults to 1h on query and 6h on field-values, and cannot exceed 7d on either. If Neon reports --minimum-severity as unsupported on a branch, use --severity-text instead (an exact, case-sensitive match, e.g. ERROR); severities vary by source, so confirm what a branch carries with neon logs field-values severity_text. Run neon logs --help for the full filter and pagination interface.
--logql replaces the structured filters with a raw stream selector or line filter. Its stream label is entity_type, not source:
neon logs query --since 1h --logql '{entity_type="function"} |= "timeout"'
If the CLI is unavailable, fall back to the Neon MCP server's read-only query_logs, list_log_fields, and list_log_field_values tools.
In TypeScript applications, use @neon/sdk. Project and branch are positional, and query returns a lazy paginated iterable rather than a promise:
for await (const record of neon.logs.query(projectId, branchId, {
since: "1h",
source: "function",
})) {
console.log(record.timestamp, record.severity_text, record.message);
}
const { data: fields } = await neon.logs.fields(projectId, branchId);
const { data: serviceNames } = await neon.logs.fieldValues(
projectId,
branchId,
"service_name",
);
query's iterator always throws on error, but fields and fieldValues follow the client's throwOnError, which defaults to false and hands back { data, error }. fieldValues resolves to the whole response, not a bare array: read serviceNames.values, and treat them as an arbitrary subset whenever serviceNames.is_truncated is true.
For direct HTTP reads, authenticate with Authorization: Bearer <NEON_API_KEY> and use this branch-scoped base URL:
https://console.neon.tech/telemetry/v1/projects/{projectId}/branches/{branchId}/loki
The available endpoints are:
GET /api/v1/query_rangeGET /api/v1/labelsGET /api/v1/label/{name}/valuesThis is a read-only Loki-compatible subset, not a push endpoint or complete Loki deployment. query_range supports LogQL stream selectors and line filters, plus since or start/end, limit, and direction; it does not support aggregations, parsers, or formatting stages.
The paths above are the ones to call directly. A Loki client that builds its own paths — a Grafana data source appends /loki/api/v1 to whatever URL it is given — may need a different root, so confirm the data-source URL against the Neon docs rather than pasting this base.
Recommended: Use @neon/sdk to manage Neon resources programmatically, such as creating projects, branches, and snapshots for dev scripts, CI/CD automations, and platforms building on top of Neon.
@neon/sdk is the official TypeScript client for the Neon API: Fetch-based, zero-dependency, ESM-only, generated from Neon's OpenAPI spec with an ergonomic layer on top. It is the successor to @neondatabase/api-client (axios-based, generated-only). The old client is not deprecated and is safe to keep using, but new code should prefer @neon/sdk.
If you're building agents that generate apps from prompts, your users want to build apps, not manage databases. Industry-leading platforms like Replit and V0 create databases on Neon because it aligns with how agents work: an instant, branchable, serverless Lakebase Postgres data layer, invisible to users.
Neon features for agents:
All details here: https://neon.com/programs/agents.md
Apply for the Neon Agent Program for special program pricing here: https://neon.com/programs/agents
Neon Auth only redirects back to domains on its trusted-domains list. Anytime the domain your app runs on changes — a new production custom domain, a new deploy/preview URL, moving from localhost to a hosted environment, and so on — you must register the new domain with Neon Auth. Otherwise sign-in and OAuth callbacks fail with an invalid domain error because the redirect target isn't trusted.
The easiest way to fix this is the CLI. With the workspace linked to the project (see the branch-first flow above), add the new domain to the trusted list:
neon neon-auth domain add <domain> # e.g. neon neon-auth domain add https://app.example.com
neon neon-auth domain list # verify what's currently trusted
neon neon-auth domain delete <domain> # remove one you no longer use
If the workspace isn't linked, pass --project-id <id> (and --branch <id|name>) explicitly. For local development, neon neon-auth domain allow-localhost manages whether localhost is permitted. Register the domain before pointing users at the new URL, so they never hit the invalid domain error.
Skills that do similar work, with their headline benchmark lift.
From the same source and nearby in the catalogue.