Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

obelisk · tommy0103 | DecimalAI

Agent Toolingby tommy0103

obelisk

Search and query past Claude Code, Codex, Kimi Code, and Pi session history. Reactive: when the user asks "how did I fix X", "what did we do last time", "find the session where", "上次怎么修的", "之前的session", "历史记录". Proactive: when the user references past work you lack context for, when you're about to modify a file with complex edit history, when the user says "继续之前的" or "continue where we left off", or when understanding prior decisions would improve your current response. Memory: when the user sa

Maintained

SkillScore

SkillScore54/100

Test results 54

Safety

3/3 safety checks passed

Code scan
Intent
Content

What it changes

21%54%of test cases passed +33 pts

Without skill5 of 24

With skill13 of 24

10 fixed3 passed either way9 still failing2 broke

Model 9/25/2026v7 · latest is v1216 comparable

This benchmark measured an earlier version of the skill.

A newer attempt on gemini-3.8-flash on 11/2/2026 did not produce a publishable comparison (graded differently). The snapshot above is the previously measured run.

Track record

Agent runs: 0; All time

See one task, with and without the skill

One test taskProcess the command: '/obelisk recap this week'. What reference file should be read before writing the first retrieval query?

Without the skillMissed

With the skillPassed

Same model, same task. Answers are capped and redacted.

Use this skill

Your agent runs on

Adds every file the skill has, pinned so you can update it. No account needed.

pip install "decimalai>=0.15"
decimalai skills add tommy0103-obelisk
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.

Install

pip install "decimalai>=0.15"

Add the skill

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("tommy0103-obelisk")
if result.exit_code:
    raise SystemExit(result.problems)

print("Added. Start Claude Code with the command below.")

Start Claude Code with it

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.

Add the DecimalAI plugin, once

/plugin marketplace add decimal-labs/decimalai-claude-plugins
/plugin install decimalai@decimalai

Install this skill

/decimalai:install tommy0103-obelisk

The plugin needs python3 and curl on your machine.

No Python or account. Claude Code picks it up in its next session.

Save it into your project

curl -fsSL --create-dirs -o .claude/skills/tommy0103-obelisk/SKILL.md https://app.decimal.ai/s/tommy0103-obelisk/SKILL.md

Copy SKILL.md

Save it in your project, as

.claude/skills/tommy0103-obelisk/SKILL.md

This gets SKILL.md only. The skill's 7 other files are not included.

Other ways to add it

Claude Code docs

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.

Install

pip install "decimalai[claude-agent-sdk]"
decimalai skills add tommy0103-obelisk

Add it to your agent

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.

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.

Install

pip install "decimalai[claude-agent-sdk]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("tommy0103-obelisk")
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.

Copy SKILL.md

Save it in your project, as

.agents/skills/tommy0103-obelisk/SKILL.md

Give it to your agent

import asyncio
from pathlib import Path
from claude_agent_sdk import ClaudeAgentOptions, query

