Skip to main content
A skill is a directory containing at minimum a SKILL.md file. That file tells an AI agent what the skill does, when to use it, and how to invoke it.

​
Anatomy of a skill

github-skill/
  SKILL.md          # Description, triggers, usage instructions
  run.sh            # Optional: script the agent can execute
  config.json       # Optional: structured metadata
  templates/        # Optional: any supporting files

​
SKILL.md

The only required file. Written in plain markdown. Contains:
  • What the skill does (a short description)
  • When to use it (trigger phrases or conditions)
  • How to invoke it (commands, arguments, examples)
The agent reads this file and decides whether and how to use the skill based on the current conversation. 
# GitHub Skill

Interact with GitHub repositories using the `gh` CLI.

## When to use

When the user asks about PRs, issues, CI status,
or any GitHub repository operation.

## Commands

- `gh pr list` — list open pull requests
- `gh issue create --title "..." --body "..."` — create an issue
- `gh run list` — check CI status

​
Scripts (optional)

If a skill needs to run code, it includes an executable. Any language works — shell, Python, Node, Go binary. The contract is simple:
  • Input: command-line arguments and/or stdin
  • Output: stdout (text the agent reads back)
  • Errors: stderr and non-zero exit codes
No HTTP. No JSON-RPC. No WebSockets.

​
Skills vs MCP servers

SCP SkillMCP Server
What you shipA directory with markdown + scriptsA running process with JSON-RPC
RuntimeNone (agent reads files, runs CLIs)Long-running server process
ProtocolFilesystem + stdin/stdoutJSON-RPC 2.0 over stdio or HTTP
DiscoveryAgent reads SKILL.mdClient calls tools/list
DependenciesWhatever your script needsSDK + transport + lifecycle
InstallationCopy a folderConfigure + start a server

​
Design principles

  1. Files over protocols — A skill is data the agent reads, not a service it connects to.
  2. CLI over RPC — When code needs to run, use standard Unix conventions.
  3. Markdown over schemas — Natural language descriptions are what LLMs understand best.
  4. Simple over complete — Cover the 90% case. Don’t build abstractions for edge cases.