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

To build a custom Claude skill, create a folder containing a 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, every skill must reside in its own folder within a domain category (Engineering, Product, Marketing, etc.) and contain four primary components:

• 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 front-matter registers the skill with Claude's plugin system, while the .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 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.

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

Step 2: Author the SKILL.md Front-Matter

The SKILL.md file must begin with YAML front-matter containing required metadata fields. The security auditor and marketplace parser both validate this structure.

---
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 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:

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

To invoke a specific skill directly from Claude Code:

/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 and return the formatted audit table.

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

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 front-matter syntax, and executes the security auditor on every pull request.

The Skill Security Auditor (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:

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 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 tool validates all skills before they enter the workspace.
• Skills are organized into domain folders and registered via .claude-plugin/marketplace.json for one-command installation.
• CI pipelines automatically lint and validate submissions against the SKILL-AUTHORING-STANDARD.md specification.

Frequently Asked Questions

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

The 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 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 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, 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 bundles.

What does the Skill Security Auditor check during validation?

The 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}