Why a 500‑Line Skill Outperforms a 1000‑Line One: From Using AI to Teaching It

Hello, I'm James. In the previous post I dissected Claude Code's startup performance, showing how engineering tricks can make even a 500‑KB CLI start in 12 ms. That article raised a bigger question: what happens after the AI starts?

01 Where do your Prompts go?

Many developers spend time crafting a useful Prompt, copy it to Notion, and then never open it again. Others repeatedly re‑describe the same requirements for unit tests, or have team members issue wildly different commands, leading to inconsistent code style. When a teammate leaves, their "spells" disappear.

This is not laziness or a lack of team standards; it is a fundamental limitation of the Prompt format. Prompts are conversational knowledge that lives only in the current window and disappear once the session ends—no version control, no sharing, no reuse.

Writing the same knowledge in a SKILL.md file turns it into an "AI skill" that can be loaded repeatedly.

Prompt is consumption; Skill is investment.

02 What exactly is a Skill?

A Skill is essentially a structured Prompt Engineering package bundled as a folder:

my-skill/
├── SKILL.md          ← core file: instructions + context + examples
├── scripts/          ← optional executable scripts (Python/Bash/...)
├── references/       ← optional reference docs (design/API/...)
└── templates/        ← optional output templates (code scaffolds/...)

Although the physical form is simple, a Skill transforms domain knowledge, processes, coding standards, and best practices into a set of structured commands that AI can automatically understand, trigger, and execute.

A Skill consists of three core elements:

Instructions : tell the AI "what to do when a certain situation occurs".

Context : provide background knowledge such as API field definitions, library version quirks, or team architecture conventions.

Tools : give the AI callable capabilities like scripts, MCP tools, or template code.

Combined, these turn a plain text prompt into an executable skill package that the AI loads once and no longer needs repeated explanations.

03 Why write Skills? Five pain points and one solution

Pain point 1 – Scattered knowledge : guidelines are spread across Confluence, GitLab Wiki, code‑review comments, and senior engineers' heads. Skills centralize this knowledge into a single file that the AI can load.

Pain point 2 – Repetitive brick‑moving : repeatedly saying "write a Controller like UserController". A Skill encodes the reference so the AI follows it automatically after one write.

Pain point 3 – Inconsistent output : different team members generate React components in different styles. Skill instructions enforce a uniform output format.

Pain point 4 – Slow onboarding : newcomers spend weeks learning the "right way". Skills inject the standards directly into the AI workflow, letting new hires produce compliant code immediately.

Pain point 5 – Knowledge loss when people leave : departing engineers take implicit knowledge with them. Skills externalize that knowledge as explicit documentation and commands.

04 Progressive loading mechanism

The cleverness of a Skill lies not in its content but in its loading mechanism, which has three layers:

Level 1: name + description      ← always resident in the AI's system prompt
Level 2: SKILL.md body          ← loaded on trigger, recommended ≤500 lines
Level 3: scripts / references   ← on‑demand, loaded only when the AI explicitly requests them

Level 1 (Eye) : name and description stay in the system prompt; they cost few tokens but decide when the AI will recall the Skill.

Level 2 (Brain) : when the AI matches a task to the description, the full SKILL.md is injected. This is the core of the Skill.

Level 3 (Hand) : scripts and reference files are never loaded automatically; they are fetched only if the AI needs them during execution.

Level 1 – be precise. Level 2 – be concise. Level 3 – load freely.

Why these principles?

Level 1 determines trigger accuracy. Vague descriptions either never fire or fire at the wrong time.

Level 2 determines token consumption. Loading a thousand‑line document each time would burn many tokens; keeping it ≤500 lines is cost‑friendly.

Level 3 has no token cost because it is fetched only when needed, allowing large scripts or full API docs without performance penalty.

05 How to organize a Skill's internal structure

A well‑crafted SKILL.md typically contains:

YAML header (required) :

---
name: react-component-generator
description: |
  Generate React functional components with TypeScript.
  Triggered when user asks to create a new component,
  add a UI element, or build a page section.
  Uses project's existing component patterns and
  design system tokens.
---

Overview (3‑5 sentences) : what the Skill does, the applicable scenario, and when NOT to use it.

