# Skill Design

> |

- **Type:** Skill
- **Install:** `agentstack add skill-houarnu166-skillful-agent-system-builder-skill-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [houarnu166](https://agentstack.voostack.com/s/houarnu166)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [houarnu166](https://github.com/houarnu166)
- **Source:** https://github.com/houarnu166/skillful-agent-system-builder/tree/main/.agents/skills/skill-design

## Install

```sh
agentstack add skill-houarnu166-skillful-agent-system-builder-skill-design
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill Design Guide

## Overview

This Skill provides methods for designing and implementing effective Skills. Skills are modular packages that extend Claude's capabilities for specific domains or tasks.

## About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as **"onboarding guides"** for specific domains or tasks.

**What Skills provide**:
1. **Specialized workflows** - Multi-step procedures for specific domains
2. **Tool integrations** - Guides for specific file formats or API operations
3. **Domain expertise** - Company-specific knowledge, schemas, business logic
4. **Bundled resources** - Scripts, reference documents, assets for complex and repetitive tasks

## Core Principle: Concise is Key

**Context window is a public good.** Only add context Claude doesn't already know.

- "Does Claude really need this explanation?"
- "Does this paragraph justify its token cost?"

**Prefer concise examples over verbose explanations.**

---

## Skill Creation Process (6 Steps)

### Step 1: Understand with Concrete Examples
Collect and understand concrete examples of how the Skill will be used.

### Step 2: Plan Reusable Content
Identify reusable resources that can be separated into scripts, references, assets.

### Step 3: Initialize Skill
Create Skill directory structure. (Recommend using `init_skill.py` script)

### Step 4: Write Skill
Implement SKILL.md and bundled resources.
→ See [frontmatter-guide.md](references/frontmatter-guide.md) for frontmatter rules

### Step 5: Package Skill
Package into distributable .skill file. (Use `package_skill.py`)

### Step 6: Iterate with Real Usage
Improve based on actual usage.

---

## SKILL.md Structure

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/          - Executable code
    ├── references/       - Documents loaded when needed
    └── assets/           - Files used in output
```

### Frontmatter Essentials

| Field | Rules |
|-------|-------|
| `name` | lowercase + hyphens, 1-64 chars, matches directory name |
| `description` | 1-1024 chars, includes functionality + trigger conditions |

**Important**: Include all "when to use" info in description. "When to Use" sections in Body don't help Claude since they're only loaded after triggering.

→ See [frontmatter-guide.md](references/frontmatter-guide.md) for detailed rules

---

## Progressive Disclosure (3-Level Loading)

1. **Metadata** (~100 words) - Always in context
2. **SKILL.md body** (<500 lines) - When Skill triggers
3. **Bundled resources** - Loaded as needed

### 3 Patterns

| Pattern | When to Use |
|---------|-------------|
| **Pattern 1**: High-level Guide | When there are multiple related features |
| **Pattern 2**: Domain-specific | When there are distinct sub-domains |
| **Pattern 3**: Conditional Details | When advanced features are occasionally needed |

→ See [progressive-disclosure.md](references/progressive-disclosure.md) for patterns and examples

---

## Bundled Resources

| Directory | Purpose | Example |
|-----------|---------|---------|
| `scripts/` | Code requiring deterministic reliability | `rotate_pdf.py` |
| `references/` | Documents loaded when needed | `schema.md` |
| `assets/` | Files used in output | `template.html` |

→ See [bundled-resources.md](references/bundled-resources.md) for detailed guide

---

## Decision Tree: Content Placement

```
Content Type → Placement
├─ Trigger conditions → description (frontmatter)
├─ Core workflow → SKILL.md body
├─ Detailed reference → references/
├─ Repetitive code → scripts/
└─ Output templates → assets/
```

---

## Design Principles

1. **Conciseness**: SKILL.md core only, under 500 lines
2. **Progressive Disclosure**: Utilize 3-level loading
3. **Clear Triggers**: Specify usage timing in description
4. **1 Level Depth**: References link directly from SKILL.md

---

## Validation

→ See [validation-checklist.md](references/validation-checklist.md) for complete checklist

**Quick Check**:
- [ ] `name`: lowercase + hyphens, 1-64 chars
- [ ] `description`: functionality + trigger conditions, 1-1024 chars
- [ ] SKILL.md: under 500 lines
- [ ] No unnecessary files (README.md, CHANGELOG.md, etc.)

---

## Common Mistakes

- ❌ Missing trigger conditions in description
- ❌ Including "When to Use" section in Body
- ❌ SKILL.md over 500 lines
- ❌ References nested 2+ levels deep
- ❌ Information duplicated between SKILL.md and references

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [houarnu166](https://github.com/houarnu166)
- **Source:** [houarnu166/skillful-agent-system-builder](https://github.com/houarnu166/skillful-agent-system-builder)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-houarnu166-skillful-agent-system-builder-skill-design
- Seller: https://agentstack.voostack.com/s/houarnu166
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.