29 May 2026
Claude Skill Structure
What's the best way to change your workflow for AI?
Perhaps it's not your workflow you need to change. Maybe it's how you design software, code it, or even how you think about it?
Eager to be the first to the party, I see devs bending over backwards to accommodate AI in their daily work.
But they're forgetting a long-standing goal of AI, which is to be indistinguishable from a human.
There's talk that modern LLMs (like Claude) may be close to truly passing the Turing Test. So in a sense, they're getting remarkably good at being human-like.
This convinces me that a future-proof strategy for working with AI tools like Claude Code is to guide and teach it as if it were human.
The principle is, if you wouldn't do it for another dev, don't do it for AI.
How to teach AI is part of a bigger theme I'll be exploring in future, but for now let's focus on skills.
Have a procedure you want to automate? A skill would be a great way to do that. Claude skills contain some context, but most importantly, they detail how to do something.
But not all skills are created equal. I don't know about you, but if I'm trusting another dev (or AI) to do something for me, I want to be confident it will be done correctly. Using a skill doesn't guarantee a correct result, so how do we improve our chances?
This reminded me of a time before AI. Back when I was a junior dev, I worked in a team of mostly seniors. So naturally, I got stuck with the tedious, repetitive jobs.
The grunt work.
One job was hand-configuring VMs for our prod environment (this was a long time ago). I was given a fresh machine and had to make it into one of the security-hardened targets we could deploy our apps to.
To do this I was given an incredibly detailed, step-by-step set of instructions on how to configure each VM. It was a super effective way to make the process repeatable for someone who had no idea how to do it.
And when I gave the configured VM back to the seniors? They would run through a checklist to make sure I'd done my job correctly.
It pays to have a structured way to make a process repeatable for another human. Given that a goal of AI is to be indistinguishable from a human, I think the same structured way can work for Claude too.
Here's my framework for creating skills:
- Context - The bare minimum information needed to perform the process.
- Process - The steps to complete, in the order they should be completed.
- Checklist - How you know the process is complete.
Here's an example which you can create in .claude/skills/configure-checkstyle/SKILL.md:
---
name: devtiro-checkstyle-configure
description: Use this skill when asked to configure CheckStyle on a project which uses Apache Maven.
---
# Configure Checkstyle
Read the entire file before continuing. Perform the steps in order and then
complete the verification.
## Context
### What is Checkstyle?
Checkstyle is a tool for checking that a Java project adheres to a specific
style guide.
It comes in two parts: The Checkstyle tool and the Apache Maven plugin we use
to run it. Both have independent lifecycles, so we pin each version independently.
### Which Style Guide?
We use the Google style guide. This style guide is built into Checkstyle.
### Fixing violations
When Checkstyle reports violations, fix them in the source code. Do not add
suppressions to `checkstyle-suppressions.xml` to make the build pass.
Suppressions exist only for genuine false positives or for code that cannot be
changed (e.g. generated sources). Common violations and their fixes:
- `PackageName` — package name contains an underscore or uppercase letter;
rename the package directory and update the `package` declaration.
- `MissingJavadocType` — class has no Javadoc comment; add one above the class.
- `MissingJavadocMethod` — public method has no Javadoc comment; add one above
the method.
## Process
Copy this checklist and track your progress:
- [ ] Step 1: Check the Project
- [ ] Step 2: Add Maven Properties
- [ ] Step 3: Add Plugin Declaration
- [ ] Step 4: Add Checkstyle Suppressions
- [ ] Step 5: Run Checkstyle
### Step 1: Check the Project
Check the project is an Apache Maven project. It should have a valid `pom.xml`
file. If it does not inform the user and do not continue.
If the project is a valid Apache Maven project, then check that checkstyle is
not already configured. If it is then inform the user and do not continue.
### Step 2: Add Maven Properties
Add the following properties to the `<properties>` section of `pom.xml`:
```xml
<checkstyle.version>11.0.1</checkstyle.version>
<maven-checkstyle-plugin.version>3.6.0</maven-checkstyle-plugin.version>
```
### Step 3: Add Plugin Declaration
Add the following plugin declaration to the `plugins` node in the project's
`pom.xml` file:
```xml
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>${maven-checkstyle-plugin.version}</version>
<dependencies>
<dependency>
<groupId>com.puppycrawl.tools</groupId>
<artifactId>checkstyle</artifactId>
<version>${checkstyle.version}</version>
</dependency>
</dependencies>
<configuration>
<configLocation>google_checks.xml</configLocation>
<excludeGeneratedSources>true</excludeGeneratedSources>
<consoleOutput>true</consoleOutput>
<failsOnError>true</failsOnError>
<failOnViolation>true</failOnViolation>
<violationSeverity>warning</violationSeverity>
<linkXRef>false</linkXRef>
<includeTestSourceDirectory>false</includeTestSourceDirectory>
</configuration>
<executions>
<execution>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
</plugin>
```
### Step 4: Add Checkstyle Suppressions
Create a new file in the root of the project named `checkstyle-suppressions.xml`
with the following content:
```xml
<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
"-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
"https://checkstyle.org/dtds/suppressions_1_2.dtd">
<suppressions>
</suppressions>
```
### Step 5: Run Checkstyle
Run checkstyle with `mvn checkstyle:checkstyle`.
Note, you may have to use the Apache Maven wrapper if `mvn` is not available
on the classpath.
On Windows:
```shell
.\mvnw.cmd checkstyle:checkstyle
```
On Linux and MacOS:
```shell
./mvnw checkstyle:checkstyle
```
If violations are reported, fix them in the source code — do not add entries
to `checkstyle-suppressions.xml`. Read the violation message carefully: it
includes the file, line number, and rule name. Refer to the Context section
above for fixes to the most common rules. Once all violations are fixed,
re-run to confirm the build reports 0 violations.
## Verification
Copy and complete the following checklist. You **must** perform each check again
ignoring previous checks in your context. This follow-up check is very important.
- [ ] Property `checkstyle.version` is `11.0.1` in `pom.xml`.
- [ ] Property `maven-checkstyle-plugin.version` is `3.6.0` in `pom.xml`.
- [ ] Specified Checkstyle plugin declaration exists in `pom.xml`.
- [ ] File `checkstyle-suppressions.xml` exists in the root of the project with
the specified contents.
- [ ] Checkstyle runs successfully with 0 violations.This is a framework I use for myself, even today. I'm pleased it's also working wonderfully with Claude.
The next time you find yourself repeating a process, try writing it as a skill using this framework.