Prerequisites :

## Prerequisites
- Node.js >= 18
- Project uses React 18 + TypeScript + Tailwind CSS
- Design tokens available in `src/styles/tokens.css`

Step‑by‑step process (core flow) :

1. Read the component's requirements from the user's request.
2. Check if a similar component already exists in `src/components/`.
3. If yes, extend it; if no, create a new file.
4. Generate the component following the template below.
5. Add a Storybook story in `src/stories/`.
6. Export the component from `src/components/index.ts`.

Code example (Before/After diff) :

- // Before: Class component
- class UserCard extends React.Component<Props> { ... }
+ // After: Functional component with hooks
+ const UserCard: React.FC<Props> = ({ user }) => {
+   const [expanded, setExpanded] = useState(false)
+   return <div>...</div>
+ }

Verification checklist :

## Verification Checklist
- [ ] Component uses functional style + TypeScript
- [ ] Props are destructured at the top
- [ ] No `any` type used
- [ ] Storybook story covers all variants
- [ ] Unit test covers all props combinations

Common pitfalls (edge cases) :

## Common Pitfalls
- DO NOT use `useEffect` for derived state — use `useMemo` instead
- If the component needs server data, use `react-query`, not `fetch` in `useEffect`
- Tailwind classes must use project design token names, not arbitrary values

06 Skill vs Rule: know which you are using

Rule is a "bottom line" that always applies, e.g., "All API calls must have a 10 s timeout" or "Never use the any type". It is like traffic law—no context needed.

Skill is a "capability" that triggers only in specific scenarios, e.g., "When generating a React component, follow the team template". It is like a toolbox item used only when needed.

If you want the AI to always remember something → write a Rule. If you want the AI to act only in certain situations → write a Skill.

In practice, a healthy project keeps 5‑10 core Rules and 10‑20 project‑level Skills.

07 Six key techniques for writing good Skills

Technique 1 – Description is your ad slot

The Description field is the AI's search engine for matching a Skill. It should contain three parts: the scenario, keywords, and boundary conditions.

# ❌ Too vague
description: Helps with React components.

# ✅ Precise trigger
description: |
  Generate new React functional components with TypeScript
  when the user asks to "create a component", "add a UI element",
  or "build a page section". Uses the project's design system and
  existing patterns. NOT for modifying existing components — use the
  refactoring skill.

Technique 2 – Open with three facts

The first three sentences of SKILL.md must state WHAT, WHY, and WHEN NOT to use the Skill.

This skill generates new React components following the
project's established patterns. Following this pattern
ensures all components in the codebase are consistent,
which reduces onboarding time for new team members by 40%
and cuts PR review cycles in half.

DO NOT use this skill when modifying an existing component —
the refactoring skill handles that case.

Technique 3 – Imperative sentences with reasons

# ❌ Pure commands – AI doesn't know why
MUST use functional components.
MUST use TypeScript interfaces for props.

# ✅ Command + reason – AI understands the trade‑off
Use functional components with hooks.
→ This avoids `this` binding issues and makes the component tree easier to debug.
Define props as TypeScript interfaces, not type aliases.
→ Interfaces support declaration merging, which our design system's type augmentation relies on.

Technique 4 – Before/After diff format

Show the change explicitly; AI can spot the difference more easily than from a full example.

- // Before: Ad‑hoc error handling
- try { await api.getUsers() } catch (e) { console.log(e) }
+ // After: Structured error handling with user feedback
+ try {
+   const users = await api.getUsers()
+   return users
+ } catch (e) {
+   const message = parseApiError(e)  // from shared error utils
+   showToast(message, 'error')       // user‑visible feedback
+   reportError(e, { source: 'getUsers' })  // central error tracking
+ }

Technique 5 – 3‑5 few‑shot examples

## Examples
**Input:** "Create a search bar for the user list page"
**Output:** `src/components/SearchBar.tsx`
→ Uses `useDebounce` hook from shared hooks
→ Emits `onSearch(query: string)` callback
→ Includes loading state and empty state
→ No results → shows `EmptyState` component from design system

