Ready to supercharge your AI agents?

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

Get Started Free →

选品分析器 (Product Research - LLM Agent 驱动版) · LeoYeAI | DecimalAI

Researchby LeoYeAI

选品分析器 (Product Research - LLM Agent 驱动版)

基于Sorftime MCP的深度选品调研。通过LLM Agent执行多维度分析：数据采集→属性标注→交叉分析→竞品VOC→壁垒评估→选品决策评估。交互式执行，输出Markdown报告和Dashboard看板。

SkillScore

SkillScore86/100

Test results 86

Safety

3/3 safety checks passed

Code scan
Intent
Content

What it changes

23%86%of test cases passed +64 pts

Without skill5 of 22

With skill19 of 22

15 fixed4 passed either way2 still failing1 broke

Measured on gemini-3.6-flash8/3/2026v220 comparable

Track record

Agent runs: 0; All time

See one task, with and without the skill

One test taskWhen invoking category_report for nodeId 7073956011 in the US store using the API client, what data type must be used for the nodeId value?

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 product-research
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("product-research")
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 product-research

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/product-research/SKILL.md https://app.decimal.ai/s/product-research/SKILL.md

Copy SKILL.md

Save it in your project, as

.claude/skills/product-research/SKILL.md

This gets SKILL.md only. The skill's 13 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 product-research

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("product-research")
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/product-research/SKILL.md

Give it to your agent

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

