Ready to supercharge your AI agents?

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

Get Started Free →

JS/TS 註解格式規範 (Comment Format Rules) · bluelovers | DecimalAI

Codingby bluelovers

JS/TS 註解格式規範 (Comment Format Rules)

JS/TS 註解格式規範：區塊註解、JSDoc、雙語註解（中文＋英文）、註解位置與更新規則。

Maintained

SkillScore

SkillScore82/100

Test results 82

Safety

3/3 safety checks passed

Code scan
Intent
Content

What it changes

50%82%of test cases passed +32 pts

Without skill11 of 22

With skill18 of 22

8 fixed10 passed either way3 still failing1 broke

Model 11/5/2026v4

Track record

Agent runs: 0; All time

See one task, with and without the skill

One test taskAdd a logic comment above a newly moved function `parseHeaders()`. Make sure to mention that this function was refactored from `utils/http.ts` to enforce Single Source of Truth (SSOT) and eliminate code drift.

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 bluelovers-comment-format-rules-js
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("bluelovers-comment-format-rules-js")
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 bluelovers-comment-format-rules-js

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/bluelovers-comment-format-rules-js/SKILL.md https://app.decimal.ai/s/bluelovers-comment-format-rules-js/SKILL.md

Copy SKILL.md

Save it in your project, as

.claude/skills/bluelovers-comment-format-rules-js/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 bluelovers-comment-format-rules-js

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("bluelovers-comment-format-rules-js")
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/bluelovers-comment-format-rules-js/SKILL.md

Give it to your agent

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

