skill-creator

Original：🇺🇸 English

Translated

Guide for creating effective agent skills. Use PROACTIVELY when creating new skills or refactoring bloated ones. Teaches progressive disclosure, 200-line rule, and 3-tier loading system.

2installs

Sourcecarvalab/k-skills

Added on2026-02-19

NPX Install

npx skill4agent add carvalab/k-skills skill-creator

SKILL.md Content

View Translation Comparison →

Skill Creator

Create effective agent skills using progressive disclosure. Skills are workflow capabilities, not documentation dumps. The goal is loading the right information at the right time.

Core Principle

Skills ≠ Documentation

```
devops
```
isn't "Cloudflare docs" → it's the ability to deploy infrastructure
```
ui-styling
```
isn't "Tailwind docs" → it's the ability to design interfaces
Each skill teaches how to perform a task, not what a tool does

3-Tier Architecture

Tier 1: Metadata (always loaded)
├── YAML frontmatter only (~100 words)
└── Enough for Claude to decide relevance

Tier 2: SKILL.md entry point (loaded on activation)
├── ~200 lines MAX
├── Overview, quick start, navigation
└── Points to references (doesn't include them)

Tier 3: references/ (loaded on-demand)
├── 200-300 lines each
├── Detailed documentation
└── Focused on single topics

The 200-Line Rule

Entry point MUST be under 200 lines. This enables:

Fast relevance scanning
Quick reference selection
400-700 lines of relevant context vs 1,000+ of mixed relevance

If you can't fit core instructions in 200 lines, you're putting too much in the entry point.

Skill Structure

skills/my-skill/
├── SKILL.md              # Entry point (<200 lines)
├── references/           # Detailed content
│   ├── guide-a.md        # 200-300 lines each
│   ├── guide-b.md
│   └── examples.md
├── scripts/              # Optional executable code
└── assets/               # Optional templates

SKILL.md Template

markdown

---
name: skill-name
description: One-line description. When to use this skill.
tools: Read, Write, Edit, Bash  # Optional
model: opus                      # Optional
---

# Skill Name

Brief description (2-3 sentences max).

## Quick Start

\`\`\`bash
# Essential commands only
\`\`\`

## Workflow

### 1. First Step
- Key points only
- No lengthy explanations

### 2. Second Step
- Action-oriented
- Link to references for details

## References

| Reference | Purpose |
|-----------|---------|
| `references/detailed-guide.md` | Full implementation details |
| `references/examples.md` | Code examples |

Writing Guidelines

Imperative tone: "Run the build" not "You should run the build"
Action-oriented: What to do, not what things are
Progressive detail: Overview → Reference → Implementation
No redundancy: Say it once, in the right place

When to Create vs Reference

Create a skill when:

Task requires specific workflow knowledge
Multiple steps with decision points
Reusable across projects

Use references when:

Detailed implementation specifics
Code examples
Edge cases and troubleshooting

Refactoring Bloated Skills

Signs you need to refactor:

SKILL.md over 200 lines
Loading 5+ skills causes context issues
90% of loaded content isn't used

Process:

Extract detailed sections to
```
references/
```
Keep only overview in SKILL.md
Add navigation table to references
Test cold start (should load <500 lines)

References

Reference	Purpose
`references/architecture.md`	3-tier system deep dive
`references/frontmatter.md`	YAML frontmatter spec
`references/writing-guide.md`	Content writing best practices
`references/refactoring.md`	How to split bloated skills
`references/anti-patterns.md`	What NOT to do
`references/examples.md`	Complete skill examples

Metrics

After creating/refactoring a skill:

Entry point: <200 lines ✓
Each reference: 200-300 lines ✓
Cold start load: <500 lines ✓
Relevant info ratio: >80% ✓