Skip to content
Back to search

agent-skills-in-practice

Learn what AI skills are and how to design, structure, and use them in real-world agent systems.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/elisaterumi-ai--agent-skills-in-practice/badge.svg)](/listings/elisaterumi-ai--agent-skills-in-practice)

HTML

<a href="/listings/elisaterumi-ai--agent-skills-in-practice"><img src="/api/listings/elisaterumi-ai--agent-skills-in-practice/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 267 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. 🌍 Language:
  2. [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md)
  3. # AI Skills — A Practical Guide
  4. From prompts to systems — learn how to build reusable AI skills.
  5. Skills are one of the core building blocks of modern AI systems.
  6. They allow you to define reusable, task-specific capabilities that an AI system can automatically apply when relevant — without repeating instructions every time.
  7. ⭐ If this project helped you, please consider giving it a star — it helps others discover it and supports the work!
  8. ## Table of Contents
  9. - [Skills Quick Guide](#skills-quick-guide)
  10. - [What are Skills](#what-are-skills)
  11. - [How Skills Work](#how-skills-work)
  12. - [Skill Structure](#skill-structure)
  13. - [Where Skills Live](#where-skills-live)
  14. - [Skills vs Other Customizations](#skills-vs-other-customizations)
  15. - [When to Use Skills](#when-to-use-skills)
  16. - [Example Use Cases](#example-use-cases)
  17. - [Creating Your First Skill](#-creating-your-first-skill)
  18. - [Best Practices](#best-practices)
  19. - [Common Mistakes](#common-mistakes)
  20. - [Advanced Concepts](#advanced-concepts)
  21. - [Why Skills Matter](#why-skills-matter)
  22. - [Resources](#resources)
  23. - [Final Thought](#final-thought)
  24. - [Contributing](#-contributing)
  25. - [Connect with me](#-connect-with-me)
  26. ## Skills Quick Guide
  27. A quick visual reference to understand how skills work — from structure to activation.
  28. <img src="https://raw.githubusercontent.com/elisaterumi-ai/agent-skills-in-practice/main/img/skills-guide-en.png" width="600"/>
  29. > 💡 Use this as a quick reference while building your own skills.
  30. ## What are Skills?
  31. A **skill** is a structured set of instructions that teaches an AI system how to perform a specific task.
  32. In Claude Code, a skill is:
  33. - A directory
  34. - Containing a `SKILL.md` file
  35. - With metadata and instructions
  36. Once defined, the system can discover and use the skill automatically.
  37. > Instead of repeating prompts, you encode behavior once — and reuse it.
  38. ## How Skills Work
  39. Skills follow a **semantic matching workflow**:
  40. 1. The system loads only skill **names and descriptions**
  41. 2. A user request is received
  42. 3. The system compares the request with available skill descriptions
  43. 4. Matching skills are selected
  44. 5. The full skill content is loaded and executed
  45. This means:
  46. - Skills are **loaded on demand**
  47. - They do **not clutter context unnecessarily**
  48. - They activate **only when relevant**
  49. ## Skill Structure
  50. Each skill lives inside a directory and must contain a `SKILL.md` file.
  51. ### Example:
  52. ```yaml
  53. ---
  54. name: pr-review
  55. description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes.
  56. ---
  57. ```
  58. Below the frontmatter, you define the instructions:
  59. ```yaml
  60. When reviewing a PR:
  61. 1. Analyze code changes
  62. 2. Check for best practices
  63. 3. Suggest improvements
  64. 4. Format output as structured feedback
  65. ```
  66. ## Where Skills Live
  67. Skills can be scoped at different levels:
  68. ### Personal Skills
  69. - Location: `~/.claude/skills`
  70. - Available across all your projects
  71. - Ideal for personal workflows
  72. ### Project Skills
  73. - Location: `.claude/skills` (inside a repository)
  74. - Shared via version control
  75. - Used for team standards
  76. ## Skills vs Other Customizations
  77. | Feature | Behavior | Use Case |
  78. |-------------------|------------------------|--------------------------|
  79. | **Skills** | Load on demand | Task-specific expertise |
  80. | **CLAUDE.md** | Always loaded | Global project rules |
  81. | **Slash Commands**| Manual invocation | Explicit actions |
  82. 👉 Skills are **automatic and contextual**
  83. ## When to Use Skills
  84. Use a skill when:
  85. - You repeat the same instructions frequently
  86. - You need consistent output formats
  87. - You want reusable workflows
  88. - You want to share knowledge across a team
  89. **Rule of thumb:**
  90. > If you explain the same thing more than once, it should be a skill.
  91. ## Example Use Cases
  92. - Code review standards
  93. - Commit message formatting
  94. - Documentation templates
  95. - Debugging checklists
  96. - Data transformation workflows
  97. - Clinical text anonymization
  98. 👉 Explore ready-to-use skills: [examples](examples)
  99. > Some examples are inspired by existing open-source skill repositories.
  100. ## 🚀 Creating Your First Skill
  101. ### Step 1 — Create directory
  102. ```bash
  103. mkdir -p ~/.claude/skills/my-skill
  104. ```
  105. ### Step 2 — Create `SKILL.md` (or use the template)
  106. Create a `SKILL.md` file inside your skill directory, or copy from the [provided template](templates/skill-template.md).
  107. ```yaml
  108. ---
  109. name: my-skill
  110. description: Describe what the skill does and when to use it.
  111. ---
  112. ```
  113. ### Step 3 — Add instructions
  114. Define:
  115. - Steps
  116. - Rules
  117. - Output format
  118. ## Best Practices
  119. - Write **clear and specific descriptions** (this controls activation)
  120. - Keep instructions **structured and explicit**
  121. - Define **expected output formats**
  122. - Avoid overly generic skills
  123. - Keep `SKILL.md` concise (use references if needed)
  124. ## Common Mistakes
  125. - Treating skills as simple prompts
  126. - Writing vague descriptions (skill won’t trigger)
  127. - Overloading a single skill with multiple responsibilities
  128. - Not defining output structure
  129. ## Advanced Concepts
  130. ### Metadata Fields
  131. - `name` (required)
  132. - `description` (required)
  133. - `allowed-tools` (optional)
  134. - `model` (optional)
  135. ### Progressive Disclosure
  136. - Keep core logic in `SKILL.md`
  137. - Move large content to:
  138. - `references/`
  139. - `scripts/`
  140. - `assets/`
  141. ## Why Skills Matter
  142. Skills transform how we build with AI:
  143. - From **prompts → reusable systems**
  144. - From **manual instructions → automatic behavior**
  145. - From **experimentation → production-ready workflows**
  146. They are a key building block for:
  147. - AI agents
  148. - Automation pipelines
  149. - Scalable AI systems
  150. ## Resources
  151. Curated links, documentation, and example repositories:
  152. 👉 [Explore resources](docs/resources.md)
  153. ## Final Thought
  154. Skills shift the mindset from:
  155. > “What should I ask the model?”
  156. To:
  157. > “What capability should this system have?”
  158. ## 🤝 Contributing
  159. Contributions are welcome!
  160. Ways to contribute:
  161. - Add new skills or use cases
  162. - Improve documentation and examples
  163. - Report issues or suggest improvements
  164. Feel free to open an issue or submit a pull request 🚀
  165. ## 🔗 Connect with me
  166. I share practical insights about AI, agents, and real-world applications:
  167. - LinkedIn (Profile): https://www.linkedin.com/in/elisa-terumi
  168. - LinkedIn (Page): https://www.linkedin.com/company/exploring-artificial-intelligence
  169. - Newsletter: https://exploringartificialintelligence.substack.com/
  170. - Medium: https://medium.com/@elisa-terumi
  171. ## Star History
  172. <a href="https://www.star-history.com/?repos=elisaterumi-ai%2Fagent-skills-in-practice&type=date&legend=top-left">
  173. <picture>
  174. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=elisaterumi-ai/agent-skills-in-practice&type=date&theme=dark&legend=top-left" />
  175. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=elisaterumi-ai/agent-skills-in-practice&type=date&legend=top-left" />
  176. <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=elisaterumi-ai/agent-skills-in-practice&type=date&legend=top-left" />
  177. </picture>
  178. </a>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.