counting-tokens

name	counting-tokens
description	Use when a user asks for the token count of a prompt, text snippet, or local file, or wants to estimate whether content will fit inside an OpenAI model context window.

Counting Tokens

Overview

gpt-tokenizer를 사용해 프롬프트나 로컬 파일의 토큰 수를 빠르게 계산하는 skill이다.

Core principle: 새 위치에 일회성 래퍼를 다시 만들지 말고, 이 skill 안의 검증된 스크립트를 그대로 재사용한다.

When to Use

• 사용자가 이 프롬프트 몇 토큰이야?, 이 파일 토큰 수 알려줘, 컨텍스트 윈도우에 들어가나?처럼 물을 때
• OpenAI 계열 모델 기준으로 텍스트 길이를 대략 검증해야 할 때
• 프롬프트 크기를 비교하거나 줄이기 전에 기준 숫자가 필요할 때

Do not use this skill for:

• Chat Completions 메시지 오버헤드, tool/function calling 오버헤드까지 정확히 계산해야 하는 경우
• 이미지, PDF 바이너리, 오디오처럼 순수 텍스트가 아닌 입력
• OpenAI 계열이 아닌 다른 토크나이저 규칙을 써야 하는 경우

Quick Reference

• skill root: /Users/pinion/.agents/skills/counting-tokens
• 설치: bun install
• 짧은 프롬프트: bun run count -- --text "Your prompt here"
• 파일 입력: bun run count -- --file /absolute/path/to/file.txt
• 모델: gpt-5 고정
• 검증: bun test

결과 JSON 필드:

• tokens
• chars
• bytes
• lines
• model
• sourceType
• source

Implementation

항상 skill root에서 실행한다.

cd /Users/pinion/.agents/skills/counting-tokens

1. Prompt text

짧은 단일 프롬프트는 --text로 바로 센다.

bun run count -- --text "Summarize the quarterly update in 5 bullets."

2. Local file

멀티라인 텍스트, 긴 시스템 프롬프트, quoting이 불안한 입력은 파일로 저장해서 --file로 센다.

bun run count -- --file /tmp/system-prompt.txt

3. Fixed model

이 skill은 항상 gpt-5 tokenizer를 사용한다. 사용자가 다른 모델을 언급하더라도 이 skill 자체는 바꾸지 말고, 필요하면 별도 요구로 처리한다.

Output

결과는 JSON으로 출력된다. 보통은 tokens를 먼저 답하고, 필요할 때만 chars, bytes, lines를 같이 덧붙인다.

예시:

{
  "tokens": 11,
  "chars": 24,
  "bytes": 24,
  "lines": 1,
  "model": "gpt-5",
  "sourceType": "text",
  "source": null
}

Common Mistakes

Mistake	Fix
다른 폴더에 새 토큰 카운터 스크립트를 또 만듦	이 skill의 bun run count를 그대로 재사용한다
긴 프롬프트를 셸 인용으로 직접 밀어 넣음	임시 파일로 저장한 뒤 --file을 사용한다
상대 경로 때문에 엉뚱한 파일을 읽음	가능하면 절대 경로를 사용한다
plain text 토큰 수를 Chat Completions 전체 요청 토큰과 동일시함	이 skill은 plain text/file 기준 추정치라는 점을 분리해서 설명한다
모델 옵션을 찾거나 다른 모델을 즉석에서 붙이려 함	이 skill은 gpt-5 고정이라는 점을 먼저 설명한다

Red Flags

• 잠깐이니까 여기서 바로 node one-liner로 세자
• playground에서 대충 보고 끝내자
• 긴 프롬프트도 그냥 --text로 밀어 넣자

이 생각이 들면 skill-local 스크립트로 돌아간다. 재사용성과 재현성이 목적이다.