Claude Code Skills (Agent Skills) Introduction [Internal Study Session Slides]

I held a "Claude Code Skills (Agent Skills) Study Session" for internal team members (Cloud Business Division Consulting Department).

Here's the slide I've prepared for DevelopersIO.

Slide content: The text information is provided below. I hope it's helpful.

Purpose of the Study Session

I'll share the background, goals, and agenda of the study session.

Background

Skills are hot right now! 🔥

• Extensions that allow you to customize Claude Code (AI agent) to your liking
• Easy to create and easy to share

Goals of This Study Session

• All participants set up Skills and understand the basic usage
• Explore applications in regular work tasks together
• Draw out participants' knowledge and output

Expected Outcomes

• During this session: Complete Skills setup + understand basic usage
• Future (short-term): More people trying efficiency improvements using Skills in daily work
• Future (long-term): Accumulation of use cases, best practices, and standards within the team

Skills Overview

Understanding skill definitions and folder structure.

Skill Definition

Here's the official definition:

A simple, open format for giving agents new capabilities and expertise.

Agent Skills are folders of instructions, scripts, and resources that agents can discover and use. This helps agents complete tasks more accurately and efficiently.

– Overview - Agent Skills (translated to English)

Key Points About Skills

The key point is that it's a folder.

• Can contain not just instructions (SKILL.md) but also scripts and references
• Agents automatically discover which skills to use, follow the instructions, and utilize scripts and references in the folder as needed

Evolution of Skills

Originally developed by Anthropic for Claude Code.

• Released by Anthropic as an open standard
• Now being adopted by agent products beyond Claude Code
• Accepting contributions from the entire ecosystem

In other words, it's becoming a common skill format for agents rather than a Claude Code-specific mechanism.

Skill Folder Structure

The folder structure of a skill looks like this:

my-skill/
├── SKILL.md          # Required: Instructions + metadata
├── scripts/          # Optional: Scripts
├── references/       # Optional: References
└── assets/           # Optional: Templates and resources

Only SKILL.md is required. (= Just SKILL.md is OK)

Skill Demo *Adapted for external audience

Let's look at auto-triggering using the document template collection skill* as an example.

Input: Rough Notes

# Creating an S3 bucket

- Do it from the Management Console
- Bucket name should be like project-name-env-purpose
- Region is Tokyo
- Block all public access
- Enable versioning
...

Request to Claude Code

> Turn rough-notes.md into a procedure manual

What Happens

1. Skill triggers based on the SKILL.md description
2. Reads the SKILL.md content
3. Loads template files from references
4. Generates a procedure manual following the template

Reference: Skill Folder Structure

.claude/skills/doc-templates/
├── SKILL.md
└── templates/
    ├── how-to/
    │   ├── README.md
    │   └── template.md
    ├── concept/
    ├── troubleshooting/
    └── ...

Skill Specifications

Let's examine the mechanism behind what we saw in the demo.

Contents of SKILL.md

---
name: my-skill
description: Description of this skill. Also explain when Claude should use it.
---

# Write instructions here in natural language

The frontmatter at the top contains name (skill name) and description (when to use it). The main body contains free-form instructions in Markdown.

How Skills Work

Skills operate on Progressive Disclosure:

1. First check only the name / description of all skills (lightweight)
2. Load the full SKILL.md content for relevant skills
3. Read additional files in references/ etc. as needed

Instead of loading all skills from the start, it reads only what's needed when needed. The key is not overloading the context window.

Note: Skill Locations

There are user-scope and project-scope locations:

Note: Relationship with Slash Commands

Claude Code originally had /command: slash commands. It was a mechanism to write instructions in Markdown in .claude/commands/<name>.md.

