ReddRadar
Agent skill
skill-design
Best practices for skill structure and types. Use when creating skills.
Install this agent skill to your Project
npx add-skill https://github.com/chkim-su/forge-editor/tree/main/skills/skill-design
SKILL.md
Skill Anatomy
skill-name/
├── SKILL.md # Required: core instructions (<500 words)
├── scripts/ # Optional: executable code
├── references/ # Optional: detailed docs (load on-demand)
└── assets/ # Optional: templates, images
Skill Types
| Type | Freedom | Use when | Structure |
|---|---|---|---|
| Knowledge | High | Multiple approaches, context-dependent | SKILL.md + references/ |
| Hybrid | Medium | Guidance + scripts needed | SKILL.md + scripts/ + references/ |
| Tool | Low | Deterministic, repeatable ops | SKILL.md + scripts/ |
| Expert | Very Low | Complex internals, undocumented APIs | Full + validation/ |
When to Script
- Same code rewritten repeatedly → Script
- File format manipulation → Script
- Reliability critical → Script
- External API/tool integration → Script
When to Hook (Enforcement Logic)
Rule: If behavior MUST happen, use hooks. Documentation cannot enforce.
| Requirement Type | Example | Solution |
|---|---|---|
| MUST/REQUIRED | "MUST use Skill tool" | PreToolUse hook to warn/block |
| Validation | "Schema must be valid" | PostToolUse hook to validate |
| Prevention | "Never commit secrets" | PreToolUse hook to block |
| Guidance | "Consider using X" | Documentation only (OK) |
Hook vs Documentation Decision
If keyword in ["MUST", "REQUIRED", "CRITICAL", "강제", "반드시"]:
→ Implement as Hook (documentation alone WILL be ignored)
If keyword in ["should", "consider", "recommend"]:
→ Documentation is sufficient
Hookify Checklist
Before finalizing skill:
- Search for enforcement keywords (MUST, REQUIRED, CRITICAL)
- Each enforcement requirement → corresponding hook exists?
- If no hook → either create hook OR downgrade to "should"
Example:
- ❌ "MUST use Skill() tool" in SKILL.md → Agents ignore this
- ✅ PreToolUse hook on Read/Grep/Glob warns when skill files accessed directly
SKILL.md Structure
---
name: skill-name
description: What + when to use (triggers skill loading)
allowed-tools: ["Tool1", "Tool2"]
---
# Skill Name
[2-3 sentence overview]
## Quick Start
[Fastest path]
## Workflow
1. Step 1
2. Step 2
## Scripts
| Script | Purpose | Usage |
|--------|---------|-------|
## Key Principles
- Principle 1
- Principle 2
For advanced: [references/advanced.md]
Tool Restrictions
# Knowledge (read-only)
allowed-tools: ["Read", "Grep", "Glob"]
# Hybrid (guidance + generation)
allowed-tools: ["Read", "Write", "Grep", "Glob", "Bash"]
# Tool (file manipulation)
allowed-tools: ["Read", "Write", "Bash"]
Checklist
- SKILL.md < 500 words
- Description includes trigger phrases
- Scripts tested
- References linked
- allowed-tools matches purpose
- Hookify check: Enforcement keywords (MUST/REQUIRED/CRITICAL) → hooks exist
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
chkim-su/forge-editor
forge-analyzer
Analyze vague user ideas and recommend architecture based on actual needs, not predefined categories. Front-end for clarifying ambiguous requests before routing to appropriate skillmaker tools.
chkim-su/forge-editor
hook-system
Claude Code Hook system entry point. Guides you to the right skill based on your needs.
chkim-su/forge-editor
mcp-gateway-patterns
MCP Gateway design patterns for Agent Gateway, Subprocess, and Daemon isolation. Use when designing MCP integrations.
chkim-su/forge-editor
workflow-state-patterns
Hook-based state machine patterns for multi-phase workflows. Use when designing sequential workflows with quality gates.
chkim-su/forge-editor
mcp-daemon-isolation
Context isolation for query-type MCP tools (LSP, search, database) via external CLI. Use when MCP query results consume too many context tokens.
chkim-su/forge-editor
critical-analysis-patterns
Philosophical/meta project analysis - critical analysis framework that asks "why?"
Didn't find tool you were looking for?