Instrumentation skill

The Faultsense instrumentation skill teaches AI coding agents how to add fs-* attributes that are actually semantically correct — picking the right trigger, the right assertion type, the right modifiers, and placing them on the element users actually interact with.

This is a different install from the agent itself.

  • The agent (script tag, npm) runs in your users' browsers. It evaluates the fs-* attributes and ships results to a collector.
  • The skill runs in your editor. It activates when you ask your AI coding agent to "add assertions" or "instrument this component," and it guides the agent through the decision tree.

You need the agent to capture production data. You need the skill if you want an AI to help you author the fs-* attributes.

Claude Code — via the Faultsense marketplace (recommended)

/plugin marketplace add Faultsense/faultsense-ai
/plugin install faultsense-instrumentation@faultsense-ai

Once installed, ask your agent anything Faultsense-shaped — "add assertions to this checkout form," "instrument the todo-toggle," "review my fs-* attributes" — and the skill activates automatically.

SSH error? The marketplace installer clones via SSH. If you see Permission denied (publickey), either configure an SSH key or use the direct install below — it uses HTTPS.

Claude Code — direct via --plugin-dir

Use when you need the skill on a machine that can't reach the marketplace, your SSH keys aren't configured, or you're tracking a specific release:

git clone https://github.com/Faultsense/faultsense-claude-plugin.git
claude --plugin-dir ./faultsense-claude-plugin

Pin to a tag if you need exact reproducibility:

git -C ./faultsense-claude-plugin checkout v0.5.4
claude --plugin-dir ./faultsense-claude-plugin

Cursor, OpenCode, Goose, Gemini CLI, and other agentskills.io-compatible agents

The Faultsense skill follows the agentskills.io open standard, so it works in any tool that implements the spec. Install by copying the skills/faultsense-instrumentation/ subdirectory of the plugin repo into your tool's skills location:

git clone https://github.com/Faultsense/faultsense-claude-plugin.git /tmp/fs-plugin
cp -r /tmp/fs-plugin/skills/faultsense-instrumentation ~/.cursor/skills/
#   or ~/.config/opencode/skills/
#   or ~/.goose/skills/
#   — path varies by tool, check your agent's docs

The .claude-plugin/plugin.json at the plugin repo root is Claude Code-specific metadata and is benignly ignored by other agents.

Verify the skill activated

In a fresh agent session, type /skill or whatever your tool's equivalent is — faultsense-instrumentation should appear in the list. Or just prompt the agent:

Add Faultsense assertions to this component.

If the skill is installed, the agent will walk through the decision tree (trigger → assertion type → modifiers → placement) rather than guessing. If it stubs an assertion like fs-assert-click-loaded that doesn't exist, the skill didn't load — check your install.

What the skill teaches

  • Trigger selection — when to use click vs. submit vs. mount vs. invariant vs. event:<name>, plus placement rules for nested elements
  • Assertion-type selection — the critical added vs. updated vs. visible distinction (the #1 instrumentation mistake), when mutation-observed resolvers beat querySelector
  • Modifier chaining — text-matches, classlist, count, detail-matches, attribute checks
  • Conditional outcomes — fs-assert-<type>-<condition> suffix patterns and fs-assert-mutex for multiple possible results
  • OOB (out-of-band) assertions — side-effect checks against a parent assertion's pass/fail
  • Framework integration — per-framework binding specifics for React, Vue, Svelte, Alpine, HTMX, Hotwire, Livewire, LiveView, Astro, Solid

The skill doesn't replace reading the attribute reference — it gives your agent the mental model for choosing correctly among those attributes.

Keeping the skill current

The marketplace install auto-updates when you run /plugin install faultsense-instrumentation@faultsense-ai again. Versions track the agent — [email protected] ships the reference surface for @faultsense/[email protected], and future releases match the pattern. Lock to an exact version via --plugin-dir if you need deterministic behavior.

Where the skill lives

The skill is released one-way from the private Faultsense monorepo to two public repos:

Both are read-only release targets. File issues upstream against the agent repo; edits to the plugin repo won't be reviewed.