SKILL.md in Cursor: Making Team Knowledge Executable

Your team's hard-won conventions usually live in wikis nobody reads or in senior developers' heads. Cursor's support for the SKILL.md standard turns that knowledge into something the AI applies automatically. Here is how to use it.

Every team accumulates knowledge: code style conventions, internal API patterns, deployment runbooks, on-call procedures, domain-specific rules. Traditionally this lives in documentation that sits parallel to the work, consulted only when someone remembers it exists. Cursor's support for the SKILL.md standard changes that by making the knowledge executable, applied automatically by the AI during code generation, edits and reviews.

What a Skill Is

A skill is a folder containing a SKILL.md file. That file has YAML metadata at the top (a name and a description) followed by Markdown instructions explaining what the skill does and when to apply it. Cursor reads installed skills at startup and applies the relevant ones automatically based on what you are working on. No special commands; the patterns just appear in the AI's behaviour.

The Two Skill Locations

Cursor reads skills from two places. User-level skills live in a directory in your home folder and apply across every project. Project-level skills live in a .cursor/skills/ folder within a specific project and apply only there. The recommendation: keep broadly useful skills (language best practices, accessibility patterns) at user level, and keep project-specific or team-specific skills at project level so they can be committed to git.

Writing a Team Skill

A skill's structure is simple. The YAML frontmatter needs a name (lowercase, hyphenated) and a description. The description is the most important part, because it determines when Cursor applies the skill. The Markdown body contains the actual instructions: the patterns to follow, examples of correct usage, and guidelines for edge cases. Keep the body focused; if it grows large, split detailed reference material into separate files the skill points to.

The Git-Based Team Pattern

The highest-value pattern for teams is committing .cursor/skills/ to git. When a new developer clones the repository, they immediately have every shared team skill installed. Updates propagate through normal git pull. Skills become executable institutional knowledge that travels with the codebase and strengthens every time someone adds a new pattern. A junior developer's AI assistant applies the same conventions a senior developer would, from day one.

What Belongs in Team Skills

Four categories deliver the most value. Code style and conventions ensure consistent generated code. Internal API patterns capture how your team makes requests, handles auth, and structures responses. Operational runbooks make new on-call engineers as effective as veterans. Domain knowledge encodes your industry's specific rules and your business logic patterns, the institutional knowledge that takes years to develop and is hardest to transfer. Encoding these as skills turns tribal knowledge into shared, automatic capability.