skill = Path(".agents/skills/product-research/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 13 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 product-research

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("product-research")
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/product-research/SKILL.md

Give it to your agent

from pathlib import Path
from agents import Agent, Runner

skill = Path(".agents/skills/product-research/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 13 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 product-research

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("product-research")
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/product-research/SKILL.md

Give it to your agent

from pathlib import Path
from openai import OpenAI

client = OpenAI()
skill = Path(".agents/skills/product-research/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 13 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 product-research

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("product-research")
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/product-research/SKILL.md

Give it to your agent

from pathlib import Path
import anthropic

client = anthropic.Anthropic()
skill = Path(".agents/skills/product-research/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 13 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 product-research

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("product-research")
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/product-research/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/product-research/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 13 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 product-research

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("product-research")
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/product-research/SKILL.md

Give it to your agent

from pathlib import Path
from langchain.agents import create_agent

skill = Path(".agents/skills/product-research/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 13 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 product-research

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("product-research")
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/product-research/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 13 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 product-research

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("product-research")
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/product-research/SKILL.md

Give it to your agent

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

skill = Path(".agents/skills/product-research/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 13 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 product-research

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("product-research")
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/product-research/SKILL.md

Give it to your agent

from pathlib import Path
from pydantic_ai import Agent

skill = Path(".agents/skills/product-research/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 13 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 product-research

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("product-research")
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/product-research/SKILL.md

Give it to your agent

from pathlib import Path
from deepagents import create_deep_agent

skill = Path(".agents/skills/product-research/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 13 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 product-research

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("product-research")
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/product-research/SKILL.md

Give it to your agent

import asyncio
from pathlib import Path
from agent_framework import Agent

skill = Path(".agents/skills/product-research/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 13 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 product-research

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("product-research")
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/product-research/SKILL.md

Give it to your agent

from pathlib import Path
from strands import Agent

skill = Path(".agents/skills/product-research/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 13 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 product-research

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/product-research/SKILL.md https://app.decimal.ai/s/product-research/SKILL.md

Copy SKILL.md

Save it in your project, as

.agents/skills/product-research/SKILL.md

This gets SKILL.md only. The skill's 13 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/product-research/SKILL.md

Read the summary as JSON

curl -fsSL https://app.decimal.ai/s/product-research.json

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

Other ways to add it

Other setups docs

You don't need a DecimalAI account.

Version: v2, tested 8/3/2026
Source: LeoYeAI/openclaw-master-skills ↗
License: MIT

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

选品分析器 (Product Research - LLM Agent 驱动版)

定位

基于 Sorftime MCP + LLM Agent 的深度选品调研。LLM 直接执行分析逻辑，脚本仅负责数据采集和报告渲染。

核心特点：

LLM 驱动：分析、洞察、决策全部由 LLM 完成
交互式执行：逐步推进，用户可中途干预
轻量脚本：仅用于 API 调用和 Dashboard 渲染

Script Directory

脚本	用途	何时调用
`run_analysis.py`	主入口脚本：整合数据采集、分析、报告生成	推荐使用
`collect_data.py`	Sorftime 数据采集（类目、Top100、关键词、趋势）	Step 1
`get_reviews.py`	竞品差评数据采集	Step 4
`api_client.py`	Sorftime API 调用 + SSE 解析 + 编码修复	每次 API 调用
`render_dashboard.py`	生成 Dashboard 可视化看板（v3.1 修复版）	报告生成阶段
`fix_data_json.py`	数据验证和修复脚本：校验并自动修复 data.json	Dashboard 生成前
`validate_data.py`	数据验证脚本：校验 data.json 字段命名和数据一致性	报告生成前

脚本职责：

不做分析判断：所有分析由 LLM 完成
不做复杂计算：交叉分析让 LLM 从数据中发现
仅做数据搬运：API → 结构化数据

推荐使用方式：

# 阶段1：数据采集（基础版 Dashboard）
python scripts/run_analysis.py "earbuds" US

# 阶段2：LLM 分析完成后，生成最终版报告
python scripts/run_analysis.py "earbuds" US --final

# 其他选项
python scripts/run_analysis.py "earbuds" US --collect-only  # 仅数据采集
python scripts/run_analysis.py "earbuds" US --no-reviews     # 跳过差评采集

执行流程（两阶段）

重要：选品分析分为两个阶段，数据采集由脚本自动完成，LLM 分析需要人工参与。

阶段1：数据采集（脚本自动）

python scripts/run_analysis.py "keyword" US

输出：

data.json - 基础数据结构（不含分析结论）
dashboard.html - 基础版看板（不含决策评分、VOC 等）
raw/ - 原始数据文件

脚本自动完成：

类目搜索 → 获取 nodeId
Top100 产品数据采集
关键词数据采集
类目趋势数据采集
竞品差评采集
市场分析（价格区间、品牌分布）

阶段2：LLM 分析（交互式）

必须完成的 LLM 分析任务：

步骤	任务	输出到 data.json
1	属性标注	`product_types`、`dimensions_analysis`
2	交叉分析	`cross_analysis`
3	VOC 分析	`voc_analysis.dimensions`
4	壁垒评估	`barriers`
5	决策评估	`decision` (overall_score, verdict)

完成后运行：

python scripts/run_analysis.py "keyword" US --final

--final 参数会：

✅ 验证分析数据完整性
✅ 更新 data.json
✅ 生成完整版 Dashboard（含决策评分、VOC 等）
✅ 如果数据不完整，会提示缺失的字段

数据完整性检查

也可以单独检查数据完整性：

python scripts/render_dashboard.py data.json --check

输出示例：

✓ 数据完整，可以渲染完整版 Dashboard
  包含: decision.overall_score, voc_analysis.dimensions, barriers, cross_analysis

或

⚠️ 数据不完整，缺少以下字段:
  - decision.overall_score
  - voc_analysis.dimensions

ℹ️ 请先完成 LLM 分析，然后重新运行渲染

执行流程（交互式）

Step 0: 信息收集

📋 选品分析 - 信息确认

1. 产品/类目关键词：[用户提供]
2. 目标站点：[US/GB/DE/FR/IT/ES/CA/JP，默认US]
3. 选品场景：[新手入门/蓝海发现/季节性/品牌打造/定向品类]
4. 约束条件（可选）：
   - 价格区间：如 $10-40
   - 月销量：如 > 1000
   - 预算：如 10万人民币

Step 1: 数据采集（增强版 v3.0）

API 调用顺序：

步骤	API	输出	说明	优先级
0.5	`search_categories_broadly`	blue_ocean_categories.json	【新增】蓝海市场发现	📋 按需
1.1	`category_name_search`	category_info.json	按产品名搜索类目（使用 searchName 参数）	⛔ 必调
1.2	`category_report`	top100.json	Top100 产品数据	⛔ 必调
1.3	`keyword_detail` × 3+	keywords.json	多维度关键词对比	⛔ 必调
1.4	`category_trend`	trend.json	新品占比趋势	⛔ 必调
1.5	`keyword_extends`	keyword_extends.json	【新增】关键词延伸词（维度发现）	📋 推荐
1.6	`potential_product`	potential_products.json	【新增】潜力产品发现	📋 推荐
1.7	`product_detail` × 6-10	products.json	竞品详情（按需）	📋 按需
1.8	`product_reviews` × 6-10	reviews.json	竞品差评（按需）	📋 按需

⚠️ 重要：API 参数说明（v3.0）

category_name_search 参数：{"amzSite": "US", "searchName": "bluetooth speaker"}
- 正确的类目搜索 API，参数名是 searchName
search_categories_broadly 参数（蓝海发现）：{"amzSite": "US", "top3Product_sales_share": 0.4}
potential_product 参数（潜力产品）：{"amzSite": "US", "monthlySales_min": 500}
keyword_extends 参数（延伸词）：{"amzSite": "US", "keyword": "bluetooth speaker"}
category_report 参数：{"amzSite": "US", "nodeId": "7073956011"}
- nodeId 是字符串类型

脚本调用方式：

# 方法1: 使用 collect_data.py (推荐)
from scripts.collect_data import collect_data
result = collect_data("bluetooth speaker", "US")

# 方法2: 使用 api_client.py
from scripts.api_client import SorftimeClient

client = SorftimeClient()

# 获取类目ID（正确的方式）
category = client.search_category_by_product_name("US", "bluetooth speaker")
node_id = category[0]['nodeId']

# 获取Top100
top100 = client.get_category_report("US", node_id)

# 获取关键词详情
keywords = client.get_keyword_detail("US", "bluetooth speaker")

Step 2: 属性标注（LLM 驱动）

LLM 任务：从 Top100 标题中提取关键差异化维度

## 属性标注任务

基于以下 Top100 产品标题，提取 3-6 个关键差异化维度：

### 标题样本
[提供 Top20-30 标题作为样本]

### 提取要求
1. 识别差异化维度（如：功率、防水、续航、形态等）
2. 为每个产品标注维度值
3. 标注置信度（高/中/低）

### 输出格式
| ASIN | 功率 | 防水 | 续航 | ... | 置信度 |

对低置信度产品：调用 product_detail 补充验证

Step 3: 交叉分析（LLM 直接发现）

LLM 任务：从标注数据中发现供需缺口

## 交叉分析任务

基于以下已标注的 Top100 产品数据，执行交叉分析：

### 数据
[提供标注后的产品数据]

### 分析要求
1. 选择 2-3 对有意义的维度组合（如：功率×价格、防水×场景）
2. 识别：空白点（0产品）、薄供给（≤2产品）、高需求低供给
3. 分析每个缺口的原因（技术限制？需求不存在？被忽视？）
4. 按机会价值排序

### 输出格式
| 维度组合 | 状态 | 产品数 | 月销量 | 原因分析 | 机会评级 |

关键点：让 LLM 直接从数据中发现规律，而不是用 Python 脚本计算

Step 4: 竞品与 VOC 分析

竞品选择逻辑表（LLM 按细分段选择）：

ASIN	品牌	选择理由	类型	覆盖维度
[LLM 选择 6-10 个代表性竞品]

⛔ 差评维度归类（关键步骤）

必须按维度归类，禁止按 ASIN 组织

LLM 任务：将竞品差评按属性维度归类，并映射到品牌能力和产品方案

输入：competitor_reviews.json（按 ASIN 组织的原始差评）输出：data.json 中的 voc_analysis 字段（按维度归类）

归类要求：

识别主要维度（3-6 个）- 基于差评内容提取痛点类别
每个维度包含：
- dimension: 维度名称（如：音质/音量、舒适度、续航）
- pain_point: 痛点描述
- frequency: 提及频次
- percentage: 占比（如 "32%"）
- affected_brands: 涉及品牌列表
- brand_opportunity: 品牌/供应链能力如何解决
- product_solution: 具体产品改进方向

输出格式示例：

{
  "voc_analysis": {
    "dimensions": [
      {
        "dimension": "音质/音量",
        "pain_point": "音量太小，户外听不清",
        "frequency": 45,
        "percentage": "32%",
        "affected_brands": ["SHOKZ", "JLab"],
        "brand_opportunity": "有14.2mm大动圈供应链",
        "product_solution": "14.2mm动圈+音量增强模式"
      }
    ],
    "summary": "主要痛点集中在音质(32%)、舒适度(28%)、续航(18%)"
  }
}

禁止的输出方式：

❌ 按 ASIN 组织：{"B0XXX": {"reviews": [...]}}
❌ 缺少频次/占比数据
❌ 缺少品牌机会和产品方案映射

Step 5: 评估与决策

进入壁垒评估：

壁垒类型	等级	数据锚点	预估成本	缓解方案
Review 壁垒	中/高	Top10 均值 XXX 评论	$XXX	Vine + PPC
资金壁垒	中/高	首批备货 + 广告	¥XX	控制首批 MOQ
...	...	...	...	...

选品决策评估（五维评分）：

维度	权重	评分(1-10)	加权分	依据
市场规模	20%	[LLM 评分]	X.X	[数据依据]
竞争格局	25%	[LLM 评分]	X.X	[数据依据]
...	...	...	...	...
总分	100%	-	X.XX	决策结论

决策结论映射：

7.5-10分 → 建议进入 (优先推进)
6.0-7.4分 → 谨慎进入 (需精准定位，明确准入条件)
4.0-5.9分 → 暂缓观望 (需更多数据验证)
0-3.9分 → 不建议进入 (风险大于机会)

产品矩阵（Tier 1 必填具体规格）：

### Tier 1: [产品定位]

**目标市场**：[维度组合空白/机会]
**决策理由**：[数据依据]

| 维度 | 规格 | 决策依据 |
|------|------|----------|
| [维度1] | [具体值] | [为什么] |
| [维度2] | [具体值] | [为什么] |

**目标定价**：$XX.XX
**差异化主张**：[一句话]
**对标竞品**：[ASIN] — [我们的优势]
**预估月销潜力**：XX-XX 件

Step 6: 报告输出

输出文件：

product-research-reports/
└── {category}_{site}_{YYYYMMDD}/
    ├── report.md              # Markdown 完整报告（LLM 直接输出）
    ├── data.json              # 结构化数据（供 Dashboard 使用）
    ├── dashboard.html         # 可视化看板（脚本渲染）
    └── raw/                   # 数据文件
        ├── category_info.json # 类目信息
        ├── top100.json        # Top100 产品数据
        ├── trend.json         # 趋势数据
        └── keywords.json      # 关键词数据

data.json 结构（简化版）：

{
  "metadata": {
    "category": "bluetooth speaker",
    "site": "US",
    "date": "20260319"
  },
  "market_overview": {
    "top100_monthly_sales": 55000,
    "top100_monthly_revenue": 5200000,
    "avg_price": 95,
    "top3_product_concentration": 0.2578,
    "top3_brand_concentration": 0.5058,
    "top10_brand_concentration": 0.8234
  },
  "dimensions": [...],
  "cross_analysis": [...],
  "competitors": [...],
  "voc_analysis": {
    "dimensions": [
      {
        "dimension": "音质/音量",
        "pain_point": "音量太小，户外听不清",
        "frequency": 45,
        "percentage": "32%",
        "affected_brands": ["SHOKZ", "JLab"],
        "brand_opportunity": "采用更大驱动单元",
        "product_solution": "14.2mm动圈+音量增强模式"
      }
    ],
    "summary": "主要痛点集中在音质(32%)、舒适度(28%)、续航(18%)"
  },
  "barriers": [...],
  "go_nogo": {...}
}

⛔ 重要：数据字段命名规范

字段名	说明	示例
`top3_product_concentration`	Top3 产品销量占 Top100 总销量的比例	0.2578 = 25.78%
`top3_brand_concentration`	Top3 品牌销量占 Top100 总销量的比例	0.5058 = 50.58%
`top10_brand_concentration`	Top10 品牌销量占 Top100 总销量的比例	0.8234 = 82.34%
`new_product_share`	新品（上架<6个月）销量占比	0.26 = 26%

禁止模糊命名：

❌ top3_concentration（不明确是产品还是品牌）
✅ top3_product_concentration 或 top3_brand_concentration

⛔ 重要：VOC 分析数据结构

voc_analysis 字段必须包含按维度归类的差评分析，而非按 ASIN 组织：

字段	类型	说明
`dimension`	string	痛点维度（如：音质/音量、舒适度、续航等）
`pain_point`	string	痛点描述
`frequency`	number	提及频次
`percentage`	string	占比（如 "32%"）
`affected_brands`	array	涉及的品牌列表
`brand_opportunity`	string	品牌/供应链能力如何解决
`product_solution`	string	具体产品改进方案

Dashboard 渲染规范

render_dashboard.py 负责将 data.json 渲染为可视化看板。关键渲染规则：

产品维度分布

必须使用表格形式，禁止使用柱状图
双栏布局：左侧价格区间分布，右侧产品形态分布
每行显示：维度值、产品数、占比（带颜色标签）
占比标签颜色规则：≥30%蓝色、≥20%绿色、≥10%黄色、<10%灰色

交叉分析（价格区间 × 产品形态）

必须使用矩阵表格形式，禁止使用图表
行：价格区间（$0-30 到 $200+）
列：产品形态（骨传导、夹耳式、开放式挂耳、入耳式）
单元格：产品数量
特殊标记：
- 竞争激烈（≥15款）：红色"红海"标签
- 市场空白（0款）且为机会点：绿色"机会"标签
底部必须有洞察提示框，说明红海和机会区域

示例输出

<!-- 维度分布：双表格布局 -->
<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 24px;">
  <!-- 价格区间表格 -->
  <!-- 产品形态表格 -->
</div>

<!-- 交叉分析：矩阵表格 -->
<table>
  <thead><!-- 表头：产品形态 --></thead>
  <tbody><!-- 行：价格区间，列：产品数 --></tbody>
</table>
<div class="insight-box">洞察：...</div>

LLM Prompt 模板库

详细 Prompt 模板请参考：references/prompt_templates.md

包含 6 个模板：

属性标注 - 从产品标题提取差异化维度
交叉分析 - 发现供需缺口
竞品选择 - 选择代表性竞品
差评归类 - 按属性维度归类痛点
选品决策评估 - 五维加权决策
产品矩阵规划 - Tier 1/2/3 具体规格

硬性规则（⛔ 不可省略）

⛔ Top100 必须完整 100 条
⛔ 关键词至少 3 个维度对比
⛔ 竞品选择 6-10 个，覆盖量级标杆/功能差异/价格带/痛点
⛔ 差评必须按维度归类（非按 ASIN 归类），输出到 data.json 的 voc_analysis 字段
⛔ VOC 分析必须包含：频次、占比、涉及品牌、品牌机会、产品方案
⛔ 选品决策评估必须量化评分
⛔ Tier 1 产品必须具体到规格（禁止"待确认"占位）
⛔ 每个数据表后有"关键洞察"段落
⛔ 空白/薄供给必须附带原因分析
⛔ 数据字段命名必须清晰：使用 top3_product_concentration / top3_brand_concentration，禁止模糊的 top3_concentration
⛔ 数据一致性校验：报告生成前必须校验 data.json 中的数值与报告文本一致

常见场景策略

场景1：新手入门（预算<15万）

价格 $10-20
轻小件
无售后风险
中国卖家占比 > 70%

场景2：蓝海发现

Top3 集中度 < 30%
新品占比 > 15%
关键词首页评论 < 500

场景3：定向品类分析（用户已指定）

跳过类目扫描，直接进入数据采集
⛔ 必须执行属性标注
⛔ 必须执行交叉分析
⛔ 必须执行选品决策评估（五维评分）

与其他 Skills 的关系

category-selection (品类筛选五维评分)
        ↓
product-research (深度选品调研) ← 本 Skill
        ↓
amazon-analyse (竞品 Listing 深挖)
        ↓
review-analysis (评论深度分析)

区别：

category-selection：品类级别的快速筛选，五维评分
product-research：指定品类的深度调研，多维度分析 + 选品决策评估
amazon-analyse：单个竞品 Listing 的详细分析
review-analysis：评论的深度痛点分析

支持的站点

US, GB, DE, FR, IT, ES, CA, JP, MX, AE, AU, BR, SA

注意事项

API Key：自动从 .mcp.json 读取
数据时效：Sorftime 数据可能有 1-7 天延迟
API 限流：每批最多 8 个并发请求
编码问题：脚本自动处理 Unicode-escape 和 Mojibake
原始数据：所有 API 响应保存在 raw/ 目录供验证

故障排查

常见错误及解决方案

错误信息	原因	解决方案
`HTTP Error 406: Not Acceptable`	API参数错误	检查参数名是否为 `searchName` 而非 `productName`
`An error occurred invoking 'xxx'`	API工具不存在	检查 TOOLS 映射表中的工具名称
`未查询到对应产品`	ASIN无效或站点错误	验证ASIN格式, 确认产品在该站点销售
`Authentication required`	API Key错误	检查 `.mcp.json` 中的 key 参数
中文乱码	Mojibake编码	脚本自动修复, 或运行 `fix_encoding.py`
`IndentationError: unexpected indent`	Windows 命令行问题	使用脚本文件而非 `python -c`
`输出目录路径错误`	相对路径问题	使用 `run_analysis.py`，自动处理路径
`NameError: name 'xxx' is not defined`	缺少 datetime 导入	检查脚本 import 语句
Dashboard 渲染问题
Dashboard 显示空白	data.json 结构不匹配	v3.5 已修复：`run_analysis.py` 自动渲染 Dashboard
Dashboard 未自动生成	旧版本未集成渲染	v3.5 已修复：数据采集完成后自动渲染
`PermissionError: [Errno 13]`	传递目录路径而非文件路径	使用绝对路径调用：`python render_dashboard.py -o output.html data.json`
`unrecognized arguments`	参数顺序错误	正确格式：`python render_dashboard.py -o dashboard.html data.json`
Dashboard 缺少 VOC 数据	LLM 未生成完整 voc_analysis	确保 LLM 生成包含 voc_analysis.dimensions 的完整 data.json
Dashboard 交叉分析为空	price_type_matrix 数据缺失	确保数据采集包含价格区间分析
`KeyError: 'xxx'`	字段名不一致	v3.4 已修复：支持新旧字段名兼容
`AttributeError: 'str' object has no attribute 'get'`	data.json 格式问题	v3.4 已修复：自动转换为列表格式

Dashboard 手动渲染方法

如果自动渲染失败，可以手动调用：

# 从输出目录调用
python .claude/skills/product-research/scripts/render_dashboard.py \
    -o product-research-reports/{keyword}_{site}_{date}/dashboard.html \
    product-research-reports/{keyword}_{site}_{date}/data.json

# 或者使用绝对路径
python "D:\amazon-mcp\.claude\skills\product-research\scripts\render_dashboard.py" \
    -o "D:\amazon-mcp\product-research-reports\{keyword}_{site}_{date}\dashboard.html" \
    "D:\amazon-mcp\product-research-reports\{keyword}_{site}_{date}\data.json"

API 工具名称对照表

功能	工具名称	参数
类目搜索	`category_name_search`	`amzSite`, `searchName`
类目报告	`category_report`	`amzSite`, `nodeId`
类目趋势	`category_trend`	`amzSite`, `nodeId`, `trendIndex`
关键词详情	`keyword_detail`	`amzSite`, `keyword`
产品详情	`product_detail`	`amzSite`, `asin`
产品评论	`product_reviews`	`amzSite`, `asin`, `reviewType`

调试技巧

启用详细输出: 在脚本中添加 print() 调试信息
检查原始响应: 查看 SSE 响应的实际内容
分步执行: 使用 Python 交互式环境逐行调试
验证API Key: curl "https://mcp.sorftime.com?key=YOUR_KEY" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

版本: v3.6 (两阶段工作流 + 数据验证) | 最后更新: 2026-03-19

About this skill

Automatic

Product Management pack

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/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

LeoYeAI / openclaw-master-skills

skills/amazon-sorftime-research-market-skill/SKILL.md

View on GitHub ↗

License MITImported 8/2/2026Version v2Bundled 13 files · scripts

Illustrative Want to see what product-research 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

选品分析器 (Product Research - LLM Agent 驱动版)

定位

Script Directory

执行流程（两阶段）

阶段1：数据采集（脚本自动）

阶段2：LLM 分析（交互式）

数据完整性检查

执行流程（交互式）

Step 0: 信息收集

Step 1: 数据采集（增强版 v3.0）

Step 2: 属性标注（LLM 驱动）

Step 3: 交叉分析（LLM 直接发现）

Step 4: 竞品与 VOC 分析

Step 5: 评估与决策

Step 6: 报告输出

Dashboard 渲染规范

产品维度分布

交叉分析（价格区间 × 产品形态）

示例输出

LLM Prompt 模板库

硬性规则（⛔ 不可省略）

常见场景策略

场景1：新手入门（预算<15万）

场景2：蓝海发现

场景3：定向品类分析（用户已指定）

与其他 Skills 的关系

支持的站点

注意事项

故障排查

常见错误及解决方案

Dashboard 手动渲染方法

API 工具名称对照表

调试技巧

SkillSafety

Source

Related skills

More in the registry