Guide · Agent skill
How to use the TransformerLens interpretability agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains how to install and use the transformer-lens-interpretability agent skill, which teaches an AI agent to use the TransformerLens Python library for mechanistic interpretability. TransformerLens lets you open up GPT-style language models such as GPT-2 and inspect their internal activations. After reading, you will know what the skill changes, how to add it to your agent, how to ask for research tasks in plain language, and what to check before you run its code.
TransformerLens InterpretabilityOrchestra-Research/AI-Research-SKILLs · MIT Download the skill Quick start
- 1Download the skill ZIP. Download the ZIP file for the transformer-lens-interpretability skill from the page where you found this guide.
- 2Unzip it into a skills folder. Unzip the folder into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project. Or upload it under Settings, Capabilities, Skills in the Claude apps.
- 3Install TransformerLens. Run pip install transformer-lens in a Python environment with torch version 2.0.0 or later.
- 4Set HF_TOKEN if needed. Only for gated models such as LLaMA or Mistral, set the HF_TOKEN environment variable to your Hugging Face token.
- 5Ask for a specific research task. Describe the behaviour you want to study and name a model, for example gpt2-small, and ask the agent to use TransformerLens.
- 6Review and run the code. Read the code the agent writes, check the prompts and metric, then run it and inspect the cached activations or patching heatmap.
What the skill makes the agent do
An agent skill is a folder of instructions and reference files that an AI agent loads when a task matches the skill's description. This one covers mechanistic interpretability research: studying how a transformer model computes a behaviour by looking at its internal parts.
With the skill, the agent can cache internal activations from a model, study attention patterns, run activation patching experiments to find which parts of a model cause a behaviour, and do direct logit attribution. The skill gives the agent code patterns, a list of supported models, and checklists for these experiments, so it writes working TransformerLens code instead of guessing at the API.
- Cache and inspect intermediate activations such as residual streams, attention patterns and MLP outputs
- Run activation patching (causal tracing) across layers and token positions
- Replicate circuit analysis, such as the indirect object identification (IOI) task
- Detect induction heads in repeated sequences
- Apply direct logit attribution to see which heads push the output toward a token
Install the skill on your computer
Download the ZIP file for the skill from the page where you found this guide. Unzip it into one of two places. For a personal setup that works in every project, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project.
If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there. The skill folder should contain SKILL.md and a references folder with api.md, README.md and tutorials.md.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Set up the Python environment
The skill runs TransformerLens code, so you need Python with the library installed. The source lists transformer-lens version 2.0.0 or later and torch version 2.0.0 or later as requirements. Install TransformerLens with pip.
Model weights are downloaded at runtime, so you also need network access and enough disk space for the model you choose. Gated models such as LLaMA or Mistral need a Hugging Face token, which you set as the HF_TOKEN environment variable. Public models like gpt2-small do not need one.
- Python with transformer-lens>=2.0.0 and torch>=2.0.0
- Network access and disk space for downloaded model weights
- HF_TOKEN only for gated models such as LLaMA or Mistral
- A GPU and substantial memory for larger models; the source notes that larger models need substantial compute
pip install transformer-lensTrigger the skill with a natural request
You do not need special syntax. The skill loads when your request matches its description, which covers reverse-engineering model algorithms, studying attention patterns, and activation patching experiments. Describe the research goal in plain words and name the model if you have one in mind.
Good requests say what you want to learn and which model to use. Vague requests such as 'look inside my model' are less likely to produce useful code. If the agent does not seem to use the skill, name TransformerLens in your request.
- Ask: 'Use TransformerLens to find which layers and positions in GPT-2 small change the answer from Rome to Paris.'
- Ask: 'Cache the attention patterns for gpt2-small on this prompt and show me which heads attend back to the first token.'
- Ask: 'Set up a direct logit attribution for the IOI prompt in gpt2-small.'
- Name TransformerLens in the request if the skill is not picked up
Run an activation patching experiment
Activation patching is the main workflow in the skill. You write a clean prompt and a corrupted prompt that differ minimally, cache the clean activations, then copy clean activations into the corrupted run one layer and position at a time. A metric such as a logit difference shows where the output changes. The skill's checklist asks for clean and corrupted inputs, a metric, cached clean activations, a systematic sweep over each layer and position, a heatmap, and a list of causal hotspots.
The sweep is the slow part on larger models, so ask the agent to start with a small model such as gpt2-small.
- Clean prompt: 'The Eiffel Tower is in the city of'
- Corrupted prompt: 'The Colosseum is in the city of'
- Metric: logit of ' Paris' minus logit of ' Rome'
- Output: a layer by position heatmap of the metric
logits, cache = model.run_with_cache(tokens)
residual = cache['resid_post', 5]
attn_pattern = cache['pattern', 3]Know which models are supported
The skill lists over 50 supported models in families. The GPT-2 family includes gpt2, gpt2-medium, gpt2-large and gpt2-xl. The EleutherAI family includes pythia models from 70m to 12b, gpt-neo and gpt-j-6b. The list also includes LLaMA, Mistral, Mixtral, phi, qwen, opt and gemma models.
TransformerLens targets transformer models. For non-transformer architectures the skill itself says to use nnsight or pyvene instead. For sparse autoencoders it points to SAELens, and for remote execution on very large models it points to nnsight with NDIF.
- GPT-2: gpt2-small is the standard starting point in the examples
- Pythia and GPT-Neo/GPT-J for EleutherAI models
- LLaMA and Mistral models require HF_TOKEN
- Non-transformer models: use nnsight or pyvene
Limits and safety notes
The skill contains code that loads models and runs experiments, and it uses the network to download model weights. Read any code the agent writes before you run it, especially when it downloads from Hugging Face or when it uses a token. Keep your HF_TOKEN out of shared notebooks and screenshots.
The skill supplies research techniques only. It does not check whether a finding is correct or meaningful. Do not use results from these experiments to make production safety decisions or to audit a deployed model without expert review.
- The skill runs scripts and uses the network: review generated code before running it
- Keep HF_TOKEN secret and only set it for gated models
- Findings are not validated by the skill; check them with ablations and expert review
- Not suited to auditing live systems without expert oversight
What people use it for
- Finding which layers and token positions in GPT-2 small change a factual answer, using activation patching
- Replicating the indirect object identification circuit analysis on a sentence about John and Mary
- Caching attention patterns to see which heads attend back to earlier tokens in a repeated sequence
- Running direct logit attribution to see which attention heads push the output toward one token
- Teaching yourself mechanistic interpretability with runnable, guided examples
Frequently asked questions
Is the TransformerLens interpretability skill free?
The skill is released under the MIT licence, as stated in its SKILL.md. The source does not state the licence of the TransformerLens library itself, so check its repository before you rely on it commercially.
What do I need to install TransformerLens agent skill?
You need Python, transformer-lens version 2.0.0 or later, torch version 2.0.0 or later, network access to download model weights, and disk space. A Hugging Face token is only needed for gated models such as LLaMA or Mistral.
How do I install the TransformerLens skill in Claude?
Download the skill ZIP and unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ in a project. In the Claude apps you can instead upload it under Settings, Capabilities, Skills.
Does the skill work with every language model?
No. TransformerLens targets transformer models, and the source lists over 50 supported models in families such as GPT-2, Pythia, LLaMA and Mistral. For non-transformer architectures, the skill recommends nnsight or pyvene.
What is the difference between TransformerLens, nnsight and pyvene?
According to the skill, TransformerLens is built for transformer models with HookPoints on every activation. nnsight is the suggested choice for non-transformer architectures and for remote execution with NDIF, and pyvene is suggested for higher-level causal intervention abstractions.
Why does my TransformerLens code fail to load a model?
Check that transformer-lens and torch are installed at the required versions and that you have network access and disk space. For LLaMA or Mistral models, set the HF_TOKEN environment variable, because those models are gated.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill is a good fit for researchers, students and ML engineers who already work in Python and want an agent to write correct TransformerLens code for caching activations, patching and attribution on GPT-style models. It is not a fit for non-transformer architectures, for safety decisions on deployed models, or for anyone without a Python environment and enough compute to load the models.
Download the skill