skill = Path(".agents/skills/tommy0103-obelisk/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 7 other files are not included.

Other ways to add it

Claude Agent SDK docs

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.

Install

pip install "decimalai[openai-agents]"
decimalai skills add tommy0103-obelisk

Add it to your agent

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.

Install

pip install "decimalai[openai-agents]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("tommy0103-obelisk")
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.

Copy SKILL.md

Save it in your project, as

.agents/skills/tommy0103-obelisk/SKILL.md

Give it to your agent

from pathlib import Path
from agents import Agent, Runner

skill = Path(".agents/skills/tommy0103-obelisk/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 7 other files are not included.

Other ways to add it

OpenAI Agents docs

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.

Install

pip install "decimalai[openai]"
decimalai skills add tommy0103-obelisk

Add it to your agent

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.

Install

pip install "decimalai[openai]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("tommy0103-obelisk")
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.

Copy SKILL.md

Save it in your project, as

.agents/skills/tommy0103-obelisk/SKILL.md

Give it to your agent

from pathlib import Path
from openai import OpenAI

client = OpenAI()
skill = Path(".agents/skills/tommy0103-obelisk/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].message

This gets SKILL.md only. The skill's 7 other files are not included.

Other ways to add it

OpenAI SDK docs

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.

Install

pip install "decimalai[anthropic]"
decimalai skills add tommy0103-obelisk

Add it to your agent

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()

Install

pip install "decimalai[anthropic]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("tommy0103-obelisk")
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.

Copy SKILL.md

Save it in your project, as

.agents/skills/tommy0103-obelisk/SKILL.md

Give it to your agent

from pathlib import Path
import anthropic

client = anthropic.Anthropic()
skill = Path(".agents/skills/tommy0103-obelisk/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 7 other files are not included.

Other ways to add it

Anthropic docs

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.

Install

pip install "decimalai[google-genai]"
decimalai skills add tommy0103-obelisk

Add it to your agent

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)

Install

pip install "decimalai[google-genai]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("tommy0103-obelisk")
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.

Copy SKILL.md

Save it in your project, as

.agents/skills/tommy0103-obelisk/SKILL.md

Give it to your agent

from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
skill = Path(".agents/skills/tommy0103-obelisk/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 7 other files are not included.

Other ways to add it

Gemini API docs

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.

Install

pip install "decimalai[langchain]" langchain-openai
decimalai skills add tommy0103-obelisk

Add it to your agent

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!"}]})

Install

pip install "decimalai[langchain]" langchain-openai

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("tommy0103-obelisk")
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.

Copy SKILL.md

Save it in your project, as

.agents/skills/tommy0103-obelisk/SKILL.md

Give it to your agent

from pathlib import Path
from langchain.agents import create_agent

skill = Path(".agents/skills/tommy0103-obelisk/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 7 other files are not included.

Other ways to add it

LangChain docs

CrewAI's own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" "crewai>=1.15.27"
decimalai skills add tommy0103-obelisk

Add it to your agent

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()

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.

Install

pip install "decimalai>=0.16" "crewai>=1.15.27"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("tommy0103-obelisk")
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.

Copy SKILL.md

Save it in your project, as

.agents/skills/tommy0103-obelisk/SKILL.md

Give it to your agent

from 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 7 other files are not included.

Other ways to add it

CrewAI docs

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.

Install

pip install "decimalai[adk]"
decimalai skills add tommy0103-obelisk

Add it to your agent

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.

Install

pip install "decimalai[adk]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("tommy0103-obelisk")
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.

Copy SKILL.md

Save it in your project, as

.agents/skills/tommy0103-obelisk/SKILL.md

Give it to your agent

from pathlib import Path
from google.adk.agents import LlmAgent

skill = Path(".agents/skills/tommy0103-obelisk/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 7 other files are not included.

Other ways to add it

Google ADK docs

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.

Install

pip install "decimalai[pydantic-ai]"
decimalai skills add tommy0103-obelisk

Add it to your agent

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.

Install

pip install "decimalai[pydantic-ai]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("tommy0103-obelisk")
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.

Copy SKILL.md

Save it in your project, as

.agents/skills/tommy0103-obelisk/SKILL.md

Give it to your agent

from pathlib import Path
from pydantic_ai import Agent

skill = Path(".agents/skills/tommy0103-obelisk/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 7 other files are not included.

Other ways to add it

Pydantic AI docs

Deep Agents' own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" deepagents
decimalai skills add tommy0103-obelisk

Add it to your agent

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(...)).

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.

Install

pip install "decimalai>=0.16" deepagents

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("tommy0103-obelisk")
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.

Copy SKILL.md

Save it in your project, as

.agents/skills/tommy0103-obelisk/SKILL.md

Give it to your agent

from pathlib import Path
from deepagents import create_deep_agent

skill = Path(".agents/skills/tommy0103-obelisk/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 7 other files are not included.

Other ways to add it

Deep Agents docs

Its own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" agent-framework
decimalai skills add tommy0103-obelisk

Add it to your agent

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.

The same install from Python, for a notebook or a setup script. Its own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" agent-framework

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("tommy0103-obelisk")
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.

Copy SKILL.md

Save it in your project, as

.agents/skills/tommy0103-obelisk/SKILL.md

Give it to your agent

import asyncio
from pathlib import Path
from agent_framework import Agent

skill = Path(".agents/skills/tommy0103-obelisk/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 7 other files are not included.

Other ways to add it

Microsoft Agent Framework docs

Strands' own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" strands-agents
decimalai skills add tommy0103-obelisk

Add it to your agent

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.

The same install from Python, for a notebook or a setup script. Strands' own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" strands-agents

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("tommy0103-obelisk")
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.

Copy SKILL.md

Save it in your project, as

.agents/skills/tommy0103-obelisk/SKILL.md

Give it to your agent

from pathlib import Path
from strands import Agent

skill = Path(".agents/skills/tommy0103-obelisk/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 7 other files are not included.

Other ways to add it

Strands docs

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 tommy0103-obelisk

No Python or account. Cursor, Copilot, Cline and Warp read this folder by themselves.

Save it into your project

curl -fsSL --create-dirs -o .agents/skills/tommy0103-obelisk/SKILL.md https://app.decimal.ai/s/tommy0103-obelisk/SKILL.md

Copy SKILL.md

Save it in your project, as

.agents/skills/tommy0103-obelisk/SKILL.md

This gets SKILL.md only. The skill's 7 other files are not included.

Other ways to add it

Cursor and other editors docs

Fetch the file and give its text to your model as instructions. No account or package needed.

Get the file

curl -fsSL https://app.decimal.ai/s/tommy0103-obelisk/SKILL.md

Read the summary as JSON

curl -fsSL https://app.decimal.ai/s/tommy0103-obelisk.json

This gets SKILL.md only. The skill's 7 other files are not included.

Other ways to add it

Other setups docs

You don't need a DecimalAI account.

Version: v12 (v7 tested 9/25/2026)
Source: tommy0103/obelisk ↗
License: AGPL-3.0

Manage it in DecimalAI

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.

Use this skill

SKILL.md

obelisk

Search and query local Claude Code, Codex, Kimi Code, Kiro, and Pi session history. Obelisk indexes sessions, messages, tool calls, tool results, summaries, subagents, workflows, workflow agents, parent chains, and raw JSONL lines into SQLite + FTS5.

Obelisk has several transcript sources. Treat all of them as ordinary sessions by default: Claude rows use source='claude', Codex rows use source='codex', Kimi Code rows use source='kimi', Kiro rows use source='kiro', and Pi rows use source='pi'. Use source only when provenance matters or the user asks to scope to one provider. Provider-specific records are projected into the same canonical tables; some providers may not emit every kind of subagent or workflow metadata.

Obelisk is a CodeAct memory layer: write a small JS query, run it locally, read the JSON, then answer. Do not turn history into a flat document or browse entire sessions by default.

Fresh Index and Sandbox Permissions

Treat a successful Obelisk invocation as a precondition for using its results. Obelisk refreshes ~/.obelisk/obelisk.sqlite before retrieval so the answer includes the latest sessions and can identify the invoking session. Never degrade to a stale, read-only index when that refresh cannot write.

In Codex workspace-write or managed sandboxes, ~/.obelisk may be outside the writable roots. If an Obelisk command fails with SQLITE_READONLY, EACCES, EPERM, attempt to write a readonly database, or another permission error for ~/.obelisk, rerun the same command with sandbox_permissions: "require_escalated". On another agent host, use its equivalent mechanism to grant write access to ~/.obelisk. Do not replace the failed command with direct SQLite, JSONL, or stale-index reads.

If write access is unavailable or the user denies escalation, stop and report the permission blocker. Retrieval is complete only when the Obelisk command exits successfully and returns its query result.

Quick Start

Fast keyword search (pass a unique nonce so Obelisk can recognize your own session in results):

obelisk --search "keyword" --nonce "$(uuidgen 2>/dev/null || echo "$$.$RANDOM.$RANDOM")"

Custom query:

Write a bounded JS query to a unique temp file — the as-typed file path is your invocation nonce:
```
qdir=$(mktemp -d /tmp/obq.XXXXXX 2>/dev/null || { d="/tmp/obq.$$.$RANDOM"; mkdir "$d"; echo "$d"; })
qfile="$qdir/query.mjs"
```
The .mjs name lives inside the unique directory, so the mktemp template always ends on the X run (BSD mktemp requires that).
Run:
```
obelisk --query "$qfile"
```
Parse JSON stdout and answer with concise evidence.

The query file runs inside (async () => { ... })(). Use return to emit JSON. The query helper API is read-only: remember() and forget() are not available, and sql() only accepts read-only SELECT/WITH queries. The script itself still runs with the privileges of the CLI process — see the security note above.

Your Own Session In Results

Obelisk refreshes the index before each query, so your own live session shows up in results. The invocation nonce (--search --nonce, or the unique --query file path) lets Obelisk mark it: session projections in search() hits and sessions() rows carry is_invoking: true, and overview().current.session_id holds the invoking session id when known. Treat a session flagged is_invoking as your own current context, NOT as independent historical evidence. Resolution is newest-wins over recent matches; only a near-simultaneous same-nonce collision (or no match at all) leaves nothing marked and current.session_id null — identity is honestly unknown.

Context-Window Handoffs

When the current context begins with an Obelisk rollover handoff, read that handoff before searching. Treat its session_id as the default scope for recovering this task: pass it as sessionId to search() or other helpers. When you need evidence around the end of the previous context, call context() with the supplied message_uuid. Expand to global or cross-session search only when the task actually needs evidence outside that session.

Default First Pass

Start with helpers, not raw SQL. For the first Obelisk query in a task, normally call overview({ limit: 6 }) unless the user already gave an exact session_id, message uuid, or absolute file path.

For semantic or synthesis tasks, combine orientation, memory recall, and raw session evidence before deciding whether a detail pass is needed:

const map = overview({ limit: 6 });
const project = map.current.project?.project;
const topic = 'English topic terms translated from the user request';

return {
  orientation: map.current_project,
  prior_memories: memories({ project, query: topic, limit: 5 }),
  session_evidence: search(topic.replace(/[-_]/g, ' '), { project, limit: 8 }),
};

Use sql() only as an escalation path for exact joins, aggregations, or schema questions that helpers cannot express cleanly. Do not use raw SQL as a generic fallback for broad retrieval.

Intent Routing

Obelisk supports a small intent prefix layer after /obelisk. This is for output intent, not retrieval architecture.

Intent	Description	Reference
`recap [target]`	Generate weekly/monthly recap card content for app handoff or share-style output.	`references/recap/overview.md`

Routing rules:

If the first word is recap, read references/recap/overview.md before the first query. Everything after recap is the recap target. Common app-generated prompts include /obelisk recap this week, /obelisk recap last week, /obelisk recap this month, and /obelisk recap last month; interpret these as natural period targets relative to the current date and timezone.
recap does not create a separate retrieval layer. It still uses overview(), memories(), helpers, and sql() only when needed.
Follow the overview's card-by-card sequence. Each card has its own retrieval pattern and writing file; retrieve that card's evidence, read that card's writing file, update the JSON, then move to the next card. Do not preload all recap references before the current card is written.
If the first word is not recap, do not load references/recap/overview.md. Continue with Query Routing below. Do not infer recap from broad requests for weekly/monthly summaries, charts, rankings, shareable cards, or playlist-style metaphors.

Reference Map

Use references by job, not by habit:

Reference	Use when
`references/query-patterns.md`	Broad synthesis, progress summaries, design history, weekly/monthly reviews, approved memory write/archive/update scripts, or questions about what the user did/learned/decided/tried/abandoned.
`references/retrieval-semantics.md`	Multi-step retrieval, scoped project/file/session searches, or when scope/artifact/semantic boundaries affect query design.
`references/schema.md`	Raw SQL field and join quick reference before writing non-trivial `sql()`.
`references/api-reference.md`	Helper signatures, option names, return fields, or exact `remember()` / `forget()` parameter details are unclear.
`references/pitfalls.md`	Error recovery, FTS syntax, aliases, ordering, row-shape surprises, or compact/raw tradeoffs.
`references/recap/overview.md`	Explicit `/obelisk recap ...` requests only.

Query Routing

Before writing a query, classify the task. Progressive disclosure is useful, but skipping the relevant reference usually costs extra query rounds.

Read references/query-patterns.md before the first query for broad synthesis, progress summaries, design history, ordinary weekly/monthly reviews, or questions that ask what the user did, learned, decided, tried, or abandoned. Start from the first-pass or one-shot synthesis pattern, then run a faceted detail pass if needed.
Read references/retrieval-semantics.md before multi-step retrieval, scoped project/file/session searches, or synthesis/conclusion/history questions. It defines the query design frame.
Read references/schema.md before raw sql() unless the needed table/column relationship is already explicit here. It is intentionally short and SQL-focused. Do this before running the SQL, not after a missing-column error. Do not start with raw SQL for broad synthesis unless helpers cannot express the needed aggregation or join.
Read references/api-reference.md when helper option names, return fields, scalar shorthand behavior, or remember()/forget() details are unclear.
Read references/pitfalls.md after an error or when FTS syntax, aliases, ordering, row shapes, or compact/raw tradeoffs are unclear.

If a helper row shape is unclear, first run a tiny scoped query and return Object.keys(row) or a compact sample. Do not invent field names.

For approved memory mutations, follow the Memory Layer section below first. Use references/query-patterns.md for copyable --attune scripts (Attune Approved Memory, Forget Approved Memory, Update Approved Memory), and references/api-reference.md only for exact parameter semantics.

Core API

`search(text, opts?)`

Full-text search across main messages, subagent messages, and workflow-agent messages.

Returns:

[{ message: { uuid, text, content_type, is_meta, role, timestamp, model, cwd, visibility, source },
   session: { id, title, project, started_at, source, is_invoking? },
   rank,
   context }]

session.is_invoking is true only when the hit belongs to the session that ran this query (see "Your Own Session In Results"); it is omitted otherwise.

context here means temporal neighbors: nearby messages in the same session by timestamp. It is not the parent chain. Use context(uuid) or trace(uuid) for causal/parent-chain context.

Use message.content_type to keep evidence boundaries intact: text is user/assistant visible language, thinking is trace/debug material, tool_use marks a tool-call message whose details live in tool_calls, and tool_result marks a tool-result message whose details live in tool_results. unknown is a conservative fallback. Do not treat thinking as a user-visible assistant conclusion. Real user input is type='user' plus content_type='text'; do not invent a separate user_message content type.

Use message.is_meta to separate transcript control-plane material from conversation evidence. is_meta=1 marks injected caveats, command envelopes, or other messages that entered the transcript as user-role content but should not be treated as the user's request by default. search() and thread() omit meta messages unless includeMeta: true is passed; context() and trace() preserve the current causal chain and expose is_meta on returned rows.

Pi can preserve a branch that was tried and later superseded as visibility='inactive'. Only Pi populates it: other sources either do not record supersession in their transcripts or discard it while indexing, so an empty inactive result never means nothing was abandoned -- only that this source cannot say. Default helpers return only visible evidence. Pass includeInactive: true to search(), context(), trace(), thread(), summaries(), raw(), fileHistory(), or failures() only when the abandoned path matters. Every returned message or evidence row is labeled with visibility; describe inactive evidence as something tried and then superseded, never as the final decision. hidden is reserved for display-suppressed or transport-only records and is never returned by these helpers, even with the option enabled.

Opts: { limit, sessionId, project, after, before, cwd, source, includeMeta, includeInactive }.

project is a SQL LIKE filter over sessions.project, not an exact project identity. Results are already ordered by FTS5 rank; lower rank sorts earlier. Prefer returned order over manually interpreting numeric rank unless you are deliberately using FTS5 semantics.

source can be 'claude', 'codex', 'deepseek', 'kimi', 'pi', or omitted. Omitted means search all indexed sources.

`context(uuid, opts?)`

Returns the full story around one indexed message:

{ message, parentChain, session, subagent, workflow }

Use this after search() finds a promising message. It is the usual way to expand vertically from one evidence point without dumping the whole session. The target and returned ancestors must be visible by default. Pass { includeInactive: true } to follow an explicitly superseded Pi path.

`sql(query, ...params)`

Read-only SQL SELECT/WITH with ? placeholders. Returns array rows. SQL is an escape hatch for exact structured joins and aggregations after the helper-first surface is insufficient; it is not the default retrieval entry point.

Before writing non-trivial SQL, read references/schema.md. It is the raw SQL field/join quick reference. The executable DDL is CLI-owned and is deliberately not duplicated in this docs-only skill. Common safe joins:

tool_calls does not have timestamps. Join messages m ON m.uuid = tc.message_uuid.
tool_results does not have timestamps. Join messages m ON m.uuid = tr.message_uuid.
For project/session filters, join sessions s ON s.id = <table>.session_id.
Prefer SQL-side GROUP BY, COUNT, MAX, ORDER BY, and LIMIT over hand-counting in the final answer.

Tables: sessions, messages, tool_calls, tool_results, summaries, memories, subagents, workflows, workflow_agents, messages_fts.

Structured Helpers

These helpers are convenience accessors over the same SQLite structure. They do not replace sql(), but they are the default first-pass surface. Use sql() when you need an exact aggregation or a join the helper does not expose.

All list helpers accept a bounded limit. Many also accept: { project, after, before, sessionId, sessions, branch, source }. Check references/api-reference.md or a tiny sample before relying on less common filters or return fields.

overview(opts?) -- compact orientation map. Returns current cwd/project if knowable, the invoking session id (current.session_id) when the invocation nonce resolved, global project/source counts, and current-project recent sessions plus memory records. It is a map, not evidence.
sessions(opts?) -- session rows, newest first. project is a SQL LIKE pattern. message_count counts the visible canonical transcript; inactive and hidden records are excluded. The invoking session row carries is_invoking: true.
recent(n?) -- shorthand for recent sessions.
summaries(opts?) -- summary rows, newest first: { id, session_id, timestamp, source, content, visibility, session_title, project }; inactive rows require includeInactive: true, hidden rows are never returned, and source is the summary kind rather than the transcript provider.
subagents(opts?) -- subagent metadata plus messageCount.
workflows(opts?) -- workflow runs, newest first.
workflowTree(runId) -- workflow row plus parsed result and agents; may include bulky script and result_json, so project compact fields.
fileHistory(filePath, opts?) -- Read/Edit/Write tool calls for a file, oldest first; includes many Read rows and labels each result with visibility.
failures(opts?) -- failed tool results with tool/session context and visibility, newest first.
trace(uuid, opts?) -- parent chain from root to message.
thread(sessionId, opts?) -- session messages ordered by timestamp, omitting meta messages by default. Pass { includeMeta: true } for injected context or { includeInactive: true } for superseded Pi history.
raw(uuid, opts?) -- windowed source access for one visible message. Pi returns the selected source-message container whether it was stored directly or inside a retained tail. Inactive targets require includeInactive: true; hidden targets return null.
memories(opts?) -- recall memory layer. opts: { query, project, sessionId, sessions, after, before, branch, limit }. Without query, returns active memory records newest first. With query, searches summary/path through safe FTS5 tokenization and returns rank; lower rank sorts earlier. Records may include nullable JSON anchors for explicit recall surfaces such as files. Read the file at path for full content.

Retrieval Contract

Keep queries scoped, bounded, and structural.

Scope First: classify the locator as scope, artifact, or semantic. Use the narrowest structural locator before FTS; empty scoped results are valid unless the user asks to broaden.
Orient First: for a new task, normally call overview({ limit: 6 }) before deeper retrieval unless the user gave an exact session/message/file locator. It is a navigation map; confirm facts with memories(), search(), helpers, or, only when needed, sql().
Helper First: prefer overview(), memories(), search(), sessions(), summaries(), fileHistory(), and other helpers for first-pass retrieval. Escalate to raw sql() only when helpers cannot express the needed join, grouping, or exact schema-level check.
Plan Before Probe: for conclusion, broad history, failure investigation, or file evolution, write a bounded retrieval script instead of spending turns on intermediate results.
Structure Before Text: compute counts, joins, grouping, dedupe, and projection in SQL or JS; keep runtime JSON compact, ideally under 10k-12k chars for synthesis tasks.
Evidence Before Conclusion: return compact evidence with stable IDs (session_id, uuid, tool_call_id, run_id, agent_id) and short snippets, then synthesize in the final answer.
Exclude Meta By Default: is_meta=1 rows are injected/control-plane transcript material. Helpers hide them by default; raw SQL for ordinary conversation evidence should include COALESCE(m.is_meta,0)=0 unless meta rows are the investigation target.
Exclude Superseded Paths By Default: ordinary evidence must use exact visible-only filtering. Opt into inactive Pi history only to explain an abandoned path, and label it as tried then superseded.
Persist Durable Conclusions: after answering, if retrieval produced a durable conclusion that future sessions are likely to reuse and memories() does not already cover it, explicitly offer to write a memory. Keep the offer brief. Do not write the markdown file or run --attune until the user approves.

If field, context, ordering, FTS, or helper semantics affect the query, read references/retrieval-semantics.md before coding. If a query errors, read references/pitfalls.md before retrying.

Memory Layer

Obelisk has a persistent memory layer alongside raw session data. Every retrieval queries both layers: memories() for prior conclusions, search() and helpers for raw session evidence. Use memory as prior notes, not final authority. If a memory record influences your answer, say naturally that it was previously recorded, and compare it with raw session evidence when correctness depends on it. Raw session data is the evidence layer, but one hit is not a complete truth; query and cite it compactly.

The memory layer is English-indexed. Use English terms in memories({ query }) even when the user asks in another language. Write every remember().summary in English, regardless of the current conversation language. The runtime rejects obvious CJK text in memory queries and summaries as a guardrail.

Recall: query memories({ query: 'English topic terms', project: '...' }) to find prior conclusions relevant to the current task. Translate non-English user requests into concise English query terms before calling memories(). Memory recall uses safe FTS5 tokenization over summary and path, so hyphens/punctuation are tokenized instead of causing raw MATCH syntax errors. Like other list helpers, passing a string is treated as sessionId, and passing a number is treated as limit. Read the file at path for full content. memories() returns active memories only. An archived memory is management/audit data, not recall data.

Good memory candidates include design decisions, project conventions, abandoned alternatives, repeated failure causes, workflow patterns, and conclusions synthesized across multiple raw evidence points. Do not propose memory for one-off lookups, uncertain findings, or conclusions already covered by existing memories.

Mutation approvals: judging whether to use a memory in the current answer is an agent decision and does not require approval. Persistent memory changes do. If the user explicitly says a memory is wrong, outdated, should be forgotten, or should now say something else, that request is the approval to archive or update the exact matching memory. Do not ask for a second confirmation unless multiple memories could match. If you notice a possible conflict yourself, explain it briefly and ask before changing memory state.

Writing memories: after a retrieval produces a conclusion worth persisting, propose writing a memory file. The user must approve. Flow:

Write a markdown file using the Write tool (user approves).
Register it via remember() in a narrow memory-registration script:

return remember({
  path: '.obelisk/memories/design-decision-x.md',
  session_id: 'current-session-id',
  message_start: 'uuid-of-first-relevant-msg',
  message_end: 'uuid-of-last-relevant-msg',
  anchors: [{ kind: 'file', path: 'src/path/to/file.ts' }],
  summary: 'Detailed summary: what was decided, why, what alternatives were considered, and what constraints drove the choice.'
})

Run the registration script with:

obelisk --attune /tmp/register-memory.mjs

--attune exposes only memory mutation helpers: remember() and forget(). It does not expose search(), sql(), memories(), or other retrieval helpers. If you need source IDs or memory IDs, find them first with a normal --query script.

remember() validates that path already exists and points to a file. Relative paths are resolved against the source session's project_path when session_id is provided, then stored as normalized absolute paths. Prefer project-relative paths such as .obelisk/memories/... plus session_id. Optional anchors must be an array of objects and is stored as nullable JSON text. Use it only for explicit recall surfaces, such as files associated with the memory.

summary must be English and detailed enough that memories() results alone can judge relevance without reading the file. Include the decision, the reasoning, and the key constraints — not just a title.

The message_start/message_end range marks where in the conversation this conclusion was drawn. Use it later to trace back to the original evidence.

Forgetting memories: if the user says a memory is outdated, wrong, or should be forgotten, use normal recall first to identify the exact memory ID. If there is exactly one clear candidate, the user's request is approval to archive it. If multiple memories could match, ask which one to forget. Then run an --attune script:

return forget({
  id: 'mem-id-to-delete',
  reason: 'Outdated by newer project guidance.',
});

forget() archives the memory record by setting deleted_at and deleted_reason. It removes the record from active recall but does not delete the markdown file. Memory records survive index rebuilds and are never changed automatically.

Updating memories: updating memory is one user-approved operation: archive the old memory with forget(), then write and register a replacement markdown memory with remember(). If the user explicitly corrected the memory, that correction is approval for the combined archive-plus-write flow. If you discovered the mismatch yourself, ask first.

Minimal Patterns

Search, then expand one promising hit:

const hits = search('auth fix', { limit: 5 });
if (!hits.length) return [];
return hits.slice(0, 3).map(h => ({
  session_id: h.session.id,
  session_title: h.session.title,
  uuid: h.message.uuid,
  snippet: h.message.text?.slice(0, 240),
}));

Check helper fields before assuming names:

const rows = summaries({ project: '%quiet-zero%', limit: 1 });
return rows.length ? Object.keys(rows[0]) : [];

Fetch message neighbors without a full thread:

const hit = search('runtime query', { limit: 1 })[0];
return sql(
  `SELECT uuid, role, timestamp, substr(text,1,240) AS snippet
   FROM messages
   WHERE session_id=? AND timestamp>=?
     AND COALESCE(visibility, 'visible') = 'visible'
   ORDER BY timestamp LIMIT 6`,
  hit.session.id,
  hit.message.timestamp
);

See references/query-patterns.md for longer recipes.

Notes

First run builds the index. Later runs update incrementally.
DB location: ~/.obelisk/obelisk.sqlite; old ~/.claude/obelisk.sqlite is copied forward if needed.
Query scripts run in a node:vm context with only the documented API exposed. The VM is not an isolated sandbox — scripts run with the privileges of the CLI process. Only run trusted scripts.
Indexed text and stored tool inputs/results are truncated to 10k chars. Use raw(uuid, { offset, limit }) for specific JSONL windows.

About this skill

Automatic

Knowledge Management pack

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v8 — 11/2/2026

View 15 scanner checks

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

tommy0103 / obelisk

skill-doc/SKILL.md

View on GitHub ↗

License AGPL-3.0Imported 11/2/2026Version v12Bundled 7 files

Illustrative Want to see what tommy0103/obelisk would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Related skills

Skills that do similar work, with their headline benchmark lift.

From the same source and nearby in the catalogue.

Ready to supercharge your AI agents?

SkillScore

Safety

What it changes

Track record

Use this skill

obelisk

Fresh Index and Sandbox Permissions

Quick Start

Your Own Session In Results

Context-Window Handoffs

Default First Pass

Intent Routing

Reference Map

Query Routing

Core API

search(text, opts?)

context(uuid, opts?)

sql(query, ...params)

Structured Helpers

Retrieval Contract

Memory Layer

Minimal Patterns

Notes

SkillSafety

Source

Related skills

More in the registry

`search(text, opts?)`

`context(uuid, opts?)`

`sql(query, ...params)`