🎓 Mastering Claude Agent Skills

Objective: Build, test, and deploy reusable "Expertise Packages" for Claude Code and Claude.ai.

Module 1: The Anatomy of a Skill

Before writing code, you must understand the "Three-Tier" architecture of a Skill.

• Tier 1: Frontmatter (Discovery): A small YAML block that Claude always sees. It tells Claude when to wake up this skill.
• Tier 2: SKILL.md (The Playbook): The core markdown instructions. This is loaded into context only when the skill is active.
• Tier 3: Supporting Files (Knowledge): Additional scripts (.py, .sh) or data files (.json, .csv) the skill can call upon.

Key File Structure:

Plaintext

.claude/skills/my-awesome-skill/

├── SKILL.md # Core instructions and metadata

├── checklist.json # Supporting data

└── utils.py # Custom script for the skill to run

Module 2: Writing the SKILL.md

A professional skill requires specific "Frontmatter."

Exercise: The "Security Auditor" Skill

Create a file at ~/.claude/skills/security-audit/SKILL.md:

Markdown

---

name: security-audit

description: Review code for OWASP vulnerabilities and security flaws. Use when user asks for a "security check" or "audit".

user-invocable: true

---

# Security Auditor Skill

When this skill is active:

1. Scan the codebase for hardcoded secrets (API keys, passwords).

2. Check for SQL Injection risks in database queries.

3. Verify that all user input is sanitized.

4. If "ultrathink" is mentioned, perform a deep architectural trace.

## Guidelines

- Always output a "Risk Level" (Low/Medium/High) for every finding.

- Provide a "Remediation" code snippet for every bug.

Module 3: Advanced Execution (Subagents & Thinking)

To make your skills "Pro-grade," use these two advanced parameters in your frontmatter:

1. context: fork: This runs the skill in a Subagent. The subagent has its own context window. It can read 50 files, summarize them, and send only the summary back to your main chat. This prevents "context bloat."
2. ultrathink: Including this keyword in your SKILL.md (or your prompt) triggers Claude’s Extended Thinking mode, making it much better at logic-heavy tasks like debugging.

Module 4: The "Skill-Creator" Meta-Skill

Anthropic provides a built-in "Skill-Creator" to help you build other skills.

The Workflow:

1. Type /skill-creator (if available) or simply ask Claude: "I want to build a skill for [X]. Help me write the SKILL.md and structure."
2. Claude will interview you about the Trigger and the Steps.
3. It will output the folder structure and content for you to save.

Module 5: Testing & Distribution

How to know your skill actually works:

1. Direct Invocation: Type /name-of-skill in the terminal. Claude should acknowledge: The "name-of-skill" skill is loading.
2. Auto-Trigger: Ask a question related to the skill's description without using the slash command. If Claude loads the skill automatically, your description is well-written.
5. Project vs. Global:
   • Global: Save in ~/.claude/skills/ to use in every project.
   • Project-Specific: Save in your repo at .claude/skills/ and commit it. Now every teammate who uses Claude Code on that repo has the skill.

🛠 Project: Build Your Final Skill

Your Task: Build a "Documentation Architect" skill.

• Goal: Automatically generates a README.md based on a folder's source code.
• Requirements: Use context: fork so it can read the whole directory without filling your chat history.
• Trigger: Should activate when the user says "Document this folder."