Frontend · AI Programming · Agent

AI Skills Are Not Prompts: A Markdown File That Gives Your Coding Agent Permanent Memory

By 莪_幻尘 · Jul 29, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

AI coding assistants forget everything between sessions. A Skill turns tribal knowledge and team conventions into a file the agent loads automatically, so every new chat starts with the same professional memory—no re-explaining required. The format is already an ecosystem standard with tens of thousands of installs across Vercel, GitHub, and Sentry's official Skills.

Summary

A Skill is a Markdown file that functions as a persistent professional SOP for AI coding assistants, not a one-off prompt. It defines trigger conditions, executable workflows with explicit input-action-output steps, and three-level constraints (MUST, SHOULD, MUST NOT). A 30-line daily-standup generator pulls git commits, categorizes them, and outputs a structured report. When a Skill exceeds 200 lines, it splits into modules loaded on demand, with a routing hub dispatching to sub-skills by intent.

The same Skill adapts across platforms: Cursor uses .mdc files with glob-based file-type triggering, Claude Code loads CLAUDE.md hierarchically from user to project to subdirectory, GitHub Copilot supports repository-level and path-specific instructions, and AGENTS.md provides universal compatibility across 22 tools. Vercel's writing-guidelines Skill has 32,500 installs; GitHub's create-agentsmd has 11,800.

Trigger precision is the difference between a dead file and a working Skill. Covering three or more user expressions for the same intent lifts hit rates from 40% to over 90%. Examples outweigh descriptions, and the description field is for keyword matching, not documentation.

Takeaways

— An AI Skill is a Markdown file with frontmatter, trigger conditions, executable workflows, output specs, and constraints—not a prompt.

— Trigger conditions in the description field determine whether the Skill loads; covering three or more expressions for the same intent lifts hit rates from 40% to 90%+.

— Every workflow step must specify input, action, and output explicitly; vague instructions like "analyze the code" produce unreliable results.

— Constraints use three levels: MUST (iron law), SHOULD (strong recommendation), and MUST NOT (absolute prohibition). Overusing MUST creates conflicts the AI resolves arbitrarily.

— One Skill does one thing. If the description contains the word "and," split it.

— A single precise example carries more information than ten lines of text description. Include one happy path and one edge case.

— Skills exceeding 200 lines should split into a SKILL.md entry file (index and routing only, under 300 lines) and modules/ loaded on demand.

— Variable configuration belongs in config/, separated from logic. A manifest.json enables automated version detection.

— Cursor uses .mdc files with glob patterns to trigger Skills only when editing matching file types.

— Claude Code loads CLAUDE.md hierarchically but explicitly warns that contradictory rules may be resolved arbitrarily—avoiding conflicts matters more than relying on priority.

— AGENTS.md is natively compatible with 22+ AI coding tools and used by over 60,000 open-source projects.

— skills.sh functions as an npm registry for Skills; Vercel's writing-guidelines has 32,500 installs, and convex-create-component has 89,000.

Conclusions

Skill adoption numbers (32,500 for Vercel's writing-guidelines, 89,000 for convex-create-component) suggest AI Skill registries are becoming infrastructure, not experiments.

The three-tier constraint system (MUST/SHOULD/MUST NOT) mirrors RFC-style specification language, but applied to AI behavior—a formalization that didn't exist in prompt engineering a year ago.

Claude Code's explicit warning that contradictory rules get resolved arbitrarily undercuts any assumption that deeper directory rules override shallower ones. The real safeguard is avoiding contradictions, not layering.

The 200-line split threshold and 300-line entry cap are driven by context-window economics, not organizational preference. Every line in the entry file competes for token budget with the actual task.

Trigger-condition design is the single point of failure: a Skill with perfect workflows but weak description keywords is invisible to the AI. The description field is a matching engine, not documentation.

Concepts & terms

AI Skill

A persistent Markdown file that defines when an AI coding assistant should activate, what workflow to follow, and what constraints to obey. Unlike a one-off prompt, a Skill loads automatically in every relevant conversation.

SKILL.md

The canonical entry file for an AI Skill, containing frontmatter metadata, trigger conditions, executable workflows, output specifications, and constraints. The only file automatically loaded by AI tools.

Glob triggering

Cursor's mechanism for activating Skills only when editing files matching a pattern (e.g., `src/**/*.tsx`). Enables file-type-specific rules without manual toggling.

AGENTS.md

A universal Skill format natively compatible with 22+ AI coding tools including Cursor, Windsurf, Devin, and GitHub Copilot. Used by over 60,000 open-source projects as a project-level instruction file.

MUST / SHOULD / MUST NOT

A three-level constraint system borrowed from RFC specification language. MUST rules are non-negotiable, SHOULD rules are strong recommendations with allowed exceptions, and MUST NOT rules are absolute prohibitions.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