Skip to content

Agent Skills Quickstart: pre-built vs SKILL.md in 3 minutes

Target Audience

  • Claude Code beginners who feel lost about Agent Skills
  • People unsure about pre-built vs SKILL.md
  • Teams looking for the smallest practical use cases

Short answer: pre-built skills and SKILL.md are different things. This page is a 3-minute map to decide what to use and when.

Conclusion: pre-built and SKILL.md are different

TypeRoleExamplePositioning
pre-built skillsBuilt-in capabilities provided by the vendorPowerPoint / Excel / Word / PDFClaude API-side capabilities
SKILL.md (custom)Your team’s procedures and review criteriaRelease checks / Incident triageOpen standard skill format

Think of pre-built as tools, and SKILL.md as procedural playbooks.

30-second decision map

Which one should you use?

  • Need to edit pptx/xlsx/docx/pdf → pre-built skills (API capabilities)
  • Need to standardize team procedures → SKILL.md (custom skills)
  • Rules that must always apply → Custom Instructions (always-on)

Activation is not keyword matching

Agent Skills load only the name/description at startup and read SKILL.md when relevant. So it is not a simple “keyword matches = always trigger” rule. The description should say when to use it.

Keep the first skill short and fixed

Start simple. A short procedure plus a fixed output format works best early on.

  • One skill, one purpose (review / triage / checklist)
  • Fixed output format (Summary / Risks / Next Actions)
  • Description includes “when to use it”

Minimal team use cases that actually work

1) Release procedure standardization

  • Before: Paste long steps every time
  • After: “Please run the release-check skill”

2) Incident triage

  • Inputs: Logs, metrics, recent changes
  • Output: Suspected causes / impact / next actions

3) Terraform plan review

  • Before: Review quality depends on reviewer
  • After: Fixed checks for IAM / Network / destructive changes

Smallest SKILL.md (8 lines)

Minimal skeleton (8 lines)
---
name: release-check
description: Standardize pre-release checks. Use for deploy, release, rollback.
---
# Steps
1. Confirm impact scope
2. Confirm rollback plan
3. Confirm monitoring metrics

Common misconceptions

  • pre-built = SKILL.md? → No. Pre-built is API-side capabilities, SKILL.md is your custom procedure package.
  • Claude creates skills automatically? → Not automatic. It means Claude can draft SKILL.md if you ask.
  • Is it popular/mainstream? → No official usage stats are published. Start small and validate.

References