# Building Custom Claude Skills with SKILL.md: The Complete Developer Guide

> Learn to build custom Claude skills with SKILL.md. Discover how to structure your skill, add Python scripts and references, and validate your package for contribution.

- Repository: [Alireza Rezvani/claude-skills](https://github.com/alirezarezvani/claude-skills)
- Tags: tutorial
- Published: 2026-03-09

---

**To build a custom Claude skill, create a folder containing a [`SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL.md) file with YAML front-matter that registers the skill name and version, accompanied by optional Python scripts in a `scripts/` directory and reference materials under `references/`, then validate your package using the security auditor before submitting to the alirezarezvani/claude-skills repository.**

The **alirezarezvani/claude-skills** repository provides a modular framework for extending Claude Code, OpenAI Codex, and OpenClaw agents with domain-specific expertise. Each skill package follows a strict directory layout centered around the **SKILL.md** file, which acts as both the manifest and documentation entry point for the skill registry system.

## Understanding the SKILL.md Architecture

The skill package structure follows a predictable pattern that enables Claude to automatically discover and load capabilities. According to the repository's [`SKILL-AUTHORING-STANDARD.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL-AUTHORING-STANDARD.md), every skill must reside in its own folder within a domain category (Engineering, Product, Marketing, etc.) and contain four primary components:

- **[`SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL.md)**: The core manifest file containing YAML front-matter (name, description, version, tags) and Markdown documentation explaining usage and capabilities.
- **`scripts/`**: Optional Python CLI tools that use only the standard library, ensuring zero-dependency execution across any Python 3 interpreter.
- **`references/`**: Markdown knowledge bases providing factual context, threat models, or best-practice guides for the agent.
- **`assets/`**: Static templates, sample data, or configuration files (JSON, HTML, Terraform) that scripts can copy or render.

The [`SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL.md) front-matter registers the skill with Claude's plugin system, while the [`.claude-plugin/marketplace.json`](https://github.com/alirezarezvani/claude-skills/blob/main/.claude-plugin/marketplace.json) file at the repository root defines skill bundles for one-command marketplace installations.

## Creating Your First Custom Claude Skill

Follow the authoring standards defined in [`SKILL-AUTHORING-STANDARD.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL-AUTHORING-STANDARD.md) to ensure compatibility with the Claude marketplace and CI validation pipeline.

### Step 1: Initialize the Skill Directory

Create a new skill folder within the appropriate domain category. The repository organizes skills by domains to maintain logical groupings.

```bash
mkdir -p my-domain/my-awesome-skill
cd my-domain/my-awesome-skill

```

### Step 2: Author the SKILL.md Front-Matter

The [`SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL.md) file must begin with YAML front-matter containing required metadata fields. The security auditor and marketplace parser both validate this structure.

```yaml
---
name: my-awesome-skill
description: >
  Generates a weekly report on repository health, including code-coverage,
  static-analysis warnings, and dependency freshness.
version: 0.1.0
tags: [report, analytics, automation]
---

# My Awesome Skill

## What It Does

- Runs `pytest --cov` to compute coverage.
- Calls `flake8` and `bandit` for lint & security findings.
- Emits a Markdown summary to `assets/report.md`.

## Usage

```bash
python3 scripts/generate_report.py <repo-path>

```

```

### Step 3: Add Executable Scripts

Place Python automation tools in the `scripts/` directory. These scripts must use only Python standard library modules to maintain zero-dependency portability. For example, [`scripts/generate_report.py`](https://github.com/alirezarezvani/claude-skills/blob/main/scripts/generate_report.py) would implement the logic referenced in the [`SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL.md) usage section.

### Step 4: Validate with the Security Auditor

Before submitting your skill, run the **Skill Security Auditor** to perform static analysis and verify compliance with repository standards.

```bash
python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py .

```

The tool at [`engineering/skill-security-auditor/scripts/skill_security_auditor.py`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering/skill-security-auditor/scripts/skill_security_auditor.py) produces a PASS, WARN, or FAIL verdict with detailed JSON or human-readable output identifying security risks or structural violations.

## Installing and Using Skills in Claude Code

Once validated and merged, skills become available through the Claude marketplace or direct installation.

To install a skill bundle from the marketplace:

```bash
/plugin marketplace add alirezarezvani/claude-skills
/plugin install engineering-skills@claude-code-skills

```

To invoke a specific skill directly from Claude Code:

```text
/plugin run skill-security-auditor /path/to/skill/

```

Claude will execute the Python scanner located at [`engineering/skill-security-auditor/scripts/skill_security_auditor.py`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering/skill-security-auditor/scripts/skill_security_auditor.py) and return the formatted audit table.

For command-line usage without the agent, run scripts directly:

```bash
python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py ./my-domain/my-awesome-skill/

```

## Skill Security and CI Validation

The repository enforces quality through automated GitHub Actions workflows. The CI pipeline lints Markdown, validates [`SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL.md) front-matter syntax, and executes the security auditor on every pull request.

The **Skill Security Auditor** ([`engineering/skill-security-auditor/SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering/skill-security-auditor/SKILL.md)) serves as both a reference implementation and a mandatory gate. It scans for common vulnerabilities in skill scripts, validates that Python code avoids external dependencies, and ensures that no secrets or unsafe patterns exist in the automation logic.

For batch validation across multiple skills, use a shell loop:

```bash
for d in */*/ ; do
  python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py "$d" --json >> audit-results.jsonl
done

```

## Summary

Building custom Claude skills with SKILL.md involves creating standardized packages that extend AI agents with deterministic automation and domain knowledge. Key takeaways include:

- Every skill requires a [`SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL.md) file with valid YAML front-matter containing name, description, version, and tags.
- Python scripts must reside in `scripts/` and use only standard library modules to ensure zero-dependency execution.
- The [`engineering/skill-security-auditor/scripts/skill_security_auditor.py`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering/skill-security-auditor/scripts/skill_security_auditor.py) tool validates all skills before they enter the workspace.
- Skills are organized into domain folders and registered via [`.claude-plugin/marketplace.json`](https://github.com/alirezarezvani/claude-skills/blob/main/.claude-plugin/marketplace.json) for one-command installation.
- CI pipelines automatically lint and validate submissions against the [`SKILL-AUTHORING-STANDARD.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL-AUTHORING-STANDARD.md) specification.

## Frequently Asked Questions

### What is the purpose of the SKILL.md file in Claude skills?

The [`SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL.md) file serves as the canonical manifest and documentation entry point for each skill package. It contains YAML front-matter that registers the skill's metadata (name, description, version, tags) with Claude's plugin system, followed by Markdown documentation explaining capabilities, usage instructions, and examples. The file acts as the bridge between human-readable documentation and machine-parseable configuration.

### Can I use external Python libraries in my skill scripts?

No. The [`SKILL-AUTHORING-STANDARD.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL-AUTHORING-STANDARD.md) explicitly requires that all scripts in the `scripts/` directory use only Python standard library modules. This zero-dependency policy ensures that skills run on any Python 3 interpreter without requiring `pip install` or virtual environments. If you need complex dependencies, you should document manual setup steps in the [`SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL.md) references section rather than automating them.

### How do I install a custom skill that isn't in the marketplace?

You can install skills directly by copying the skill folder (containing [`SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL.md), `scripts/`, `references/`, and `assets/`) into your local workspace or by referencing the folder path in Claude Code. For marketplace distribution, you must submit a pull request to the `alirezarezvani/claude-skills` repository, pass the security auditor validation, and have the skill added to the [`.claude-plugin/marketplace.json`](https://github.com/alirezarezvani/claude-skills/blob/main/.claude-plugin/marketplace.json) bundles.

### What does the Skill Security Auditor check during validation?

The [`skill_security_auditor.py`](https://github.com/alirezarezvani/claude-skills/blob/main/skill_security_auditor.py) script performs static analysis on skill packages to identify security risks and structural violations. It checks for hardcoded secrets, unsafe subprocess calls, disallowed external imports, malformed YAML front-matter in [`SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL.md), and missing required directories. The auditor outputs a PASS, WARN, or FAIL verdict and is integrated into the repository's CI pipeline to gate all pull requests.