Blog 5 of N: Agent Skills Changed How I Use Claude Code - Here's the Open Standard Behind It
What if your AI agent could learn a procedure once and remember it forever? Not facts - it already knows plenty of those. But the step-by-step, context-specific processes that make your team's work actually work. That is what agent skills do. And the format is simpler than you think.
What Are Agent Skills?
If you have used any AI coding tool recently - Claude Code, Cursor, GitHub Copilot, or similar - you have probably noticed something. These tools are impressive reasoners. They can explain complex code, debug tricky issues, and generate entire applications from a description. The underlying large language models already know a massive amount of facts. Ask one about microservice architecture, the history of relational databases, or how HTTP works - you will get a solid, confident answer.
But there is a specific kind of knowledge they lack. And that gap is exactly what skills were created to fill.
The Missing Piece: Procedural Knowledge
Let's say your company has a weekly status report that every team member submits. It is not just any report - your team has a specific way of doing it:
- Start with completed items, listed as bullet points
- Then blockers - each one must have a severity rating (low, medium, high) and who owns the resolution
- Anything overdue by more than 2 days gets a risk flag
- Then next week's planned items
- Always end with a "Needs from Leadership" section, even if empty
- Bullet points only, no paragraphs, no filler
Six rules. Specific order. Specific formatting.
Now open any AI tool and say: "Write my weekly status report."
You will get a perfectly reasonable, generic template. It will have sections for accomplishments and goals. It might even look professional. But it will miss your team's specific rules. No severity ratings on blockers. No risk flags. No mandatory leadership section. Because the AI has never seen your team's process.
This is the difference between two types of knowledge:
- Factual knowledge - What things are. "A status report summarizes work done and work planned." The AI already knows this.
- Procedural knowledge - How things get done in a specific context. "Our team's status report follows these 6 rules in this order." The AI does not know this.
LLMs ship with enormous factual knowledge. They can tell you what a status report is, what a code review is, what an incident report is. But they do not know your process for writing one. They do not know the 15-step onboarding procedure for new developers at your company. They do not know the exact sequence of checks your team runs before deploying to production.
That kind of knowledge - step-by-step, context-specific, "here is how we actually do this" - is procedural knowledge. And without it, the AI has only two options when it encounters a task like this:
- You tell it every single step, every single time. All 6 rules, every Monday morning. Hope you remember them all. Hope your colleague remembers them too.
- It takes its best guess. Which will look plausible but miss half your team's requirements.
Neither is great. And this is the problem skills were designed to solve.
A skill is how you give an AI agent procedural knowledge - the step-by-step, context-specific instructions for how to do a particular job.
What Does a Skill Look Like?
The format is remarkably simple. A skill is a folder containing a file called SKILL.md. That is the minimum. A folder and a Markdown file.
.claude/
└── skills/
└── weekly-status/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: additional documentation
└── assets/ # Optional: templates, data filesOnly the SKILL.md file is required. The three subdirectories - scripts/, references/, and assets/ - are optional. Most skills do not need them. We will talk about what they do later, but for now, just know that a skill can be as simple as a single Markdown file in a folder.
Inside the SKILL.md
The file has two parts: a small header at the top, and the instructions below it.
The header (called frontmatter) is a few lines of metadata wrapped between --- markers. It has two mandatory fields:
---
name: weekly-status
description: >
Writes the team's weekly status report in the standard format.
Use when the user asks to write, draft, or prepare a status
report, weekly update, or weekly summary.
---
| Field | What it does |
name | Identifies the skill. Lowercase letters, numbers, and hyphens only, max 64 characters. Must match the folder name. Cannot start or end with a hyphen |
description | Tells the agent what this skill does and when to use it. This is the most important line in the entire file - more on why in a moment |
There are also optional fields you can add:
| Field | What it does |
license | License for sharing (e.g., "Apache-2.0") |
compatibility | Environment requirements (e.g., "Requires Python 3.12+") |
metadata | Key-value pairs for things like author name and version number |
allowed-tools | Pre-approved tools the skill may use (experimental) |
Tools like Claude Code also extend the standard with additional frontmatter fields - for example, disable-model-invocation (only the user can trigger the skill, preventing the agent from auto-activating it), context: fork (run the skill in an isolated subagent), and more. These are tool-specific extensions. The core format - name, description, and body - works everywhere.
The body is everything below the header. It is written in plain Markdown - no special syntax, no programming language, just text. This is where the actual instructions live. Step-by-step procedures, rules, examples of good and bad output, edge cases, anything the agent needs to know to do the job correctly.
There are no restrictions on how you structure the body. Write it however makes the procedure clearest. The agent will read it like a document and follow along.
That is the entire format. A header that says "here is what I am and when to use me" and a body that says "here is how to do it." If you can write a checklist in a text file, you can write a skill.
Why the Description Matters So Much
The description field controls when the skill activates. The agent does not read the full instructions upfront - it reads only the name and description. Later, when you ask it to do something, it compares your request against all the skill descriptions and loads the matching one. This matching happens through the AI's own reasoning - not keyword matching, but genuine understanding of intent.
This is why a specific description matters:
- Good: "Writes the team's weekly status report in the standard format. Use when the user asks to write, draft, or prepare a status report, weekly update, or weekly summary."
- Bad: "Helps with reports."
The good description has trigger words that match how people naturally ask for this task. The bad one is so vague the agent might never activate it. Think of it like labeling a recipe card - "Grandma's Dal" is useful, "food" is not.
The Optional Folders
Most skills only need the SKILL.md file. But for complex procedures, the three optional directories add capabilities:
| Directory | What it holds | When it loads |
scripts/ | Executable code (Python, Bash, JavaScript) | When the agent decides to run it |
references/ | Additional documentation, guides, specs | When the agent needs more context |
assets/ | Templates, sample files, data | When a step references them |
The key thing: these folders do not load when the skill activates. They load only when the agent reaches a step that needs them. This is part of a larger loading strategy we need to talk about next.
The Context Pollution Problem
Here is a question that comes up naturally: what if you have a lot of skills?
Maybe your team has a skill for writing status reports, another for meeting notes, one for incident reports, one for onboarding new team members, one for code reviews, one for release notes, one for sprint retrospectives. That is seven skills. A large organization might have dozens. Some teams have over a hundred.
If the agent loaded all of those skills - every instruction, every reference file, every template - into memory at startup, it would use up most of its context window before anyone even asked a question. The context window is the amount of text an AI model can hold in its working memory at one time. Fill it up with skill instructions you are not using, and there is less room for the actual conversation. This is called context pollution - irrelevant information crowding out the information you actually need.
This is also why you cannot just put all your procedures into a single instructions file like CLAUDE.md. If you stuffed your status report procedure, your meeting notes procedure, your incident report template, your onboarding checklist, and your deployment runbook all into oneCLAUDE.md file, it would be thousands of lines long. And it would load into context on every single session - even when you are just fixing a typo in a README and none of those procedures are relevant.
Skills solve this with a loading strategy called progressive disclosure.
Progressive Disclosure: Load Only What You Need
Progressive disclosure works in three tiers. Each tier loads more information, but only when it is actually needed.
Tier 1 - Just the labels (at startup)
When the agent starts, it loads only the name and description from every installed skill. That is roughly a sentence or two per skill - maybe 50 words each. Even if you have 200 skills installed, the total overhead at startup is a few thousand words. That is a tiny fraction of modern context windows, which can hold tens of thousands of words.
Tier 2 - The full instructions (when the task matches)
When you ask the agent to do something that matches a skill's description, the agent pulls the full SKILL.md body into its context. Now it has the complete step-by-step procedure. The specification recommends keeping the body under 500 lines so that this loading remains efficient.
The matching itself happens through the AI's own reasoning. You do not need to use exact keywords - the model understands intent. If you say "prepare my weekly update" and the skill description mentions "weekly status report," the model recognizes these are the same thing.
Tier 3 - Supporting resources (only at the point of need)
Files in scripts/, references/, and assets/ load only when the agent reaches a step that specifically needs them. If step 5 of a procedure says "use the template in assets/report-template.md," that template loads when the agent gets to step 5 - not when the skill activates, and certainly not at startup.
The result: an agent starts each session with a lightweight index of everything it knows how to do. It pulls in detailed instructions only when you ask for something relevant. And it grabs supporting resources only at the moment a specific step requires them. Most of the time, most of your skills take up almost zero space in the agent's working memory.
This is why skills scale in a way that instruction files cannot.CLAUDE.md ,rules.md, and similar project-level files are always loaded, always taking up context. Skills are loaded on demand, taking up context only when they are being used.
Skills vs. Other Ways of Teaching Agents
Skills are not the only way to give an AI agent additional knowledge. If you have used AI coding tools, you have probably encountered other approaches. They all serve different purposes.
Instruction Files (CLAUDE.md,rules.md,.cursorrules) are project-level rules that load at startup and stay in context the entire session. Good for broad conventions like "always use TypeScript strict mode" or "never commit .env files." But if you stuff every procedure in there - status reports, meeting notes, incident templates, deployment checklists - it becomes thousands of lines that load every session, even when you are just renaming a variable. Think of it as a poster on the wall: good for a few important rules, bad for a filing cabinet of procedures.
Agent Definitions (.claude/agents/, agents.md) define specialized personas - a code reviewer, a security auditor, a technical writer. They set who the agent is and what role it plays. But they do not teach how to do a specific task. A security auditor agent still needs your organization's specific review checklist. Think of it as a job title: it tells you someone is an accountant, but not how your company's month-end close works.
Skills (.claude/skills/,SKILL.md) define how to do a specific task. They load only when the task matches, and you can have hundreds without context pollution. Think of it as a recipe card: you have a whole box of them, but you only pull out the one you need right now.
| Instruction Files | Agent Definitions | Skills | |
| Answers the question | "How should we work in this project?" | "What role does this agent play?" | "How do I do this specific task?" |
| Loaded when | Every session, always | When the role is activated | Only when the task matches |
| Scales to | A few rules per project | A handful of roles | Hundreds of procedures |
| Knowledge type | Conventions and preferences | Identity and behavior | Procedures and workflows |
| Portable across tools | No (format varies by tool) | No (format varies by tool) | Yes (open standard, 35+ tools) |
These three are not competing - they are layers. Instruction files set the project rules. Agent definitions set the role. Skills provide the step-by-step procedures. A well-configured agent might use all three at the same time.
How This Maps to Human Memory
There is a parallel from cognitive science that makes this entire concept easy to remember.
Humans have three distinct types of memory:
- Semantic memory - Facts you know. "Delhi is the capital of India." You do not remember when or where you learned this - you just know it.
- Episodic memory - Experiences you remember. "When I visited Delhi last June, it was 45 degrees and I learned to never schedule outdoor meetings after noon." This is tied to a specific time and place.
- Procedural memory - Things you know how to do. "How to navigate the Delhi Metro during rush hour." You do not think through which line to take, where to switch, or which side of the platform to stand on - you just do it. The procedure is internalized.
AI agent architectures are starting to mirror exactly this:
| Your Memory | Agent's Equivalent | How It Works |
| Semantic (facts you know) | RAG and knowledge bases | The agent retrieves facts from a document store. "What is our refund policy?" - it looks it up |
| Episodic (experiences you remember) | Conversation history and logs | "What did we discuss yesterday?" - the agent recalls prior interactions |
| Procedural (things you know how to do) | Skill files | "Write my status report" - the agent follows your team's specific process |
This maps cleanly onto the different ways of giving agents knowledge:
- RAG (Retrieval Augmented Generation) is the agent's reference library. It retrieves facts from documents at runtime - policies, specifications, product details. But a library does not teach you a procedure. You can read every book about cycling and still not know how to ride a bike.
- MCP (Model Context Protocol) gives the agent access to tools - like handing someone a bicycle. But having a bicycle does not mean you know how to ride it, when to shift gears, or which route to take to work. MCP provides the tool. A skill tells the agent when to use it and how.
- Fine-tuning is like surgically rewiring your muscles and balance so cycling becomes instinct. Powerful, but expensive - and if you want to learn mountain biking next, you have to redo the whole thing.
- Skills are the riding lessons. Step by step: how to balance, when to brake, how to shift gears on a hill. Written down, easy to update, and you can hand the same instructions to anyone.
In practice they all work together. A skill provides the playbook - "first do this, then check that, then format the result like so." MCP provides the connections. RAG provides the reference material. The skill is the glue that orchestrates when to reach for what, and what to do with the results.
An Open Standard
One more thing that sets skills apart from instruction files likeCLAUDE.md or .cursorrules: portability.
CLAUDE.md only works in Claude Code..cursorrules only works in Cursor. Each tool has its own format, and they are not interchangeable. Skills follow an open standard published at agentskills.io, originally developed by Anthropic under the Apache 2.0 license. It has been adopted by over 35 platforms including Claude Code, OpenAI Codex, GitHub Copilot, VS Code, Cursor, Gemini CLI, JetBrains Junie, Databricks Genie Code, Snowflake Cortex Code, Spring AI, Kiro, and many more.
A skill you write for Claude Code works on any platform that supports the spec. Your team member who prefers Cursor or GitHub Copilot can use the exact same skill from the same Git repository. Write once, use everywhere.
A Word on Trust
Skills can include executable scripts in the scripts/ directory. That makes them powerful - but executable code means trust matters. When an agent runs a script from a skill, it runs with your permissions on your machine.
Treat skill installation like any software dependency: read the SKILL.md before installing, check the scripts/ directory if it exists, and prefer skills from known sources. Skills are human-readable by design, which makes them easier to audit than compiled packages - but "easy to read" is not a reason to skip reading it.
Let's See It in Action
Enough theory. Let's create a real skill and see how it changes the experience.
We will build a weekly-status skill for the status report example we have been discussing throughout this blog.
Create the Skill
Where you store a skill determines who can use it:
| Location | Path | Applies to |
| Enterprise | Managed settings | All users in your organization |
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | All your projects |
| Project | .claude/skills/<skill-name>/SKILL.md | This project only |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | Where plugin is enabled |
When skills share the same name across levels, higher-priority locations win: enterprise > personal > project. For most teams, the two you will use daily are personal (your home directory, available everywhere) and project (committed to Git, shared with the team).
We want the team to share this one, so we will use the project directory. Open a terminal (Terminal on macOS/Linux, Command Prompt or PowerShell on Windows) and navigate to your project's root folder.
macOS / Linux:
mkdir -p .claude/skills/weekly-statusWindows (Command Prompt):
mkdir .claude\skills\weekly-statusThis creates the folder structure .claude/skills/weekly-status/ inside your project. On Windows, mkdir creates parent directories automatically. On macOS/Linux, the -p flag does the same.
Now create a file called SKILL.md inside that folder. You can use any text editor - VS Code, Notepad, TextEdit, vim, whatever you prefer. The file path should be:
- macOS / Linux:
.claude/skills/weekly-status/SKILL.md - Windows:
.claude\skills\weekly-status\SKILL.md
Add this content:
---
name: weekly-status
description: >
Writes the team's weekly status report in the standard format.
Use when the user asks to write, draft, or prepare a status
report, weekly update, or weekly summary.
---
# Weekly Status Report
Write a weekly status report covering Monday to Friday of the
current week.
## Report Structure
Follow this exact structure:
### 1. Completed
- List each completed item as a bullet point
- Start each bullet with a past-tense verb (Finished, Fixed,
Delivered, Migrated, etc.)
- Be specific - include module names, ticket numbers, or
feature names when the user provides them
### 2. Blockers
- Each blocker must include:
- What is blocked
- Severity: [LOW], [MEDIUM], or [HIGH]
- Owner: who needs to resolve it
- If an item is overdue by more than 2 days, add a [RISK] flag
- If there are no blockers, write "None"
### 3. Next Week
- List planned items as bullet points
- Start each bullet with a verb (Start, Continue, Complete,
Review, etc.)
### 4. Needs from Leadership
- Always include this section
- If nothing is needed, write "None at this time"
## Formatting Rules
- Bullet points only. No paragraphs.
- Keep each bullet to one or two lines maximum
- No greetings, no sign-offs, no filler
- Use plain text, no markdown formatting in the output
## Before writing, ask the user:
- What did you work on this week?
- Any blockers or things waiting on someone else?
- What is planned for next week?That is it. The skill is ready.
Use the Skill
Open Claude Code in your project. You have two ways to use it:
Option A - Invoke directly: Type /weekly-status. Claude Code loads the skill and starts the procedure.
Option B - Ask naturally: Type "Write my weekly status report." Claude Code matches your request to the skill description and loads it automatically.
Here is what the interaction looks like:
Notice what the agent did. It did not just fill in a template. It asked for inputs, realized the answers were too brief, and asked follow-up questions to get useful detail - exactly as the skill instructed. Then it applied judgment: it rated the blocker as MEDIUM, linked the dependency between Jira-234 and Jira-345, identified Sam as the owner, and even suggested a leadership follow-up for the unresolved dependency. Every rule in the skill was followed, and the agent reasoned about the specifics of your situation.
The Before and After
| Aspect | Before Skills | After Skills |
| Writing the report | Type a paragraph explaining the format, then your updates | Type /weekly-status and answer three questions |
| Remembering the format | You memorize 6 rules and hope you get them right | The skill remembers them |
| Blocker severity ratings | You remember to add them (sometimes) | Always included |
| Risk flags on overdue items | You calculate this yourself | Flagged automatically |
| "Needs from Leadership" section | Forgotten half the time | Always included |
| Sharing with the team | Send a notes file, hope everyone stays in sync | Commit the skill to Git |
| Updating the format | Edit every copy, notify everyone | Edit one SKILL.md, push to Git |
| Context window impact | If in CLAUDE.md: loaded every session, even when irrelevant | Loaded only when you ask for a status report |
What Else Can You Build?
The weekly-status skill we built uses only aSKILL.md file. But remember the optional folders - scripts/, references/, assets/? That is where things get interesting. Here are some ideas - inspired by real problems teams deal with every day - to show you what becomes possible.
For Developers
pr-summary - Summarize pull requests in SAP language
Across lines of business, PR review latency - not coding - is the dominant bottleneck. Review cycles span days because reviewers have to read every file to understand the scope. This skill changes that.
scripts/runsgit diffand extracts the list of changed files, grouped by type (CDS models, service definitions, UI5 views, config files)references/contains your team's PR description standards and SAP-specific terminology guide (what a CDS annotation change means, what an OData projection change implies)SKILL.mdinstructs the agent to summarize the diff in functional terms - not "changed 3 files" but "Adds a new OData entity projection in the CAP CDS model and updates the corresponding Fiori Elements list report configuration." Reviewers grasp the scope in seconds instead of reading every file
cap-scaffold - Scaffold a full-stack CAP + Fiori/UI5 project
Setting up a new CAP project correctly - with CDS data models, OData service definitions, a Fiori/UI5 front-end, XSUAA authentication, CI/CD pipeline, and monitoring - takes days of stitching pieces together. This skill turns it into a conversation.
assets/holds templates: CDS entity definitions, Fiori Elements manifest.json, xs-security.json for XSUAA, GitHub Actions CI/CD workflow, Dockerfilereferences/has SAP's Golden Path architecture guidelines, approved library lists, and naming conventions per LoBSKILL.mdasks what you are building ("a Books catalog with list-detail UI"), then scaffolds the entire project from templates, wires up authentication, sets up the CI pipeline, and generates a README explaining every architectural choice it made
ci-triage - Diagnose CI failures in seconds
When CI pipelines fail, developers spend time sifting through logs only to find it was an environment or config issue, not a code problem. This skill triages failures automatically.
scripts/fetches the CI log output, parses error messages and stack traces, and extracts the failing test or build stepreferences/contains a catalog of common failure patterns your team has seen before (dependency version conflicts, environment drift, flaky tests) with known fixesSKILL.mdreads the parsed output, matches it against known patterns, and produces a diagnosis: "Test failure in OrderService.test.js - NullPointerException: new field OrderDate not initialized in test fixture. Suggested fix: provide default value in test data setup." Root cause and fix, not just a red X
compliance-check - Shift-left security and privacy review
Teams operates under non-negotiable constraints: secure coding standards, GDPR data privacy, export controls, OSS license hygiene. Today, violations are found late - during formal security reviews - creating friction and rework. This skill catches them at the point of coding.
scripts/runs static analysis on the diff - checks for hardcoded credentials, insecure deserialization, weak cryptography, and banned functions. A second script scanspackage.jsonorpom.xmlorpyproject.tomlfor new dependencies and checks them against an allow-list of approved OSS licensesreferences/contains SAP's secure coding rules by category (security, privacy, licensing, architecture) and the current approved license list (MIT, Apache-2.0, BSD)SKILL.mdorchestrates a two-pass review: deterministic checks first (scripts), then contextual AI analysis of data flow patterns the scripts cannot catch - like a function that reads personal data in one module and logs it unmasked in another. Output is a structured compliance summary categorized by severity and type
For Business Users
client-proposal - Draft a client proposal that follows your company's playbook
Every sales team has a format: executive summary first, then pain points, proposed solution, pricing table, case studies, timeline. But when you ask an AI to "write a proposal," you get a generic template that misses your company's structure, tone, and pricing rules. This skill knows your playbook.
assets/holds the proposal template with your standard sections, pricing table format, and case study layoutsreferences/contains your pricing tiers, approved discount thresholds, service descriptions, and a library of past case studies tagged by industry and deal sizeSKILL.mdwalks you through: gather client requirements, select the most relevant case studies from the library, draft each section in your company's tone, fill in the pricing table with the correct tier, and flag if any proposed discount exceeds the threshold that needs manager approval
learning-plan - Personalized weekly study plan for professional development
Your company offers a catalog of courses for upskilling - maybe it is cloud certifications, AI fundamentals, leadership development, or technical role transitions. The courses exist, but employees do not know what to take, in what order, within their available time. This skill turns a sprawling course catalog into a weekly plan that fits your schedule.
scripts/calculates time budgets - splits multi-hour courses into 25-30 minute sessions, sequences them across weeks to respect your weekly hour cap (e.g., 3 hours/week), and flags prerequisitesreferences/has the course catalog with durations, difficulty levels, and prerequisite chains for each learning pathSKILL.mdasks three questions: what you want to learn, what you already know, and how many hours per week you can dedicate. Then it generates a week-by-week learning plan with specific sessions, estimated completion dates, and checkpoints to verify you are retaining what you learned
sales-scheme - Analyze and optimize rebate programs
Sales schemes are shared via PDFs, emails, and circulars. Manual interpretation leads to inconsistent rebate decisions, and there is no visibility into whether a scheme is actually effective. This skill brings structure and data to the process.
scripts/parses scheme documents (discounts, slabs, conditions), links them with sales data, and calculates which customers are close to achieving the next slab thresholdreferences/contains the current scheme rules, historical performance data, and the rebate calculation logicassets/has the recommendation report template with sections for current performance, suggested rebate adjustments, and smart nudges ("Customer X is close to the next slab - an increase of Y units would unlock a higher rebate")SKILL.mdguides you through: upload the scheme, review the AI's analysis of what is working and what is not, and get specific recommendations - optimized rebate percentages, credit note estimates, and customer-level nudges to drive behavior before month-end
onboarding-checklist - Personalized new hire setup
Every new hire needs IT access, HR paperwork, team introductions, tool setup, and a training schedule. But onboarding differs by role - an engineer's first week looks nothing like a sales rep's. Most companies have a checklist somewhere, but it is generic, outdated, or buried in a wiki nobody reads. This skill generates a personalized plan.
assets/has templates for IT setup requests, HR forms, training schedules, and first-week calendarsreferences/has role-specific guides (engineering onboarding includes dev environment setup and repo access; sales onboarding includes CRM training and territory briefing)SKILL.mdasks for the new hire's name, role, team, and start date, then generates a personalized checklist with specific tasks, deadlines relative to the start date, links to each form or system, and the name of who to contact for each step
Each of these examples uses the same simple building blocks: aSKILL.md for instructions, optional scripts for automation, optional references for context, and optional assets for templates. The format is the same. The possibilities are not.
Blog Series
| Blog | Topic | Status |
| Blog 1 | Calling Your First LLM on SAP AI Core | Published |
| Blog 2 | Structured Output and Your First Agent | Published |
| Blog 3 | From Terminal to Browser - A Chat UI | Published |
| Blog 4 | Evaluation with MLflow | Published |
| Blog 5 | Build Your First Agent Skill From Ground Zero | This blog |
Bluesky
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.