insights/.agents/skills/writing-skills/SKILL.md

name, description

name	description
writing-skills	Guide for writing Insights agent skills — job-to-be-done templates that teach agents how to use MCP tools to achieve a goal. Use when adding new product functionality that agents should know how to work with, creating a new skill, or updating existing skills in products/*/skills/.

Writing skills for Insights agents

Read the full guide at docs/published/handbook/engineering/ai/writing-skills.md.

Quick workflow

# 1. Scaffold
insightscli init:skill

# 2. Write your skill in products/{product}/skills/{skill-name}/SKILL.md

# 3. Lint
insightscli lint:skills

# 4. Build to verify
insightscli build:skills

# 5. Test locally with Insights Desktop or a coding agent
insightscli sync:skill -- --name <skill-name>

# 6. Delete the test skill (optional)
insightscli unsync:skill -- --name <skill-name>

Distribution is automatic after merge — CI publishes to Insights/skills.

When to write a skill

When new functionality is added to a product and agents need to know how to work with it. A skill is not about what tools exist (that's the MCP server) — it's about how an experienced person would approach a job using those tools.

Ask: "If a customer asked an agent to do X with my feature, would the agent know the right approach?" If not, write a skill.

How many is too many?

Skill count is a budgeted, shared resource — agents pick from a list of all skill descriptions, and many harnesses truncate that list once it grows long, so every extra skill makes the others less likely to fire. Prefer a small set of focused skills, each with rich references/, over many thin ones:

• New trigger → new skill. A skill earns its own entry point only when its "when to use it" is clearly distinct from every existing skill.
• More detail → references/, not a new skill. Another failure mode, SDK variant, or query catalog is depth on an existing job — add it to that skill's references/ instead of spending a new slot.
• Consolidate near-duplicate siblings. Skills sharing a diagnosis, bug class, or trigger should be one skill with references, not two.

Key rules

• Name: lowercase kebab-case, prefer gerund form (analyzing-llm-traces, not llm-analytics). Never prefix with insights-*.
• Description: third person, specific, include trigger terms and when to use it. Max 1024 chars.
• Structure: SKILL.md entry point + references/ for detailed content. Keep SKILL.md under 500 lines.
• Frontmatter: name and description are required.
• Tone: describe the workflow and reasoning, not a rigid script. Trust the agent to adapt.
• Conciseness: the agent is smart — only include context it doesn't already have.

Skill structure

products/{product}/skills/{skill-name}/
    SKILL.md                         # entry point (required)
    references/                      # optional
        guidelines.md
        models-foo.md
        example-bar.md.j2            # Jinja2 template, rendered at build time
    scripts/                         # optional
        setup.sh

Only references/ and scripts/ subdirectories are collected. Others are ignored.

Template functions

Files ending in .j2 are rendered with Jinja2 at build time by products/insights_ai/scripts/build_skills.py. Extend the build pipeline so the monorepo stays the source of truth — when domain knowledge lives in code (Pydantic models, query runners, function registries), add a template function rather than duplicating it as static markdown that drifts.

Available functions:

• pydantic_schema("dotted.path.to.Model") — renders a Pydantic model's JSON Schema
• render_insightsql_example({"kind": "TrendsQuery", ...}) — renders a query spec to InsightsQL SQL
• insightsql_functions() — returns all available InsightsQL function names

Good example: querying-insights-data

• Clear entry point linking to 30+ reference files
• Progressive disclosure — agents load only what they need
• Mix of static .md and generated .md.j2 content
• See products/insights_ai/skills/querying-insights-data/SKILL.md

Bad example: llm-analytics

An umbrella skill covering traces, experiments, evaluations, cost tracking, prompt management. Too broad — agents can't determine when to activate it. Break into focused skills instead.