Add interaction-reference skill for BYOA agent behavioral steering

[rayshan]

Exec Summary

Adds Carta's AI Agent Interaction Reference as a plugin skill to steer how customer BYOA agents (Claude Code, Cowork) present cap table data. When the plugin is installed, the agent automatically follows Carta's voice, tone, financial precision, and data provenance standards — distinguishing Carta data from agent-computed data, citing sources, and using consistent Carta terminology.

Key Design Decisions

• Inlined as skill body (temporary) — The full external reference (~470 lines) is the SKILL.md body itself. This guarantees all rules are in context the moment the skill triggers. This is a pragmatic first step — the intent is to find a way to reuse the canonical reference across projects (plugins, system prompts, custom agents) without maintaining separate copies, making updates a single-source change.
• user-invocable: false — Background knowledge, not a user command. Description stays in context; Claude auto-invokes alongside domain skills.
• Belt-and-suspenders triggering — Pushy skill description + SessionStart hook reminder together ensure reliable co-loading with domain skills.
• Stripped pro-forma-model — Removed presentation/behavioral guidance from the pro-forma-model skill that now overlaps with the interaction reference (disclaimer templates, bar chart format rules, table templates). Domain logic (round math, SAFE conversion, option pool shuffle) is preserved.

Summary of Changes

• New interaction-reference skill — Carta's behavioral rules for presenting cap table data (voice, tone, financial precision, data provenance, trust & safety, audience calibration). Auto-loaded alongside domain skills for every Carta query.
• SessionStart hook enhanced — Added reminder to always co-load the interaction-reference skill alongside domain skills.
• Pro-forma-model skill slimmed — Removed 52 lines of presentation guidance that now lives in the interaction reference. Keeps all domain-specific computation logic.

Affected user flows

• Any BYOA agent query involving Carta cap table data now gets behavioral steering (voice, data attribution, financial precision)
• Pro-forma modeling flow works the same but presentation quality now depends on interaction-reference being co-loaded

Other changes

• README updated with the new skill entry

A/B Testing

Ran side-by-side sessions using git worktrees — one with the interaction-reference skill, one without (baseline). Tested pro-forma modeling prompts. Key observed deltas: data provenance labeling ("from Carta" attribution), best-effort disclaimers on agent-computed data, ASCII bar chart visualization, and more direct BLUF structure. Stripping presentation guidance from the domain skill amplified the delta significantly.

TODOs

• Find a reusable mechanism to share the canonical interaction reference across projects without maintaining separate inlined copies
• Run description optimization loop (skill-creator) to refine triggering accuracy
• Consider stripping overlapping presentation guidance from other domain skills (ownership, portfolio-query, etc.) as done for pro-forma-model
• Evaluate whether a PreToolUse hook would provide stronger triggering guarantee for simple queries that skip skills

Test Coverage Delta

No automated tests. Manual A/B testing via worktree-based side-by-side sessions (demo transcripts in _temp_ray/).

Demo

Carta.AI.Agent.Interaction.Guide.demo.mov

[etarhan]

https://github.com/carta/claude-marketplace/pull/386