Introduction

Skills are used to automate repetitive work. In other words, if there is a task you perform daily, weekly, or whenever some "trigger" happens, it can probably be automated using a Skill.

Some examples of repetitive work:

• Writing commits.
• Writing comments about what was developed in a task.
• Bumping a tag version, from 1.0.1 to 1.1.0, for example.
• Creating an ADR.
• Writing release notes for a version launch.

Beyond automating, a Skill can help standardize much of this work. Take writing an ADR as an example: it is a document that, following best practices, works better when standardized.

That way, a Skill can help ensure the standard is followed by everyone on the team, and across different chats as well, since each chat has its own context.

How to create

A Skill can be created inside the .claude/skills/[skill-name]/SKILL.md directory. The Skill name comes from the directory name.

The SKILL.md file is where the instructions passed to the skill live.

How to use

A skill can be used automatically when the AI understands that a Skill exists to do a specific job.

It can also be invoked directly from the prompt, with something like Use Skill X to do Y, or called directly with the command Use the skill /skill-name.

Best practices

Name and description

A Skill is written as a markdown file, but the first lines must include at least two settings: name and description.

Like this:

name: [skill-name]
description: [skill-description]

The name should match the directory name.

The description is useful and important so the AI understands what the Skill does. With a better understanding, the AI can invoke it whenever it finds it necessary.

A good practice is to state in the description when the AI should use it, something like:

• Use when you need to review the code
• Use when you need to write a commit message
• Use to check the authentication module

There is no need to write a long text, but it is ideal to describe clearly what the Skill does and when it should be used.

Instructions

Write the instructions for what needs to be done with a clear and concise description. Ideally, this file should not get too large — up to 300 lines is a good target.

Separate topics with markdown headings and subheadings. This makes the instructions easier to read and better organized within the file.

Use bullet points. Artificial intelligence models prefer reading lists with direct instructions over long texts that require interpreting what needs to be done.

Disable model invocation

By default, every Skill in the project can be called directly by the AI while it is working. However, it is possible to disable this behavior and prevent the model from calling it.

That way, the Skill can only be invoked manually from the terminal.

This setting is configured in the skill's configuration block by setting the disable-model-invocation key to true.

Argument Hint

You can define arguments that can be passed to help the Skill run.

This definition is also made in the skill's configuration block, using the argument-hint key with the desired argument, for example: argument-hint: <branch-or-path>, argument-hint: <adr-name>

Define the output

This is the best setting for standardizing what gets returned.

Going back to the ADR example, if you want the Skill to always return or create the ADR with the same set of information, the ideal approach is to tell the Skill what is expected in the output, for example:

## Output

Always use this structure to output data

- Title:
- Date:
- Status: Accept/Suspend/Reject
- Context:
- Decision:

With that, every time the Skill runs, it will return exactly this data.

Define what should not be done

Defining what not to do is just as important as defining what to do, because it ensures the AI will not "hallucinate" and do something that was not asked for.

Use the same pattern of separating with markdown and adding bullet lists, to keep the file consistent and easier to read.

Incremental improvement

The idea is that skills help with daily work by removing repetitive tasks. For a skill to remain useful, the ideal approach is to review the work it delivers and improve its documentation of what to do, what not to do, and add more examples.

Over time and across tasks, the Skill will become more and more complete and accurate.

Complete Skill example

---
name: create-adr
description: Creates a standardized ADR (Architecture Decision Record) from a technical decision made by the team. Use when the user asks to record, document, or formalize an architecture decision, when they mention "ADR", "technical decision" or "decision record", and also when a relevant choice of technology, pattern, or tool is settled during the conversation.
argument-hint: <decision-title>
---

## Context

ADRs record relevant architecture decisions and the reasoning behind them.
The goal is that anyone joining the project later understands **why**
the decision was made, not just **what** the decision was.

Existing ADRs live in `docs/adr/`.

## Task

Write an ADR about the decision given in `$ARGUMENTS`.

- Read the existing ADRs in `docs/adr/` to follow the same style and numbering.
- Number the new file in sequence: `docs/adr/NNNN-title-in-kebab-case.md`.
- Gather context from the current conversation, the project files, and the Git history.
- Record at least one alternative that was considered and rejected.
- Describe the consequences of the decision, both positive and negative.
- If essential information is missing (reasoning, alternatives, owner), ask
  before writing instead of assuming.

## Status

- **Accepted** — decision in effect
- **Proposed** — under discussion, not in effect yet
- **Superseded** — replaced by another ADR (cite which one)
- **Deprecated** — no longer in effect and not replaced

## Output

Always use this structure, in this order:

# NNNN - <decision title>

- **Date:** YYYY-MM-DD
- **Status:** Accepted | Proposed | Superseded | Deprecated
- **Owners:** <names or team>

## Context

What problem led to this decision. Two or three paragraphs, at most.

## Decision

What was decided, in one direct sentence, in the present tense.

## Alternatives considered

- **<alternative>** — why it was rejected.

## Consequences

- **Positive:** what improves.
- **Negative:** the accepted cost, technical debt, or limitations.

## What not to do

- Do not change existing ADRs; to reverse a decision, create a new ADR
  with status **Superseded** pointing to the previous one.
- Do not invent alternatives, benchmarks, or numbers that are not in the
  conversation or in the project.
- Do not describe implementation, step-by-step guides, or code — an ADR records
  a decision, not a tutorial.
- Do not write an ADR for trivial and reversible decisions, such as code
  formatting or variable naming.
- Do not leave the consequences section with only positive points.

Conclusion

Skills help a lot with day-to-day work, assisting with repetitive tasks, maintaining writing standards, code standards, repository checks, and many other jobs that can be automated.

If you have any suggestions to improve this article, feel free to reach out to me on LinkedIn :)