When you build a new Command Line Interface (CLI), you might observe AI agents like Claude Code repeatedly calling `--help`. This isn't because the agent is confused by the tool; rather, it's re-learning the same command surface for every task due to the absence of a compact guide to kickstart its usage.
This is precisely the problem `SKILL.md` addresses. It doesn't modify your CLI; instead, it provides the agent with a more direct path to the commands it would eventually discover on its own, significantly accelerating the learning process.
What a Skill Is
A "skill" is defined as a folder containing Markdown instructions that Claude Code loads when a request matches a specified set of trigger phrases. For a CLI, a well-structured skill typically consists of three layers:
- Frontmatter: Contains the skill's name, a description with trigger phrases, and a list of allowed tools.
- Body: A focused command guide that the agent reads immediately after the skill is triggered.
- References: Supplemental documentation that the agent can consult if the main `SKILL.md` file doesn't provide enough detail.
Each layer serves a distinct purpose: the frontmatter dictates when the skill activates, the body guides the agent's initial actions, and the references keep the main file concise without sacrificing important details.
Meet pokecli
To provide a tangible and inspectable example, the author developed `pokecli`, a Python CLI specifically for this article. The goal was not to create the most feature-rich CLI, but rather a concrete enough tool to demonstrate the `SKILL.md` pattern from beginning to end.
`pokecli` is designed to query Pokemon, berries, items, and moves, download sprites, and manage a local cache. It features six top-level command groups, predictable output, and a clean structure that maps effectively into a skill's body content.
You can install `pokecli` and its corresponding skill using the following steps:
First, install `pokecli` using `uv`: `uv tool install git+https://github.com/jebucaro/pokecli`
Next, install the bundled skill into the `~/.claude/skills/pokecli` directory by running: `pokecli install --skills`
What `install --skills` Does
The `install --skills` command extracts the skill files, which are shipped as package data within the installed `pokecli` package. This command does not reach out to GitHub or generate new content; instead, it reads the files bundled within the Python wheel and writes them to the appropriate directory on your machine.
In Python, this flow is typically implemented by defining the destination path, such as `~/.claude/skills/pokecli`. It then leverages the `importlib.resources` module to access resource files (e.g., `SKILL.md` and reference files within `pokecli.skills`) bundled inside the package. These contents are subsequently copied to the created destination directories using methods like `Path.write_text`, ensuring directories exist and proper encoding is handled.