**Input:** "Add a modal for confirming deletion"
**Output:** `src/components/ConfirmModal.tsx`
→ Uses `Modal` wrapper from `src/components/ui/Modal.tsx`
→ Accepts `onConfirm`, `onCancel`, `title`, `message` props
→ Primary button uses `variant="danger"` design token

Technique 6 – Mark error‑prone spots and boundaries

## Edge Cases & Gotchas
❌ Setting `fetch` in `useEffect` — use `react-query` instead.
   The `useEffect + fetch` pattern causes race conditions when props change rapidly.
❌ Importing from `../../components/Button` with relative paths.
   Always use the path alias: `@components/Button`.
❌ Adding inline Tailwind colors like `text-[#ff0000]`.
   Use design tokens: `text-brand-red` or `text-error-500`.

08 Where to store Skills: user‑level vs project‑level

~/.claude/skills/          ← user‑level: applies to all projects
    ├── git-workflow/
    ├── code-review-checklist/
    └── writing-blog-posts/

.project/.claude/skills/   ← project‑level: applies only to this repo
    ├── react-component/
    ├── api-migration/
    └── database-schema/

User‑level Skills contain generic capabilities (git workflow, code‑review checklist, writing style). Project‑level Skills hold project‑specific conventions (component generation, API migration steps, schema management). If a Skill is useful in more than two projects, promote it to user‑level.

09 How a good Skill evolves

Example: a database‑migration Skill.

Version 1 (V1) – vague and trusting AI :

# Database migration
When a user needs to modify a table, use this Skill.
1. Generate up migration script
2. Generate down migration script
3. Ensure safe execution
Use ALTER TABLE statements, watch performance.

AI produced scripts with wrong column types, missing indexes, reversed down scripts, and no transaction wrapping.

Version 3 (V3) – exhaustive, error‑proof :

# Database migration
Execute PostgreSQL table changes. Applicable when the user mentions "add column", "alter table", or "create index".

## Why strict compliance is required
- Locking a table >5 s blocks user requests.
- Wrong down script prevents rollback, leading to manual data fixes.
- Missing IF NOT EXISTS causes CI failures on repeated runs.

## Hard rules (violation = production incident)
1. All ALTER statements must be inside a transaction → atomic rollback.
2. Columns must not default to NULL → ORM mapping consistency.
3. New columns require IF NOT EXISTS → idempotent migrations.
4. Large tables (>1 M rows) must not share a transaction with business SQL → avoid long locks.
5. Indexes must be created CONCURRENTLY and never inside a transaction.

## Output format
up: `migrations/YYYYMMDD_HHMMSS_desc.up.sql`
down: `migrations/YYYYMMDD_HHMMSS_desc.down.sql`

## Verification checklist
- [ ] Large‑table operations run outside transactions
- [ ] All new fields/indexes use IF NOT EXISTS
- [ ] Indexes use CONCURRENTLY (not in a transaction)
- [ ] Down script exactly reverses up script
- [ ] No column defaults to NULL
- [ ] ORM model files are updated accordingly

## Common errors
❌ Index created inside a transaction with CONCURRENTLY → PG error
❌ Down script is a copy of up script → should undo operations
❌ Forgot to sync ORM model → code‑DB drift
❌ Used BIGINT for a field that should be INT UNSIGNED

From an 8‑line V1 to a 50‑plus line V3, each additional line addresses a concrete failure discovered in practice. The iterative process turns a Skill into a reliable, self‑evolving engineering document.

Summary

Skill is structured Prompt Engineering packaged as a folder (instructions, context, tools).

It solves five major pain points: scattered knowledge, repetitive work, inconsistent output, slow onboarding, and knowledge loss.

Progressive loading (Level 1 precise, Level 2 ≤500 lines, Level 3 on‑demand) keeps token cost low.

Skill vs Rule: Rules are always‑on bottom lines; Skills are conditional capabilities.

Six writing techniques – precise description, three‑sentence opening, imperative + reason, before/after diff, few‑shot examples, and explicit edge‑case notes – are distilled from real AI failures.

Prompt lets you use AI. Skill lets you teach AI. The former is tactical; the latter is strategic.

Next time we will explore how to weave your toolchain into a network with MCP, showing how Skills teach AI "what to do" and MCP enables AI to actually "do it".