The 247-Character Rule: Why Your AI Skill Descriptions Are Never Read

Mike set his fourth cup of coffee by the keyboard. The Claude Code terminal on the screen stayed perfectly still. Last month he’d followed three tutorials and written six skills. All of them sat under .claude/skills, untouched, like a gym membership.

“It never touches my skills,” he said across the partition.

Sarah kept typing. “You call those skills?”

“What else would you call them?”

She rolled her chair over. Her screen showed a folder named deploy-service. Inside, besides SKILL.md, were references/, scripts/, assets/, even a shell script for a smoke test. The first line of her SKILL.md wasn’t a title — it was a tight, clipped description: “Use this skill when the user needs to deploy to staging, encounters an SSL certificate error, or requires a version rollback.”

“Two hundred forty-seven characters,” Sarah said. “One more and the system cuts it off. Your description was over three hundred. All the model saw was ‘helps with database-related tasks…’ and an ellipsis. How was it supposed to know when to fire?”

Mike pulled up his own description. After “handling connection pool timeouts, slow query location, schema migrations” came ellipses. The second half — “and prioritize use when encountering replication lag alerts” — had never been read by the model.

That afternoon he broke his six skills into proper folders, trimmed every description to under two hundred thirty characters, and added a line at the bottom of the subscriptions skill: Gotcha: The subscriptions table is append-only. To get the latest version, sort by version, not by created_at. That was a pitfall he’d discovered last quarter and never written down.

The next morning at 10:04 he asked Claude to investigate a duplicate charge. The terminal flickered. The subscriptions skill triggered. The model opened references/troubleshooting.md on its own, found the status explanation for payment_events, and didn’t circle created_at the way it used to.

“It used it?” Mike’s voice came out louder than he meant.

Sarah laughed, tapping a classification chart on her screen with her pen. They’d sorted the forty‑odd skills into nine categories: Library & API Reference, Product Verification, Data Query & Analysis, Business Process Automation, Code Scaffolding, Code Quality & Review, CI/CD & Deployment, Runbook Troubleshooting, Infrastructure Operations. Mike took a highlighter and circled the top row — Verification.

“This one’s worth the time,” Sarah said. “Let it verify its own code.”

She fished a mint from her drawer and tossed it at him. “That registration flow bug last time — Claude fixed it, spun up a headless browser, clicked all the way through email verification, and recorded a video. Lauren from product just stared. I spent a whole week polishing that skill.”

Mike started raising his skills as folders. The morning standup report skill ran on day one, writing results into a JSON file under the CLAUDE_PLUGIN_DATA directory. The next day Claude read yesterday’s record first, automatically filtering out tickets already reported. He packed a few repetitive data‑cleaning functions into scripts/. Instead of rewriting the data‑fetching logic from scratch each time, the model assembled ready‑made blocks in seconds.

Friday at 4:17 p.m., he activated the careful skill before a deployment. The terminal blocked an rm -rf command and flashed: Are you sure you want to execute this in prod? [y/N] Mike pulled his hand back from the Enter key.

The team began filling .claude/skills at the root of the repo. Soon everyone’s context budget was bursting. At that week’s meeting, Mike drew a small square in the upper‑left corner of the whiteboard and wrote “Sandbox → Marketplace.” The rule: anyone who wanted to share a skill would drop it into a GitHub folder called skill-sandbox. Once enough people were using it, the author would open a PR to move it into the official plugin marketplace. No approvals — just people voting with their feet.

Lisa from QA handed over a skill called trace-id. Its description was a single sentence: “Use this skill when the user provides a request ID and needs to align fields between the API gateway logs and the billing system logs. Note: the gateway calls it @request_id, the billing system calls it trace_id — they are the same value.”

Sarah moved it into the marketplace. The skill was invoked nine times that afternoon.

Two days later Mike added instrumentation to the five most‑used skills — a PreToolUse hook logging every call. The data came back. Two skills had near‑zero trigger counts. He checked their descriptions: one read “Helps the team improve efficiency,” the other “Optimizes workflow.” Human‑readable, model‑meaningless fluff.

He changed “improve efficiency” to “Use when the user needs to generate a CSV and interface with the internal data warehouse export endpoint.” The next day, zero became four.

At seven in the evening, only the two of them were left in the office. Mike spat out the last release note from an assets template and, on his way, watered the nearly dried‑out pothos on Sarah’s desk. Outside, the Bay Bridge lights blinked on, fog draping the cable towers.

The terminal printed: Deploy completed. Smoke test passed. Release note generated.

Sarah swung her bag over her shoulder and stopped beside his workstation. Mike opened his mouth. She pointed at the clock in the bottom‑right corner of his screen.

“Don’t pull another all‑nighter.”

He nodded. He folded the classification chart with its fluorescent tags, tucked it into the drawer. Inside were three mints, still unwrapped.