"I'm the best at piloting this thing!"
There's a famous line from a Japanese mecha anime — the protagonist screams: 「僕が一番ガンダムをうまく使えるんだ！」 — "I'm the one who can pilot this Gundam the best!"
If you use AI coding tools every day, you've probably felt something similar. That sense of clicking with the AI. Knowing you're getting more out of it than most people around you.
But how do you show that?
"Look at my PR count"? "Check how many lines I generated"? That's not it. Those numbers don't capture the feel of working well with AI. That nagging gap between what you know and what you can prove is what got me started.
My own question, answered
In my previous post, I asked:
Is your team measuring AI coding productivity by any of these?
| Common metric | What it actually rewards |
|---|---|
| Lines of code generated | Volume targets promote bloat |
| Number of prompts per session | High count may signal poor instructions, not hard work |
| Response speed | Penalizes people who think before they ask |
| Commit count | Easily inflated by splitting work |
| Number of AI tools adopted | Using ≠ using well |
They all measure quantity. But whether you're actually good at working with AI never shows up in volume metrics.
That article laid out three enduring principles: keep things reversible, make intent explicit, verify outputs. AI Fluency is my attempt to turn those into a structured self-reflection — not a score that ranks you, but a mirror that shows you how you collaborate.
Why "Fluency"?
Fluency — like language fluency. When you're fluent, conversation flows naturally. You don't stumble, backtrack, or struggle to express what you mean.
Working with AI has a similar feel. When it's going well, your instructions and the AI's output click, and the work just flows. When it's not, you're stuck in loops of corrections and rework.
AI Fluency tries to visualize that — how naturally you collaborate with AI.
Here's what I built
My result: The Explorer — the type that explores new ways of using AI. Strong in Breadth, with room to grow in Precision.
Full ability sheet: profile.md
Repo: github.com/suruseas/ai-fluency
Also available in Japanese on Qiita.
A Different Yardstick: 5 Axes
By breaking down what "fluency" actually means in practice, I landed on five dimensions:
| Axis | What it measures |
|---|---|
| Context Design | Setting up the environment so the AI can do its best work |
| Precision | Communicating intent clearly with minimal back-and-forth |
| Steering | Guiding AI output in the right direction; judging quality |
| Output | Actually delivering value through AI collaboration |
| Breadth | Using AI's capabilities across diverse tasks, not just one pattern |
The first three map to the enduring principles from the previous article:
- "Make intent explicit" → Context Design + Precision
- "Verify outputs" → Steering
The remaining two go further — asking whether the collaboration actually produces results (Output) and whether you're using AI's full range or stuck in a single pattern (Breadth).
Not "fewer prompts is better" — but "can you get it right with fewer exchanges?" Not "more commits" — but "are you actually achieving your goals?" That shift — from quantity to quality — is the whole point.
A note on methodology
These five axes weren't derived from a literature review or formal research. They emerged from iterating with AI itself — breaking down what "good collaboration" felt like across dozens of my own sessions, then pressure-testing the categories until they stopped overlapping. It's an opinionated framework, not a scientific instrument. I think that's okay for a self-reflection tool.
16 Style Types — A Bit of Fun That Stuck
After generating the 5-axis scores, I realized raw numbers are hard to talk about. "My Context Design is 76 and Breadth is 96" — not exactly cocktail-party material.
So I put together a personality-type system on a whim — classifying people by the shape of their radar chart. It turned out to be surprisingly intuitive, so it stuck.
The types are determined by which axes stand out, not by how high your scores are. It's about style, not rank. Here are a few:
- The Sniper (Precision) — Minimum input, maximum output. One-shot instructions that just work.
- The Architect (Context Design) — Master of setting the stage. The AI barely needs to ask questions.
- The Explorer (Breadth) — Always finding new ways to use AI. First to try MCP, plugins, sub-agents.
- The Surgeon (Precision + Steering) — Precision and finesse for tough problems.
- The Virtuoso (Balanced) — Well-rounded across all axes.
There are 16 types in total (1 balanced + 5 primary + 10 hybrid). See the full list in the repo.
High scores across the board aren't the goal — every shape has meaning.
Honest Limitations
This is a self-reflection tool, not a performance metric. A couple of things to know:
- Scores vary between runs. The qualitative assessment uses an LLM, so results aren't deterministic. That's a tradeoff of using AI-based evaluation — I leaned into it by emphasizing shape over absolute numbers.
- Style is personal, not comparable. Common rubric, but not an identical scale. Your "72" and someone else's "72" don't mean the same thing. The radar chart shape is what matters.
There's also an inherent circularity worth naming: the tool uses an LLM to evaluate how well you work with an LLM. It may have blind spots — for example, favoring verbose sessions over terse-but-expert ones. I don't have a fix for that yet, but I think the transparency of the framework (all scoring logic is in the repo) helps.
How to Use It
It currently supports Claude Code session data. The five axes themselves are agent-agnostic by design — support for other agents is planned.
# 1. Clone & setup
git clone https://github.com/suruseas/ai-fluency.git
cd ai-fluency
npm install
# 2. Generate session analysis in Claude Code
claude> /insights
# 3. Generate your scorecard (English output)
npm run score # → output/scores.json
npm run card # → output/card-dark.svg, card-light.svg
npm run profile # → output/profile.md
Or even simpler: if you're already in a Claude Code session, just type /ai-fluency — it handles everything in one shot.
This produces SVG cards (dark/light themes) and a Markdown ability sheet in output/. To embed the card in your GitHub README, see the instructions in the repo.
Wrapping Up
This started as my answer to a question I posed in my previous article: if lines of code and prompt counts are the wrong metrics, what should we look at?
My answer: Context Design, Precision, Steering, Output, Breadth — the quality of human-AI collaboration, not the volume.
It's not a perfect tool. But if it makes you stop and think, "Huh, so that's how I work with AI" — that's enough.
If you use Claude Code, it takes about 2 minutes. Drop your type in the comments — I'll compile the dev.to distribution in a follow-up post!
suruseas
/
ai-fluency
AI Fluency - Score your AI collaboration style across 5 axes
AI Fluency
GitHub プロフィールに貼れる「AI活用力」のスコアカード生成ツール。
AI エージェントとの協働スタイルを5軸でスコアリングし、SVGカードと能力シートを出力します。評価軸はエージェント共通の設計ですが、現時点では Claude Code のセッション分析データ（/insights で生成）に対応しています。
カード例
前提条件
現在の対応エージェント: Claude Code
- Claude Code がインストール済みであること
- Claude Code でのセッション履歴があること（分析対象データとして必要）
他の AI エージェントへの対応は今後追加予定です。
試してみる
1. リポジトリをクローンしてセットアップ
git clone https://github.com/suruseas/ai-fluency.git
cd ai-fluency
npm install
2. facets データを生成する
Claude Code で /insights を実行してください。セッション履歴が分析され、~/.claude/usage-data/facets/ に facets データ（JSON）が生成されます。
claude> /insights
Note: facets データがない状態では以降のステップは実行できません。
3. スコアカードを生成する
クローンしたディレクトリで Claude Code を起動し、/ai-fluency を実行します。
cd ai-fluency
claude
claude> /ai-fluency
直近3ヶ月分のデータを対象に、スコア算出からカード・能力シートの生成まですべて自動で行われます。
手動で実行する場合
# 定量スコアのみ算出（output/scores.json に出力）
npm run score
# SVG カードを生成（output/card-dark.svg, card-light.svg）
npm run card:ja # 日本語版
npm run card # 英語版（デフォルト）
# 能力シートを生成（output/profile.md）
npm run profile:ja # 日本語版
npm run profile # 英語版（デフォルト）
生成物はすべて output/ ディレクトリに出力されます。
注意: 生成物にはプロジェクト固有の情報は仕組み上含まれませんが、
output/profile.mdに機密情報が出力されていないことを公開前にご確認ください。
3. README に埋め込む
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/suruseas/ai-fluency/main/output/card-dark.svg">
<img src="https://raw.githubusercontent.com/suruseas/ai-fluency/main/output/card-light.svg" alt="AI Fluency">
</picture>
スコアについて
スコアの一部（定性評価）は AI がセッション内容を読み取って判定しています。そのため以下の点にご注意ください。
- 再現性はありません — 同じデータでも実行ごとにスコアが多少変動します
- …
Top comments (0)