Slash commands are actually skills now (they've evolved into that).

Source: https://code.claude.com/docs/ja/skills (as of 2026-03-10)

Tips for Using Skills

Here are some helpful points for creating and developing skills.

Keep SKILL.md Under 500 Lines

SKILL.md is the entry point of the skill. Use it as an overview and navigation. Put details in references/ etc.

my-skill/
├── SKILL.md          # Overview + navigation
├── references/       # Detailed references
├── examples.md       # Usage examples
└── scripts/
    └── helper.sh

Use context: fork for Subagent Execution

Adding context: fork to the frontmatter runs the skill as an isolated subagent.

This doesn't contaminate the main conversation context.

Example of using context:fork

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

• Source: code.claude - Run skills as subagents

Tips: What is a Subagent?

A specialized AI assistant that handles specific tasks. It runs in its own context window and doesn't access the main conversation history. After completion, only the results are returned to the main conversation.

— Sub-agents - Claude Code Official Documentation

When Skills Don't Trigger

Review your description. Is it clear to Claude when it should be used?

If it still doesn't work, the last resort is manual execution:

• Run directly as a slash command with /skill-name
• Example: /fix-issue 123

Security Considerations

Limit skill sources to trusted sources:

• Self-created skills
• Skills managed and reviewed internally
• Trusted public skills (e.g., anthropics/claude-code-skills)

If using third-party skills, review all contents (SKILL.md, scripts, references, etc.). If you're unsure, don't use it.

https://zenn.dev/nuits_jp/articles/2026-01-19-risks-of-skills-marketplace

Skill Creator Skill

Installing the official skill-creator allows you to interactively create and improve skills.

> /skill-creator
⏺ Welcome to Skill Creator!
  1. I want to create a new skill
  2. I want to improve an existing skill
  3. I want to run tests/evaluation of a skill
  4. I want to optimize a skill's description (trigger)

Distinguishing from Other Mechanisms

The following video is helpful for understanding how to choose between Skills, CLAUDE.md, MCP, and subagents:

• Claude Agent Skills Explained - YouTube

Skills vs CLAUDE.md

Skills vs MCP Servers

Skills vs Subagents

Hands-on *Adapted for external audience

Let's actually create a proposal using skills.

Prerequisites

Assuming Claude Code is already installed.

For the hands-on, we'll use the proposal-creation-toolkit plugin. Please register the marketplace (shared with the team in advance) and install the plugin.

Setting up slide generation (marp-cli) is optional.

1. Marketplace Registration + Plugin Installation

   1. Run /plugin in Claude Code
   2. Select "Marketplace → Add marketplace"
   3. Enter the (previously shared marketplace URL)
   4. Select "Proposal Creation Toolkit" from the plugin list and install

2. (Optional) marp-cli Setup

   If you want to experience Marp slide generation, please make sure marp-cli is available:

   # pnpm dlx: temporarily download and run a package (equivalent to npx)
   pnpm dlx @marp-team/marp-cli --version
   

Hands-on Overview

We'll use the proposal-creation-toolkit plugin to automatically generate a proposal from meeting minutes.

Meeting Minutes (meeting-memo.md)
    ↓  /create-proposal       ← Everyone
Proposal Markdown
    ↓  /marp-from-proposal    ← Optional
Marp Slides (.md) + Images
    ↓  marp-cli
Presentation (HTML)

Hands-on Steps

1. Step 1: Clone the Repository and Open

   Clone the hands-on repository and open it in Claude Code:

   git clone <Hands-on Repository URL>
   cd handson-repo
   claude
   

   File structure:

   handson-repo/
   ├── meeting-memo.md      ← Meeting minutes (sample)
   └── themes/
       └── custom.css       ← Marp theme
   

   Recommendation for hands-on: Set the model to Default (Sonnet) for faster responses.

   /model → Select 1. Default (recommended)
   

2. Step 2: Generate a Proposal

   Enter the following in Claude Code:

   /create-proposal @meeting-memo.md
   

3. Step 3: Answer Questions

   Claude will ask questions with multiple-choice options. Respond with the number.

4. Step 4: Review and Approve the Structure

   Claude will present a table of contents proposal. After reviewing, respond with "yes" to start generation.

   Generated file:

   proposal.md    ← Proposal markdown
   

5. (Optional) Step 5: Generate Marp Slides

   /marp-from-proposal @proposal.md
   

   Generated files:

   proposal_marp.md   ← Marp slides
   images/            ← Figures (auto-generated)
   

   ※For publicly available reference material, please see:

   Creating Proposal Slides Automatically from Meeting Minutes with Claude Code and Nano Banana Pro | DevelopersIO

6. (Optional) Step 6: Preview

   Use marp-cli to output slides to HTML and check them:

   pnpm dlx @marp-team/marp-cli proposal_marp.md --theme themes/custom.css
   
   # For PDF output
   pnpm dlx @marp-team/marp-cli proposal_marp.md --theme themes/custom.css --pdf
   

(For Those with Extra Time) Try the Skill Creator

If you have extra time, try the official skill-creator. It allows you to interactively create and improve skills.

Install via /plugin → Discover tab, search for skill-creator:

/plugin → Search for skill-creator in Discover

After installation:

/skill-creator

If you have tasks you'd like to make more efficient in your daily work, try turning them into skills.

Conclusion

Here's what we covered today:

• Skills Overview: Definition and folder structure
• Skills Demo: Experience with custom skill auto-triggering
• Skills Specifications: SKILL.md and progressive disclosure
• Tips for Using Skills: Distinctions from other mechanisms (CLAUDE.md / MCP / Subagents)
• Hands-on: Using proposal-creation-toolkit to generate proposal→slides from meeting minutes

Reference Links

• Skills - Claude Code Docs
• Overview - Agent Skills
• What are Skills? - Claude Support