Plugin components

Plugins are the installed product. Skills are one executable component inside that product. Telvine stores a versioned inventory of declared components and records runtime events only where the plugin author or host can reliably emit them.

Documented component surface

Component	Codex	Claude Code / Cowork	Telvine telemetry
Skills	skills/*/SKILL.md	Skills bundled in plugins	skill.* execution events; inventory
Manifest	.codex-plugin/plugin.json	.claude-plugin/plugin.json	Inventory; validation events only
Commands	Runtime-specific command files	commands/ and manifest commands	plugin.component.* when executed or wrapped; inventory otherwise
Apps / connectors	.app.json app mappings	Cowork connectors	plugin.component.* if the connector integration emits; inventory otherwise
MCP servers / config	.mcp.json	.mcp.json and manifest mcpServers; Cowork may bundle local MCP-backed connectors	plugin.component.* from a wrapper or integration; never tool arguments
Hooks	hooks/hooks.json	hooks/hooks.json	plugin.component.* from hook code; inventory
Agents / sub-agents	Not listed as a Codex plugin component in current docs	agents/ and manifest agents	Inventory; execution only when explicitly emitted
Tools, channels, model providers, memory, context engines, and harness adapters	Runtime-specific plugin surfaces	Runtime-specific plugin surfaces	plugin.component.* when the runtime or wrapper emits; inventory otherwise
LSP servers, output styles, themes, monitors, executables, settings, user config, dependencies, scripts	Not listed in current Codex plugin docs	.lsp.json, output-styles/, themes/, monitors/, bin/, settings.json, manifest fields, and scripts/	Inventory; execution only when wrapped
Assets / UI resources	Presentation assets	Plugin resources where packaged	Inventory only

Sources: Codex plugin authoring, Codex Skills, Claude Code plugins, Claude plugin manifest reference, and Claude Cowork plugins.

Claude component inventory

Claude's plugin manifest and default directories map cleanly into Telvine's component inventory:

Claude surface	Telvine component type	Directory	Manifest field
.claude-plugin/plugin.json	manifest	.claude-plugin	unknown
skills/*/SKILL.md	skill	skills	skills
commands/	command	commands	commands
agents/	agent or sub_agent	agents	agents
hooks/hooks.json	hook	hooks	hooks
.mcp.json or mcpServers	mcp_server or mcp_config	mcp	mcpServers
.lsp.json or lspServers	lsp_server	lsp	lspServers
output-styles/	output_style	output-styles	outputStyles
themes/	theme	themes	experimental.themes
monitors/	monitor	monitors	experimental.monitors
bin/	executable	bin	bin
scripts/	script	scripts	scripts
settings.json or settings	settings	settings	settings
userConfig	user_config	.claude-plugin	userConfig
dependencies	dependency	.claude-plugin	dependencies
Directory scan or packaging step	directory	matching directory	matching field

Telvine stores plugin-relative component_path values only, such as skills/code-reviewer/SKILL.md or hooks/hooks.json. Do not send absolute local paths, user file paths, prompts, connector payloads, tool arguments, or model outputs.

When a Claude manifest field points at a custom path, keep the same component type and manifest field. The custom path goes in component_path; the canonical component bucket stays in component_directory.

Claude manifest field	Example value	Inventory component
skills	"./custom/skills/"	one skill per resolved <name>/SKILL.md
commands	"./custom/cmd.md" or ["./cmd1.md"]	one command per resolved Markdown command
agents	"./custom/agents/reviewer.md"	one agent or sub_agent per resolved agent file

{
  "component_type": "agent",
  "name": "reviewer",
  "telemetry_mode": "component_events",
  "component_path": "custom/agents/reviewer.md",
  "component_directory": "agents",
  "manifest_field": "agents",
  "source": "manifest_path"
}

Register a component inventory

Create a plugin with POST /v1/plugins, then record each shipped version:

{
  "version": "1.2.0",
  "manifest_format": "claude",
  "manifest_hash": "4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a",
  "marketplace_published_git_url": "https://github.com/acme/agent-plugin-marketplace.git",
  "components": [
    {
      "component_type": "skill",
      "name": "close-books",
      "telemetry_mode": "skill_events",
      "component_path": "skills/close-books/SKILL.md",
      "component_directory": "skills",
      "manifest_field": "skills",
      "source": "default_directory"
    },
    {
      "component_type": "mcp_server",
      "name": "xero",
      "telemetry_mode": "component_events",
      "component_path": ".mcp.json",
      "component_directory": "mcp",
      "manifest_field": "mcpServers",
      "source": "manifest_path"
    },
    {
      "component_type": "monitor",
      "name": "release-health",
      "telemetry_mode": "declaration_only",
      "component_path": "monitors/release-health.json",
      "component_directory": "monitors",
      "manifest_field": "experimental.monitors",
      "source": "default_directory",
      "experimental": true
    }
  ]
}

telemetry_mode is one of skill_events, component_events, declaration_only, or host_unavailable. The distinction prevents a package inventory from being mistaken for observed usage. component_path is the plugin-relative path inside the package. component_directory lets Telvine aggregate telemetry by folder, and manifest_field records which manifest entry declared or generated the component.

marketplace_published_git_url records the Git URL where this plugin version was published from or into a marketplace. Use a GitHub HTTPS URL, git://, ssh://, or git@host:org/repo.git form. Local folders should be resolved to their published Git remote before they are stored.

Emit component events

Use a plugin-scoped write key for package-level events:

Plugin-scoped write keys are created by telvine publish ./my-plugin or by an authenticated runtime-key exchange. POST /v1/runtime/write-key requires a Clerk session token or read-scoped Telvine key for the same org/plugin before it will mint a short-lived write key for an installation.

{
  "event_type": "plugin.component.invoked",
  "plugin_id": "plg_abc12345",
  "version": "1.2.0",
  "installation_id": "inst_xyz12345",
  "occurred_at": "2026-05-27T12:34:56.789Z",
  "idempotency_key": "01HX0000000000000000000000",
  "runtime": "codex-app",
  "properties": {
    "component_type": "mcp_config",
    "component_name": "xero",
    "operation": "configured",
    "component_path": ".mcp.json",
    "component_directory": "mcp",
    "manifest_field": "mcpServers",
    "duration_ms": 200
  }
}

Use component_type: "directory" when the observable unit is a packaging, scan, validation, or resolution step for a directory rather than a runtime capability.

Do not emit prompts, connector payloads, tool arguments, absolute or user content file paths, retrieved records, hook input, or generated content. For a component the host does not expose, store it in inventory with host_unavailable; do not infer usage.