Master Resource Pack

AI Agent Skills & SKILL.md Guide

Step-by-step setup guide and build pack for discovering, auditing, installing, testing, and creating agent skills using skills.sh.

Contents

📌 1. Core Concept & Progressive Disclosure

Key Takeaway: A skill is a reusable playbook for an AI agent. You package guidelines, constraints, or workflows once in a directory, and compatible agents load them automatically when relevant.

Agent Skills (agentskills.io) are an open specification supported by Claude Code, Cursor, Copilot, and Antigravity. To protect context windows, skills use Progressive Disclosure:

1. Discovery (Catalog): Agent reads only the name and description from YAML frontmatter at startup.
2. Activation (Instructions): Agent loads the full SKILL.md file only when your prompt matches the skill's purpose.
3. Execution (Resources): Helper scripts (Bash/Node) or reference sheets are loaded only if explicitly called during execution.

📄 2. What a SKILL.md File Contains

A skill requires at least a SKILL.md file with YAML frontmatter followed by Markdown instructions:

EXACT STARTER SKILL.MD EXAMPLE 
---
name: natural-message-writer
description: Rewrites emails and chat messages so they sound concise and natural. Use when a user asks to rewrite, shorten, simplify, or humanize a message.
---

# Goal
Rewrite the message clearly while preserving its original meaning.

# Workflow
1. Identify the main point.
2. Preserve names, dates, requests, and commitments.
3. Remove filler and repeated ideas.
4. Use short, natural sentences.
5. Do not invent information.

# Output
Return: 1. A natural version, 2. A shorter version

# Final checks
- The meaning is unchanged
- No facts were invented
- The requested action is clear

Required Frontmatter Fields: name (hyphen-case string) and description (trigger criteria).

🛡️ 3. Read a Skill Before Installing It

⚠️ Safety Checklist Before Running Install Commands:

  • Inspect SKILL.md: Verify no malicious file modifications, token theft, or unauthorized network calls.
  • Audit scripts/: Inspect Bash, Python, or JavaScript helper scripts for obfuscated code.
  • Check Dependencies: Review package.json or manifest files before installing external packages.
  • Verify Permissions: Confirm whether unsandboxed execution or elevated rights are requested.

Note: Appearing on skills.sh is an open registry and does NOT constitute a security audit guarantee. Never run skill installation with admin/root privileges.

🚀 4. 10-Step Setup Guide

1 Confirm Compatibility

Ensure your AI agent supports Agent Skills (Claude Code, Cursor, Antigravity, Copilot).

2 Search skills.sh

Browse skills.sh for a workflow addressing your specific task.

3 Inspect Source Repository

Click through to the GitHub repository to verify the author and commit history.

4 Read SKILL.md

Confirm the instructions and scope match your safety requirements.

5 Run Verified Installation Command

TERMINAL COMMAND 
npx skills add  --skill

6 Refresh & Verify Discovery

Restart your AI agent and run npx skills list to confirm discovery.

🔬 6. How to Test Skill Impact

  1. Select one scoped task and lock baseline variables (same model, prompt, codebase).
  2. Run without the skill and save the output.
  3. Install the skill and run the exact same prompt.
  4. Compare outputs on compilation accuracy, accessibility, performance, and guideline compliance.
  5. Keep the skill only if it produces measurable improvement.

🛠️ 7. Build a Custom Skill

Create .agents/skills/my-skill/SKILL.md in your project:

---
name: my-skill
description: Brief statement explaining when the agent should trigger this skill.
---

# Workflow
1. Step one instructions.
2. Step two instructions.

💡 8. Quick Knowledge Check

Q1: What are the two mandatory YAML frontmatter fields in a SKILL.md file?

Q2: How do skills avoid consuming your context window on every turn?