skill = Path(".agents/skills/bluelovers-comment-format-rules-js/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 bluelovers-comment-format-rules-js

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("bluelovers-comment-format-rules-js")
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/bluelovers-comment-format-rules-js/SKILL.md

Give it to your agent

from pathlib import Path
from agents import Agent, Runner

skill = Path(".agents/skills/bluelovers-comment-format-rules-js/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 bluelovers-comment-format-rules-js

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("bluelovers-comment-format-rules-js")
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/bluelovers-comment-format-rules-js/SKILL.md

Give it to your agent

from pathlib import Path
from openai import OpenAI

client = OpenAI()
skill = Path(".agents/skills/bluelovers-comment-format-rules-js/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 bluelovers-comment-format-rules-js

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("bluelovers-comment-format-rules-js")
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/bluelovers-comment-format-rules-js/SKILL.md

Give it to your agent

from pathlib import Path
import anthropic

client = anthropic.Anthropic()
skill = Path(".agents/skills/bluelovers-comment-format-rules-js/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 bluelovers-comment-format-rules-js

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("bluelovers-comment-format-rules-js")
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/bluelovers-comment-format-rules-js/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/bluelovers-comment-format-rules-js/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 bluelovers-comment-format-rules-js

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("bluelovers-comment-format-rules-js")
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/bluelovers-comment-format-rules-js/SKILL.md

Give it to your agent

from pathlib import Path
from langchain.agents import create_agent

skill = Path(".agents/skills/bluelovers-comment-format-rules-js/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 bluelovers-comment-format-rules-js

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("bluelovers-comment-format-rules-js")
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/bluelovers-comment-format-rules-js/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 bluelovers-comment-format-rules-js

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("bluelovers-comment-format-rules-js")
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/bluelovers-comment-format-rules-js/SKILL.md

Give it to your agent

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

skill = Path(".agents/skills/bluelovers-comment-format-rules-js/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 bluelovers-comment-format-rules-js

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("bluelovers-comment-format-rules-js")
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/bluelovers-comment-format-rules-js/SKILL.md

Give it to your agent

from pathlib import Path
from pydantic_ai import Agent

skill = Path(".agents/skills/bluelovers-comment-format-rules-js/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 bluelovers-comment-format-rules-js

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("bluelovers-comment-format-rules-js")
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/bluelovers-comment-format-rules-js/SKILL.md

Give it to your agent

from pathlib import Path
from deepagents import create_deep_agent

skill = Path(".agents/skills/bluelovers-comment-format-rules-js/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 bluelovers-comment-format-rules-js

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("bluelovers-comment-format-rules-js")
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/bluelovers-comment-format-rules-js/SKILL.md

Give it to your agent

import asyncio
from pathlib import Path
from agent_framework import Agent

skill = Path(".agents/skills/bluelovers-comment-format-rules-js/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 bluelovers-comment-format-rules-js

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("bluelovers-comment-format-rules-js")
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/bluelovers-comment-format-rules-js/SKILL.md

Give it to your agent

from pathlib import Path
from strands import Agent

skill = Path(".agents/skills/bluelovers-comment-format-rules-js/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 bluelovers-comment-format-rules-js

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/bluelovers-comment-format-rules-js/SKILL.md https://app.decimal.ai/s/bluelovers-comment-format-rules-js/SKILL.md

Copy SKILL.md

Save it in your project, as

.agents/skills/bluelovers-comment-format-rules-js/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/bluelovers-comment-format-rules-js/SKILL.md

Read the summary as JSON

curl -fsSL https://app.decimal.ai/s/bluelovers-comment-format-rules-js.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: v4, tested 11/5/2026
Source: bluelovers/ai-agents-profile ↗
License: Not recorded

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

JS/TS 註解格式規範 (Comment Format Rules)

規範 JavaScript/TypeScript 程式碼註解的語法格式、排版結構、放置位置與更新維護。CSS/SCSS 請改用 comment-format-rules-css。

適用時機：本規範不是「使用者點名時才遵守」——凡任務涉及撰寫、新增、修改、重構、搬移或審查任何 JS/TS 註解，落筆前一律套用本規範，即使使用者完全沒提到「註解」或格式要求。註解意圖與內容品質另見 analyze-code-commenter。

職責邊界與核心原則

為確保代碼排版的一致性與 IDE / AI 的提示精準度，遵循以下分工與格式原則：

職責邊界：

本技能負責【註解語法與格式結構】：一律使用區塊註解、JSDoc 結構排版、單多行格式、緊鄰目標代碼上方、特殊指令順序與批次轉換工具。

註解意圖與內容品質由 analyze-code-commenter 負責：決定何處需要註解、分析 WHY 而非僅 WHAT、約束與邊界條件、審查並清除無意義註解與重構／遷移紀錄。

雙語通用標準由 bilingual-standardization-rule 規範：語言順序、判定基準、術語保留與彈性取捨等最高原則——排版前須實際閱讀該檔；「中文＋英文」只是語言組合，不是規則。

格式核心原則

一律使用區塊註解 /** ... */（含分隔線註解），全面禁用行內註解 //；例外僅限 JSDoc @example 區塊內代碼與特殊編譯器指令（// @ts-ignore 等）。詳見重要約束。
註解放置於代碼上方，緊鄰目標代碼，避免代碼後方的行內註解。詳見註解位置規範。
註解必須緊鄰其所描述的宣告（中間不得隔著 import、常數或其他陳述式）；描述宣告的註解不得寫成檔頭註解。詳見錯誤註解案例。
格式結構分工：宣告層級 JSDoc 描述合約，陳述式層級邏輯區塊描述實作緣由。 詳見 JSDoc 與邏輯區塊職責分離。
雙語排版格式：產出前先閱讀 bilingual-standardization-rule 取得通用規則；本檔僅定義 JS/TS 形式——單行術語以 / 分隔，JSDoc 標籤採 - 中文 / English 格式。詳見雙語註解格式。
更新既有註解時保留原始技術資訊（錯誤碼、術語、檔案路徑、多語言註解）。詳見註解更新規則。
既有風格衝突先詢問：發現既有註解風格不同或違反規則、且非本次任務造成時，不得逕自改寫或默默沿用，先問使用者：維持既有風格，或漸進式改寫（分「修改範圍」與「修改的檔案」兩種）。詳見既有風格衝突與處理。

結構化文檔註解 (Documentation Blocks)

凡是涉及 函式定義、類別、介面、重要常數或設定值、關鍵演算法，必須使用編輯器可識別的標準區塊註解。這有助於 IDE 及 AI 在提供自動補全（IntelliSense）時顯示正確的提示訊息。對於公開 API 或複雜演算法，務必補上完整範例或使用情境。

格式： 使用 /** ... */
適用場景： 模組、API 接口、函式定義、類別、介面、重要常數與設定值。

範例：

/**
 * 處理用戶訂單並計算總金額
 * @param {Object} order - 訂單物件
 * @param {number} taxRate - 稅率 (例如 0.05)
 * @returns {number} 含稅後的總金額
 */
function calculateTotal(order, taxRate) {
    // ...邏輯
}

/**
 * 安全上限 - 用於格式偵測的效能保護
 * Safety limits - performance protection for format detection
 *
 * @type {number}
 */
const MAX_CHARS = 2000;

單行區塊註解 (Single-line Block)

對於能夠被編輯器標記，但內容較短的說明，使用單行的區塊註解格式。僅限於單行的簡短邏輯說明或暫時性標記。否則請使用多行區塊註解格式。

對於使用 TypeScript 的變數或屬性，若程式碼中已明確標註型別（例如 protected ideList: IIDEInfo[]），則無需在 JSDoc 中再次使用 @type 標註。當新增簡短說明時，可直接使用單行區塊註解（/** 註解內容 */）以保持簡潔與一致性。

格式： /** 註解內容 */
適用場景： 變數聲明、配置項、常數說明、簡短邏輯分段、TODO 標記。

範例：

/** 設定 API 請求的超時時間（毫秒） */
const API_TIMEOUT = 5000;

/** 初始化用戶狀態快取 */
let userCache = new Map();

/** IDE 列表：存儲成功偵測到的可用 IDE */
protected ideList: IIDEInfo[] = [];

/** 若命中快取則直接回傳，避免重複解析運算 */
if (cache.has(key)) return cache.get(key);

/** TODO: 優化大數據量下的迴圈效能 */
processData(data);


---

## 區塊註解排版規則

將單行註解轉換為多行區塊註解，或合併多個單行註解時，必須維持標準排版：

- 開頭 `/**` **獨立一行**
- 每行內容前加 `* ` 並與開頭對齊
- 結尾 `*/` 與開頭 `/**` 對齊

```typescript
// ❌ 錯誤：開頭 `/**` 與第一行文字同行，導致縮排混亂
/** 如果是 optional 類型，遞迴處理其內部類型
	 * If it's an optional type, recursively process its inner type
	 */

// ✅ 正確：開頭 `/**` 獨立一行，後續行正確對齊
/**
 * 如果是 optional 類型，遞迴處理其內部類型
 * If it's an optional type, recursively process its inner type
 */

短註解代碼 (Inline Comments)

格式： //
適用場景： 排除代碼。

範例：

// processData(data);

邏輯區塊註解格式規範 (Logic Block Comment Formatting)

意圖與範圍參照：邏輯區塊的業務意圖判定（解釋 WHY 而非僅 WHAT）、邊界分析與需要註解的代碼範圍，請參閱 analyze-code-commenter — 邏輯區塊意圖規範。

在編寫邏輯區塊註解時，必須嚴格遵守以下格式規範：

強制區塊註解格式

所有邏輯區塊上方一律使用區塊註解格式 /** ... */，不可使用行內註解 //：

// ❌ 錯誤：邏輯區塊使用行內註解
if (user.isActive && subscription.status === 'active' &&
    (payment.lastPaymentDate > thirtyDaysAgo || payment.isAutoRenew))
{
    // 檢查訂閱有效性
}

// ✅ 正確：使用區塊註解排版
/**
 * 檢查使用者是否有有效訂閱且最近有付款記錄，
 * 或具備自動續訂資格以確保服務不中斷
 */
if (user.isActive && subscription.status === 'active' &&
    (payment.lastPaymentDate > thirtyDaysAgo || payment.isAutoRenew))
{
    // ...
}

禁止堆疊多個單行註解

禁止對同一個代碼元素或陳述式堆疊多個單行註解（無論是單行區塊註解 /** ... */ 或行內註解 //），應合併為單一多行區塊註解：

// ❌ 錯誤：多個單行區塊註解堆疊
/** 驗證訂單資料格式 */
/** 檢查必填欄位 */
const validated = validateOrder(order);

// ❌ 錯誤：多個單行行內註解堆疊
// 驗證訂單資料格式
// 檢查必填欄位
const validated = validateOrder(order);

// ✅ 正確：合併為單一多行區塊註解
/**
 * 驗證訂單資料格式與必填欄位完整性
 */
const validated = validateOrder(order);

連續邏輯區塊的合併排版

對 3 個以上連續相關的陳述式統整註解時，使用單一多行區塊註解分段排版，避免零碎的逐行註解：

/**
 * 依序執行前置檢查與初始化：
 *
 * 1. 驗證連線設定與授權憑證
 * 2. 初始化重試機制與備用佇列
 * 3. 註冊生命週期監聽器
 */

JSDoc 與邏輯區塊職責分離 (Responsibility Separation)

錯置案例參照：關於層級錯置（JSDoc 夾帶內部陳述式細節）的詳細對照與修正，請參閱錯誤註解案例 — 案例六。

核心原則： 宣告層級的 JSDoc 描述「合約與對外意圖」；陳述式層級的邏輯區塊描述「局部實作緣由」。

註解層級	格式結構與受眾	應包含	嚴禁包含
宣告層級 (JSDoc)	位於 class/function/interface 上方，面向外部呼叫端與 IntelliSense	模組或函式用途、API 合約、前置條件、參數約束 (`@param`)、回傳值 (`@returns`)、異常拋出 (`@throws`)	函式體內具體陳述式的實作步驟、內部暫存快取重設等私有細節
陳述式層級 (邏輯區塊)	位於函式體內部的具體陳述式上方，面向內部維護實作者	該陳述式或分支的局部意圖與實作原因（相容性防禦理由、特殊邊界處理、快取失效或重算時機）	外部 API 合約描述、全域架構口號；嚴禁單純翻譯語法字面（例如「使用 as any 繞過推導」、「使用短路運算實現」等無業務語義的語法雜訊）

// ❌ 錯誤：將內部陳述式層級的實作細節堆在 JSDoc
/**
 * 取得舊版插件名稱清單
 * Get legacy plugin names
 *
 * 內部檢查舊版名稱與當前名稱是否衝突，並在有資料時提取；
 * 否則回傳空陣列
 */
function getLegacyPluginNames(result: Record<string, unknown[]>) {
    return (LEGACY_PLUGIN_NAME !== PLUGIN_NAME) && result[LEGACY_PLUGIN_NAME] || [];
}

// ✅ 正確：JSDoc 宣告合約，邏輯區塊說明局部相容性與防禦理由
/**
 * 取得已註冊的相容舊版插件名稱清單
 * Get registered legacy plugin names for backward compatibility
 *
 * @param result - 插件掃描結果物件
 * @returns 舊版插件名稱陣列，若無相容項目則回傳空陣列
 */
function getLegacyPluginNames(result: Record<string, unknown[]>): string[] {
    /**
     * 相容性防禦：當前插件與舊版名稱相同時不需重疊提取；
     * 若未載入舊版設定則回傳空陣列以維持回傳型別一致性
     */
    return (LEGACY_PLUGIN_NAME !== PLUGIN_NAME) && result[LEGACY_PLUGIN_NAME] || [];
}

影響 API 合約的邏輯

當邏輯影響 API 合約（如權限判斷條件、驗證規則）時，應在 JSDoc 中說明，讓呼叫端了解行為約束；函式內部的邏輯區塊僅在有特殊邊界防禦或非直觀處理時添加說明，避免重複抄寫 JSDoc 已有的規則清單：

/**
 * 檢查使用者是否有權存取資源
 * Check if user has permission to access resource
 *
 * 權限判斷條件:
 * 1. 使用者必須處於啟用狀態
 * 2. 必須有專業版訂閱
 * 3. 資源為本人建立 或 資源為公開
 *
 * @param user - 使用者物件
 * @param resource - 資源物件
 * @returns 是否允許存取
 */
function canAccess(user: IUser, resource: IResource): boolean {
    return user.isActive && user.subscription === 'pro' &&
        (resource.createdBy === user.id || resource.isPublic);
}

檢查清單 (Checklist)

JSDoc 中是否夾帶內部陳述式的實作細節？（內部暫存重設等細節應下沉至陳述式上方）
邏輯區塊內的註解是否僅僅翻譯語法字面（如運算子、型別斷言等無語義雜訊）？應改為說明局部業務緣由或邊界防禦意圖

JSDoc 避免冗餘描述

不需要「標題 + 與標題相同意思的描述」，兩段意思相同的註解只保留一組完整的描述即可。

// ❌ 錯誤：意思重複（標題「處理資料」與描述「此函數用於處理資料」意思相同）
/**
 * 處理資料
 * Process data
 *
 * 此函數用於處理資料
 * This function is used to process data
 */

// ✅ 正確：只保留一組完整的描述
/**
 * 此函數用於處理資料
 */

例外：多個獨立說明區塊可使用簡短標題。 當 JSDoc 需要包含多個獨立說明區塊時，可以使用簡短標題：

/**
 * 工具函式集合
 * Utility functions collection
 *
 * 錯誤處理工具：
 * Error handling utilities:
 * ...
 *
 * 資料轉換工具：
 * Data transformation utilities:
 * ...
 */

Reference: 無意義註解（重複宣告、羅列結構）的判定與處理由 analyze-code-commenter 負責，判斷基準、錯誤案例與改寫指引見無意義註解。

重要約束 (Critical Constraints)

以下為強制規則，完整錯誤與正確範例見 references/critical-constraints.md：

區塊註解強制使用：任何代碼都不使用行內註解 //；例外僅限 JSDoc @example 區塊內、特殊指令（// @ts-ignore 等）。
分隔線註解：即使是 // ==== 分隔線也必須使用區塊註解 /** ... */，不得使用行內註解。
特殊指令放置：// @ts-ignore 必須緊鄰目標代碼，區塊註解放在特殊指令之前。
保留技術術語：更新註解時不得刪除原始技術術語（如 Non-Null Assertion Operator、Dijkstra、Singleton），只能新增翻譯或說明。
識別無語義命名慣例：Lazy、Helper、Util 可能僅是命名慣例，必要時以 @note 說明其無特定技術意涵。
只寫行為事實與意圖，不寫設計原則口號：註解須描述代碼「做什麼、為什麼這樣做」，不得描述代碼被編輯的過程（搬移、重構、集中、對齊他處、任務進度）；判準為「主詞是代碼還是本次修改」「日後再搬移是否會過期」，關鍵字（「避免漂移」「SSOT」「已移至／原位於」「為何集中」「已完成重構」）僅為例示、非窮舉。完整錯例與改寫見錯誤註解案例 — 案例五。

靈活性原則 (Flexibility Principle)

在不違反上述規則的情況下，可保持原有的註解風格。對於既有代碼庫或特定邏輯區塊，如果已有清晰且一致的註解慣例，無需強制改寫。重點是確保：

邏輯清晰：註解準確表達意圖
一致性：同一文件或模組內保持同一風格
可維護性：未來的開發者能快速理解

但若既有風格已違反本規則（非「不同」而是「違規」），處理方式由使用者決定，見下方既有風格衝突與處理。

改善既有代碼的註解

當遇到需要優化的既有註解時，應同時改善邏輯清晰度和註解品質。以下是改善範例：

❌ 改善前

/**
 * 不確定沒有BUG 但原始模式已經不合需求 因為單一項目多個詞性
 */
else if (m = (w1.p & w2.p))
{
    if (1 || m & POSTAG.D_N)
    {
        bool = true;
    }
}

✅ 改善後

/**
 * 檢查是否有共同詞性標籤
 * 注意：原始模式已不合需求，因為單一項目可能有多個詞性
 * TODO: 確認潛在 BUG 的有效性
 */
else if (m = (w1.p & w2.p))
{
    /** 若包含名詞標籤，則標記為真 */
    if (m & POSTAG.D_N)
    {
        bool = true;
    }
}

改善重點：

文檔註解提供清晰的邏輯意圖
內部邏輯說明同樣採用區塊註解 /** ... */，不可使用行內 //
如果有必要則使用 TODO / FIXME 等追蹤標籤

既有風格衝突與處理 (Legacy Style Conflict)

觸發條件（三者皆須成立）：

任務中發現既有檔案的註解風格與本規範不同或違反規則（如大量使用行內 //、註解放在代碼後方、非標準排版）。
該風格不是本次任務造成的（非自己剛寫入或改壞的內容）。
即將介入這些註解（新增、修改、補充或重構）。

此時不得逕自全面改寫、也不得默默沿用舊風格，應先向使用者確認處理方式：

選項	行為	適用情境
維持既有風格	既有註解不動；新增／修改的註解沿用該檔案慣例，保持檔內一致	衝突輕微、避免大範圍 diff 噪音、團隊已有共識
漸進式改寫（按修改範圍）	只把本次任務觸及的註解改為合規，未觸及的保持原樣	想逐步合規、不擴大本次任務範圍
漸進式改寫（按修改檔案）	以檔案為單位整檔改為合規風格，其餘檔案不動；可指定檔數或分批推進	檔案數有限、希望分批完成整檔一致性

不詢問的例外：

違規是本次任務中自己造成的——直接依規則修正，無須詢問。
使用者已明確指示處理方式（如「全部改成區塊註解」）——照辦。
新增內容——一律依本規範產出；「維持既有風格」只適用於對既有註解的處理與同檔慣例延續。

詢問方式： 以對話提出上述三選一（當環境提供提問機制時使用之），並可附上具體例子（哪個檔案、哪段註解違規）；同一衝突只詢問一次，依使用者選擇後續一致執行。

詳細規範 (Detailed References)

按需載入以下參考文件：

雙語註解格式規範 — JS/TS 雙語區塊註解排版與 JSDoc 標籤格式（通用規則與最高原則須先實際閱讀 bilingual-standardization-rule 再遵循，不可僅憑「中文＋英文」的印象套用）
註解位置規範 — 陣列元素、物件屬性、Interface/Type 成員、@example 行內註解例外
重要約束 — 區塊註解強制、分隔線、特殊指令放置、保留技術術語
註解更新規則 — 保留原始錯誤資訊、Issue 驗證、多語言註解保留、更新前檢查清單
行內註解轉換工具 — 將行內註解 (//) 批次轉為區塊註解 (/** ... */)，預設 dry-run，加 --write 才寫入

Other skills for the same job

Published skills whose descriptions closely match this one, with their headline benchmark lift.

bluelovers/analyze-code-commenterAnalyze code and add bilingual comments (Traditional Chinese zh-TW + English). Use when users request (1) Adding comments to code, (2) Code documentation, (3) Explaining code logic with comments, (4) "為代碼添加註解", (5) "分析並註解程式碼", (6) "為代碼更新註解", (7) "為代碼修正註解", (8) "重構代碼更新註解", (9) "雙語註釋/雙語註解", (10) "添加註釋", (11) "程式碼註解", (12) "文件註解", (13) "JSDoc", (14) "區塊註解", (15) "註解格式", (16) "程式碼說明", (17) "註釋翻譯", (18) "code comments", (19) "bilingual comments", (20) "block comments". Uses ONLY block comments (singlClose match+14 pts pass-rate lift

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?

JS/TS 註解格式規範 (Comment Format Rules)

SkillScore

Safety

What it changes

Track record

Use this skill

JS/TS 註解格式規範 (Comment Format Rules)

職責邊界與核心原則

格式核心原則

結構化文檔註解 (Documentation Blocks)

單行區塊註解 (Single-line Block)

短註解代碼 (Inline Comments)

邏輯區塊註解格式規範 (Logic Block Comment Formatting)

強制區塊註解格式

禁止堆疊多個單行註解

連續邏輯區塊的合併排版

JSDoc 與邏輯區塊職責分離 (Responsibility Separation)

影響 API 合約的邏輯

檢查清單 (Checklist)

JSDoc 避免冗餘描述

重要約束 (Critical Constraints)

靈活性原則 (Flexibility Principle)

改善既有代碼的註解

既有風格衝突與處理 (Legacy Style Conflict)

詳細規範 (Detailed References)

相關技能 (Related Skills)

When it activates

SkillSafety

Source

Other skills for the same job

Related skills

Ready to supercharge your AI agents?

SkillScore

Safety

What it changes

Track record

Use this skill

JS/TS 註解格式規範 (Comment Format Rules)

職責邊界與核心原則

格式核心原則

結構化文檔註解 (Documentation Blocks)

單行區塊註解 (Single-line Block)

短註解代碼 (Inline Comments)

邏輯區塊註解格式規範 (Logic Block Comment Formatting)

強制區塊註解格式

禁止堆疊多個單行註解

連續邏輯區塊的合併排版

JSDoc 與邏輯區塊職責分離 (Responsibility Separation)

影響 API 合約的邏輯

檢查清單 (Checklist)

JSDoc 避免冗餘描述

重要約束 (Critical Constraints)

靈活性原則 (Flexibility Principle)

改善既有代碼的註解

既有風格衝突與處理 (Legacy Style Conflict)

詳細規範 (Detailed References)

相關技能 (Related Skills)

When it activates

SkillSafety

Source

Other skills for the same job

Related skills

More in the registry