Expertise Best Practices

When adding content to InSkill you have two options, depending on how you want that content used.

Resources or Agents

Resources are static content: documents, links, videos, and other reference material. Use a resource when you want to provide readable, contextual information that Technicians can browse and InSkill can reference directly.

Agents handle interactive or dynamic cases, where the system needs to process, query, or act on data.

• Data Query agents work with structured data in CSV or Excel that needs to be searched, filtered, or analyzed — lookups, tables, large datasets.
• Script agents run custom logic or workflows, enabling behavior beyond static content.

📘

Note

Use resources for content you want presented or referenced as-is. Use agents when you need the system to interact with or compute on the data.

Choosing a Format

If your content already exists in a specific format, keep it as-is. The guidance below is for new content.

Tabular data

Choose a standalone CSV or Excel resource when the tabular data is the primary content, the table is small to medium sized, and Technicians will ask questions about the data rather than query it directly.

🚧

Caution

In a standalone spreadsheet resource, only tables are extracted. Surrounding text is ignored.

Keep tables inside a document when the table is part of a larger narrative, the surrounding explanation matters, and the table is small to medium sized.

Choose a Data Query agent when the data is large or frequently queried, and Technicians need to filter, look up values, or aggregate — questions like finding the value in one column where another column matches, or the average pressure for pumps in a given region.

If your data lives in a database or another structured system, contact [email protected] to discuss integration options.

Frequently changing content

Dynamic resources, written in HTML or Markdown, are best for content that changes often and for unstructured or miscellaneous material such as FAQs or phone extensions. They render cleanly in the browser and are straightforward to edit and maintain. See Adding Dynamic Resources.

Everything else

PDF, Word, plain text, and Markdown files all work.

📘

Note

PDF files open in the browser. Other file types download when opened.

Document Best Practices

These practices help ensure InSkill can parse, understand, and use your content.

Word

• Use the predefined heading styles rather than manually formatted text.

HTML

• Use semantic HTML: real heading elements, and navigation elements so menus can be excluded from parsing.
• Add title attributes to images and links.
• Give every table a header row.
• Do not use tables for layout.
• Use inskill-skip, as either an attribute or a class, to exclude irrelevant content such as cookie banners, shopping carts, and language selectors.

PDF

• Prefer tables with visible borders, which improves table detection.

Excel

• Named tables or filtered ranges improve table detection.
• Put headers in the top row where possible.
• Avoid vertical headers.