Knowledge entries

Knowledge entries are durable reference materials that AI agents can search while answering questions or running tasks. Use them for context that should be remembered exactly, such as metric definitions, operating procedures, product terminology, customer notes, or repository documentation.

Knowledge entries complement memories. Entries are written or connected by your team; memories are learned from agent runs and feedback.

Entry types

You can add knowledge in two common ways:

• Direct entries: notes, explanations, and small documents created inside Altertable.
• Repository syncs: connected GitHub or GitLab repositories that make Markdown, text files, and dbt metadata available as searchable context.

Use direct entries for business rules and lightweight guidance. Use repository syncs when the source of truth already lives in code, analytics projects, or operational documentation.

Import skills as knowledge

You can upload a Markdown skill file or sync a repository of skills to make its guidance available to Altertable agents.

Upload a Markdown skill

1. Open Knowledge and choose Add knowledge.
2. Select File, then Choose file to upload the skill's .md file. For a standalone upload, use a descriptive filename such as monthly-revenue-analysis.md.
3. Set Title to a specific name such as "Monthly revenue analysis". Include the task and topic you would search for to make the entry easier to find.
4. Choose whether the entry is available in the current environment or in all environments.
5. Review Automatically include in AI sessions, then select Add knowledge.

Keep the original SKILL.md filename in its skill directory, as required by the Agent Skills format. Rename only the copy you upload as knowledge.

The upload creates a knowledge entry from that file. To update it later, edit the entry and replace the attachment. If the skill references other documents, add those separately or sync its repository.

Sync a skills repository

1. Connect GitHub or GitLab in Settings → Integrations. See knowledge integrations.
2. In Knowledge, choose Add knowledge → Repository.
3. Select the provider, repository, and branch. For example, select altertable-ai/skills if it is available through your GitHub connection.
4. Choose the environment scope and select Add repository.

Repository sync imports supported Markdown and text files, including SKILL.md files. It skips local development skills under .agents/skills/, .claude/skills/, and .codex/skills/ at any depth. Keep skills you want to share as knowledge outside those directories, for example at skills/revenue-analysis/SKILL.md. Sync the repository again after changing the source files to refresh its knowledge entries.

How imported skills affect agents

Imported skills are indexed as knowledge. Agents can find them through knowledge search, including the search_entities MCP tool, and may use their instructions when answering questions or running tasks. Review the content before importing it: development conventions or conflicting instructions can steer an agent away from your intended analysis.

Turning off Automatically include in AI sessions keeps an entry out of the initial session context, but agents can still find it through search. The environment scope controls where the knowledge is available.

This imports the skill's content as reference material; it does not install an agent plugin or register a callable skill. To install Altertable skills in an external agent, follow Agent setup.

dbt repositories

Altertable detects dbt projects through dbt_project.yml and extracts knowledge from their source files. For Git-based sync, commit target/manifest.json alongside each project's source files on the connected branch to include model lineage and semantic metadata. Also commit target/semantic_manifest.json to preserve generated metric and semantic definitions in a dedicated knowledge entry for each project. Both paths are relative to the project's dbt_project.yml.

Syncing a repository does not run dbt to generate these artifacts or publish executable metrics. Follow the dbt repository setup to generate and refresh the artifacts, preserve metric definitions, and enrich matching semantic models.

What to include

Good entries are specific and reusable:

• How your company defines revenue, activation, churn, and retention.
• Which tables are authoritative for common analyses.
• Known caveats in source systems or ETL jobs.
• Product terminology and internal names that do not appear in schemas.
• Investigation playbooks for recurring incidents or workflows.

Keep entries current. Stale guidance can be worse than missing guidance because agents may confidently apply the wrong rule.

Learn more

• Semantic Layer: define metrics and dimensions directly on models.
• Memories: understand learned context from agent work.
• Ask Agent: use knowledge during conversational analysis.