skill-authoring

Skill Authoring Guide

How to write effective skills that conform to the agentskills.io standard.

Core Principles

1. Conciseness Is King

The context window is a public good. Every skill shares this space.

Basic assumption: the agent is already very smart. Add only what the agent does not know. For every sentence, ask yourself:

• "Is this explanation really necessary?"
• "Does this paragraph justify its token cost?"

Prefer concise examples over verbose explanations.

2. Matching Degrees of Freedom

Degree of Freedom	When	Form
High	Multiple approaches are valid, judge based on context	Text instructions
Medium	A preferred pattern exists, some variation is allowed	Pseudocode/scripts with parameters
Low	Fragile tasks, consistency is essential	Specific scripts, minimal parameters

Narrow bridge (beside a cliff) = specific guardrails (low degree of freedom) Wide plain = allows diverse paths (high degree of freedom)

SKILL.md Structure

---
name: my-skill-name        # 필수, 소문자+하이픈, 1-64자
description: >             # 필수, 1-1024자
  무엇을 하는지 + 언제 사용하는지 + 관련 키워드
license: Apache-2.0        # 선택
metadata:                  # 선택
  author: misskim
  version: "1.0"
---

# 스킬 제목

[에이전트가 따를 지침 - 마크다운 자유형식]

Required Fields

• name: Must match the directory name, lowercase + hyphens only
• description: Serves as the skill activation trigger → make it keyword-rich

Directory Structure

skill-name/
├── SKILL.md          # 필수
├── scripts/          # 실행 코드 (Python/Bash/JS)
├── references/       # 상세 문서 (필요 시 로드)
└── assets/           # 정적 리소스 (템플릿, 이미지, 데이터)

Considerations Specific to Our Environment

1. Clawdbot agent: Place in skills/ or ~/.clawdbot/skills/
2. MiniPC integration: External tasks can be delegated via the nodes.run command
3. Subagents: Skills can be designed to spawn subagents
4. Security: Include only trusted code in scripts/
5. Keep SKILL.md under 500 lines — move detailed content to references/

Bad Skill vs Good Skill

Bad: "Processes PDFs" (description is too short) Good: "Extracts text/tables from PDF files, fills forms, and merges multiple PDFs. Use when mentioning PDF document work or document extraction."

Bad: Explaining Python syntax the agent already knows Good: Providing domain-specific knowledge/workflows the agent does not know

Prerequisites Checklist (Template)

When writing a new skill, first fill out the checklist below.

• The specific problemthis skill will solve is defined in one sentence.
• Checked for overlap with existing skills(if overlapping, consolidate into a routing section).
• Specified the required execution environment/dependencies (node, binaries, permissions, API keys).
• Defined the input/output forms (e.g., files, URLs, code, report templates).
• Wrote down the fallback path (alternative tool/manual procedure) in case of failure.
• Includes at least one real usage example.

When to Use / When NOT to Use (Decision Tree Template)

Add branching logic in the form of the template below at the top of the skill.

## When to Use This vs Others
- Use this skill when: {핵심 조건 1}, {핵심 조건 2}
- Use {other-skill} when: {대안 스킬이 더 적합한 조건}
- Do NOT use this skill when: {명확한 제외 조건}

Keep decision-making short at 2-3 lines, and always include cross-links between skill pairs that are easily confused with each other.

Dual Description Rule (Agent vs Marketplace)

Even for the same skill, separate descriptions by purpose.

• SKILL.md frontmatter description (for agents):
  • Include abundant trigger keywords.
  • Specify "when it should be invoked."
  • E.g., include domain keywords, request types, and activation signals.
• marketplace.json description (for humans):
  • Natural 1-2 sentences focused on a feature summary.
  • Write in marketing/discovery-friendly sentences.
  • Avoid listing internal trigger keywords.