AgentSkillsCN

skill-authoring

撰写有效的SKILL.md文件，以扩展代理的能力。适用于创建新技能、更新现有技能，或向代理传授专业化的 workflows 的场景。

SKILL.md
--- frontmatter
name: skill-authoring
description: Guide for creating effective SKILL.md files that extend agent capabilities. Use when creating new skills, updating existing ones, or teaching the agent specialized workflows.
metadata:
  author: misskim
  version: "1.0"
  origin: Concept from Anthropic skill-creator, adapted for Clawdbot agentskills.io standard

Skill Authoring Guide

agentskills.io 표준에 맞는 효과적인 스킬 작성법.

핵심 원칙

1. 간결함이 왕

컨텍스트 윈도우는 공공재다. 모든 스킬이 이 공간을 공유한다.

기본 가정: 에이전트는 이미 매우 똑똑하다. 에이전트가 모르는 것만 추가할 것. 모든 문장마다 자문:

  • •"이 설명이 정말 필요한가?"
  • •"이 단락이 토큰 비용을 정당화하는가?"

장황한 설명보다 간결한 예제를 선호.

2. 자유도 매칭

자유도언제형태
높음여러 접근법이 유효, 맥락에 따라 판단텍스트 지침
중간선호 패턴 존재, 일부 변형 허용의사코드/파라미터 있는 스크립트
낮음취약한 작업, 일관성 필수구체적 스크립트, 최소 파라미터

좁은 다리(절벽 옆) = 구체적 가드레일 (낮은 자유도) 넓은 평원 = 다양한 경로 허용 (높은 자유도)

SKILL.md 구조

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

# 스킬 제목

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

필수 필드

  • •name: 디렉토리명과 일치, 소문자+하이픈만
  • •description: 스킬 활성화 트리거 역할 → 키워드 풍부하게

디렉토리 구조

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

우리 환경 특화 고려사항

  1. •Clawdbot 에이전트: skills/ 또는 ~/.clawdbot/skills/에 배치
  2. •MiniPC 연동: nodes.run 명령으로 외부 작업 위임 가능
  3. •서브에이전트: 스킬이 서브에이전트를 스폰하도록 설계 가능
  4. •보안: scripts/ 코드는 신뢰할 수 있는 것만 포함
  5. •SKILL.md 500줄 이하 유지 — 상세 내용은 references/로 분리

나쁜 스킬 vs 좋은 스킬

나쁜: "PDF를 처리합니다" (description이 너무 짧음) 좋은: "PDF 파일에서 텍스트/표를 추출하고, 폼을 채우고, 여러 PDF를 병합합니다. PDF 문서 작업이나 문서 추출을 언급할 때 사용."

나쁜: 에이전트가 이미 아는 Python 문법 설명 좋은: 에이전트가 모르는 도메인 특화 지식/워크플로우 제공