AI Skills for Log Analysis: How I Structured a Reproducible Diagnosis

Analyzing logs with an AI assistant works better when the assistant follows a procedure rather than improvising. I gathered my instructions in ia-tools: a collection of skills and agents, in Spanish, for Claude Code, Codex and other harnesses compatible with the open Agent Skills standard.

This article explains how they're designed, why I split them this way and what limits they have.

The Problem

Pasting a stack trace into a chat and asking "what's failing?" gives uneven results:

• The assistant assumes technology and version without asking.
• Each answer has a different format, hard to compare or move into a ticket.
• Sensitive data (tokens, credentials, personal data) slips through without anyone flagging it.
• Diagnosis happens without knowing the environment (production or development, server role, version).

A useful diagnosis always follows the same steps. If the steps are always the same, they can be written once.

What a Skill Is

A skill is a folder with a SKILL.md file: instructions the model loads automatically when the conversation matches its description, or that you invoke manually with /name. Long reference material lives in references/ and is loaded only when needed.

That on-demand loading is the most important design decision: don't put everything in the context. A single giant skill with rules for twenty technologies would consume context and dilute the instructions.

How It's Organized

One main skill and several technology-specific ones:

• log-analyzer: detects the log's technology from its patterns, requests the context it can't infer and produces a standardized diagnosis.
• Skills by technical family: cloud (Azure, AWS, GCP), databases (PostgreSQL, Oracle, SQL Server), Docker, .NET, Kafka, Kubernetes and OpenShift, Laravel, PHP, Spring Boot, Quarkus, web servers, Windows Event Log, MinIO, IBM API Connect and SRE alerts.

The main one decides which reference to load. That way the assistant brings into context only what's relevant for that log.

The Diagnosis Flow

1. Detect the technology from the log's own patterns.
2. Ask for what it can't infer: environment, version, server role. Diagnosing without that context leads to confident and wrong conclusions.
3. Analyze using the references specific to that technology.
4. Deliver a report with a fixed structure, so it's comparable across incidents and easy to attach to a ticket.

A Deliberate Decision: Flag, Don't Hide

The skills do not censor credentials, tokens or personal data that appear in the log. They flag them in red in the report.

The reason is practical: if the log contains a secret, what you need is to rotate it, and for that you have to know it's there. Silently hiding it leaves you with a false sense of security. The cost is that the report may contain sensitive data, so you must review it before sharing.

A complementary rule: don't paste production logs into external tools without your organization's authorization.

Agents: A Different Piece

In addition to the skills, the repository includes four agents for Claude Code (independent roles with their own instructions):

• Drafting corporate communications.
• Turning notes or transcripts into meeting minutes.
• Extracting actionable decisions, tasks and risks.
• Translation, proofreading and tone adjustment.

They are generic templates written for Spanish-speaking teams; the idea is that you adapt them to your organization.

Installation

In Claude Code, as a plugin:

/plugin install ia-tools --marketplace ifirestone/ia-tools

For Codex and other compatible harnesses, the repository includes a script that links each skill into your skills directory:

./scripts/link-skills.sh

Since they are symbolic links to the repository, a git pull keeps everything up to date. Keep in mind that the script replaces existing folders with the same skill name, so review it first if you have skills of your own.

ChatGPT has no native mechanism for loading skills: you can paste the content of a SKILL.md as the instructions of a Project or custom GPT and upload the references as knowledge files.

Limits to Keep Clear

• A diagnosis is a hypothesis, not a verdict. The assistant can be wrong, especially with partial logs or without context. Verify before acting.
• Quality depends on the log you give it. A fragment without the root error line produces weak conclusions.
• Maintenance. Technologies change versions and error messages; the references must be kept up to date.
• Data sensitivity. Flagging is not protecting. The responsibility of not exposing information is still yours.

What I Learned Designing It

• A fixed procedure is worth more than a clever prompt. Consistency is what makes the diagnosis useful.
• Asking before diagnosing prevents most falsely confident answers.
• Splitting by technology keeps the context small and the instructions precise.
• Writing in the team's language reduces friction when the report is read by operations or support people.

Conclusion

Skills turn a good diagnostic practice into something repeatable and shareable. They don't replace the engineer's judgment; they save the mechanical work of the first analysis.

The repository is open source (MIT). If you add a skill for another technology, the contribution guide explains the structure.