Agent Skills

Agent Skills

Agent는 MCP뿐 아니라 Skill을 활용하여 다양한 기능을 편리하게 구현할 수 있습니다. 여기에서는 LangGraph에서 Agent skill을 활용하는 방법에 대해 설명합니다. 전체적인 architecture는 아래와 같습니다. CloudFront - ALB - EC2로 streamlit을 안전하게 제공하고, LangGraph Agent에 MCP와 Skills 기능을 구현합니다.

Agent Skills

Agent Skills은 AI agent에게 특정 작업 수행 방법을 가르치는 재사용 가능한 지침 패키지입니다. Agent skills는 효과적으로 context를 관리하기 위하여 discovery, activation, execution의 과정을 거칩니다. 정리하면 agent가 관련된 skill의 name과 description을 읽는 discovery를 수행한 후에, SKILL.md에 포함된 instruction을 읽는 activation을 수행합니다. Agent는 instruction을 수행하는데 필요하다면 관련된 파일(referenced file)을 읽거나 포함된 코드(bundled code)를 실행합니다. 각 스킬은 SKILL.md 파일로 구성되며, YAML 프론트매터(name, description)와 상세 지침(워크플로, 코드 패턴 등)으로 이루어져 있습니다.

Operation Architecture

flowchart TB
  subgraph UI["Streamlit (app.py)"]
    M[대화 모드 선택]
    SKUI[Skill / MCP 선택]
  end

  subgraph LLM["Amazon Bedrock"]
    BR[Bedrock Runtime]
    CB["ChatBedrock (chat.get_chat)"]
  end

  subgraph Skills["Agent Skills (skill.py)"]
    SRC["skills/*/SKILL.md"]
    SM[SkillManager]
    BSP[build_skill_prompt]
    GSI[get_skill_instructions]
  end

  subgraph LangGraphStack["LangGraph Agent (langgraph_agent.py)"]
    RLA[run_langgraph_agent]
    SG[StateGraph]
    CM[call_model]
    TN[ToolNode]
    SC[should_continue]
    BT["Built-in: execute_code, write_file, read_file, bash, upload_file_to_s3, get_current_time"]
    MCPC[MultiServerMCPClient]
  end

  subgraph MCPServers["MCP Servers (mcp_config.py)"]
    T[tavily / use-aws]
    R[knowledge base]
    AWS[aws_documentation]
    WF[web_fetch / korea_weather / trade_info]
    OTH[slack / notion / drawio / browser-use / ...]
  end

  subgraph Storage["Artifacts / S3"]
    ART[artifacts/]
    S3[(S3)]
  end

  M --> RLA
  SKUI -->|skill_list| BSP
  SKUI -->|mcp_servers| MCPC

  RLA --> SG
  SG --> CM
  CM --> SC
  SC -->|tool_calls| TN
  TN --> CM
  CM --> CB
  CB --> BR
  TN --> BT
  TN --> GSI
  RLA --> MCPC
  BSP -->|system_prompt| CM
  GSI --> SM
  SM --> SRC
  MCPC --> MCPServers
  BT --> ART
  BT --> S3

| 모드 | 모듈 | 설명 | |------|------|------| | 일상적인 대화 | chat.general_conversation | 대화 이력 + ChatBedrock 스트리밍 | | RAG | chat.run_rag_with_knowledge_base | Bedrock Knowledge Base 검색(retrieve) 후 ChatBedrock으로 답변 생성 | | Agent | langgraph_agent.run_langgraph_agent | LangGraph StateGraph + built-in tools + MCP + Skills (단일 턴) | | Agent (Chat) | langgraph_agent.run_langgraph_agent | Agent와 동일 + LangGraph checkpointer로 대화 이력 유지 | | 번역하기 | chat.translate_text | 한국어 ↔ 영어 번역 | | 이미지 분석 | chat.summarize_image | ChatBedrock 멀티모달 (이미지 + 텍스트) 분석 |

Progressive Disclosure

시스템 프롬프트에는 스킬의 이름과 설명만 XML 형태로 포함하고, 상세 지침은 agent가 get_skill_instructions 도구를 호출하여 필요할 때만 로드합니다. 이를 통해 프롬프트 크기를 최소화하면서도 agent가 다양한 스킬을 활용할 수 있습니다.

  
    pdf
    PDF 파일 읽기/병합/분할/OCR/폼 처리 등
  
  ...

스킬의 구조

각 스킬은 SKILL.md 파일 하나가 핵심이며, 필요에 따라 scripts/, references/, assets/ 등의 보조 폴더를 포함할 수 있습니다.

skills/
├── pdf/
│   ├── SKILL.md          # YAML 프론트매터 + 상세 지침
│   └── assets/           # 폰트 등 보조 리소스
├── notion/
│   └── SKILL.md
└── xlsx/
    └── SKILL.md

SKILL.md는 아래와 같이 YAML 프론트매터와 마크다운 본문으로 구성됩니다.

---
name: pdf
description: PDF 파일 처리를 위한 스킬
---

# PDF Processing Guide

## Overview
이 가이드는 Python 라이브러리를 사용한 PDF 처리 작업을 다룹니다.
execute_code 도구로 아래의 Python 코드를 실행하세요.
...

스킬의 종류

스킬은 베이스 스킬과 플러그인 스킬 두 가지로 구분됩니다.

• 베이스 스킬 (application/skills/): Agent 모드에서 공통으로 사용하는 스킬입니다. 플러그인 모드에서도 기본으로 병합되어 함께 제공됩니다.

| 스킬 | 설명 | |------|------| | pdf | PDF 읽기/병합/분할/OCR/폼 처리 | | notion | Notion API를 통한 페이지/DB/블록 관리 | | memory-manager | MEMORY.md 기반 대화 메모리 관리 | | docx | Word 문서 생성/편집/분석 | | xlsx | 스프레드시트 작업/모델링 | | pptx | PowerPoint 읽기/편집/생성 | | myslide | AWS 테마 프레젠테이션 생성 | | retrieve | Bedrock Knowledge Base RAG 검색 | | skill-creator | 새로운 스킬 설계/패키징 가이드 |

• 플러그인 스킬 (application/plugins//skills/): 특정 플러그인 모드에서만 활성화되는 스킬입니다.

| 플러그인 | 스킬 | 설명 | |----------|------|------| | productivity | memory-management | 약어/별칭 해석 포함 메모리 관리 | | productivity | task-management | TASKS.md 기반 작업 관리 | | frontend-design | frontend-design | 프론트엔드 UI 구현 가이드 | | enterprise-search | search-strategy | 질의 분해/다중 소스 검색 전략 | | enterprise-search | knowledge-synthesis | 다중 소스 결과 통합/출처 부여 | | enterprise-search | source-management | MCP 검색 소스 연결/우선순위 |

스킬의 동작 흐름

[skill.py](./application/skill.py)에서 구현된 스킬의 동작 흐름은 다음과 같습니다.

1. 스킬 탐색: SkillManager가 스킬 디렉토리를 스캔하여 SKILL.md의 YAML 프론트매터(이름, 설명)를 레지스트리에 등록합니다.
2. 프롬프트 구성: build_skill_prompt()가 활성화된 스킬의 이름/설명을 `` XML로 시스템 프롬프트에 포함합니다.
3. 지침 로드: 사용자 요청에 맞는 스킬이 있으면 agent가 get_skill_instructions 도구를 호출하여 상세 지침을 로드합니다.
4. 작업 수행: 로드된 지침에 따라 execute_code, write_file 등의 도구를 사용하여 작업을 수행합니다.
5. 결과 전달: 결과 파일이 있으면 upload_file_to_s3로 업로드하여 URL을 제공합니다.

활성화할 스킬은 config.json의 default_skills(베이스)와 plugin_skills(플러그인별)에서 설정하며, Streamlit UI에서도 체크박스로 선택할 수 있습니다.

LangGraph에서 Skill의 구현

[chat.py](./application/chat.py)의 runlanggraphagent는 사용자의 요청(query)를 Agent를 이용해 수행합니다. 여기서는 [app.py](./application/app.py)에서 선택한 MCP 서버의 리스트에서 mcp.json을 생성하여 serverparams을 추출하고, MCP tool과 built-in tool을 추출하여 agent를 생성합니다. built-in tool에는 skill을 위한 getskillinstructions과 executecode, writefile, readfile 들이 있습니다.

async def run_langgraph_agent(query, mcp_servers):
    mcp_json = mcp_config.load_selected_config(mcp_servers)
    server_params = langgraph_agent.load_multiple_mcp_server_parameters(mcp_json)

    client = MultiServerMCPClient(server_params)        
    tools = await client.get_tools()

    builtin_tools = langgraph_agent.get_builtin_tools()
    tools = tools + builtin_tools
        
    app = langgraph_agent.buildChatAgent(tools)
    config = {
        "recursion_limit": 50,
        "configurable": {"thread_id": user_id},
        "tools": tools,
        "system_prompt": None
    }            
    inputs = {
        "messages": [HumanMessage(content=query)]
    }
            
    result = ""
    async for stream in app.astream(inputs, config, stream_mode="messages"):
        message = stream[0]    
        for content_item in message.content:
            if content_item.get('type') == 'text':
                text_content = content_item.get('text', '')
                result += text_content
                                
    return result

[langgraphagent.py](./application/langgraphagent.py)의 getbuiltintools은 skill과 관련된 tool 들의 리스트를 리턴합니다. 이 tool중에 getskillinstructions은 등록된 skill에 대한 정보를 리턴합니다.

def get_builtin_tools():
    """Return the list of built-in tools for the skill-aware agent."""
    return [execute_code, write_file, read_file, upload_file_to_s3, get_skill_instructions]

@tool
def get_skill_instructions(skill_name: str) -> str:
    """Load the full instructions for a specific skill by name.

    Use this when you need detailed instructions for a task that matches
    one of the available skills listed in the system prompt.

    Args:
        skill_name: The name of the skill to load (e.g. 'pdf').

    Returns:
        The full skill instructions, or an error message if not found.
    """
    instructions = skill_manager.get_skill_instructions(skill_name)
    if instructions:
        return instructions
    available = ", ".join(skill_manager.registry.keys())
    return f"Skill '{skill_name}'을 찾을 수 없습니다. 사용 가능한 skill: {available}"

[langgraphagent.py](./application/langgraphagent.py)에서는 Skill을 관리하기 위한 SkillManager를 정의합니다. SkillManager가 initiate될 때에 discover()는 skill directory에 있는 skill 정보를 가져와서 registry에 등록합니다. 등록된 skill 정보는 availableskills_xml를 통해 prompt에서 활용합니다.

@dataclass
class Skill:
    name: str
    description: str
    instructions: str
    path: str

class SkillManager:
    """Discovers, loads and selects Agent Skills following the Anthropic spec."""

    def __init__(self, skills_dir: str = SKILLS_DIR):
        self.registry: dict[str, Skill] = {}
        self._discover()

    def _discover(self):
        """Scan skills directory and load metadata (frontmatter only)."""
        for entry in os.listdir(self.skills_dir):
            skill_md = os.path.join(self.skills_dir, entry, "SKILL.md")
            if os.path.isfile(skill_md):
                meta, instructions = self._parse_skill_md(skill_md)
                skill = Skill(
                    name=meta.get("name", entry),
                    description=meta.get("description", ""),
                    instructions=instructions,
                    path=os.path.join(self.skills_dir, entry),
                )
                self.registry[skill.name] = skill

    # ---- prompt generation (progressive disclosure) ----
    def available_skills_xml(self) -> str:
        """Generate  XML for the system prompt (metadata only)."""
        if not self.registry:
            return ""
        lines = [""]
        for s in self.registry.values():
            lines.append("  ")
            lines.append(f"    {s.name}")
            lines.append(f"    {s.description}")
            lines.append("  ")
        lines.append("")
        return "\n".join(lines)

    def get_skill_instructions(self, name: str) -> Optional[str]:
        """Return full instructions for a skill (loaded on demand)."""
        skill = self.registry.get(name)
        return skill.instructions if skill else None

skill_manager = SkillManager()

LangGraph의 agent는 아래와 같이 구현합니다. 여기서 buildsystemprompt은 SKILL에 대한 정보인 skillsxml과 SKILLUSAGE_GUIDE를 아래와 같이 포함합니다.

async def call_model(state: State, config):
    last_message = state['messages'][-1]

    tools = config.get("configurable", {}).get("tools", None)
    custom_prompt = config.get("configurable", {}).get("system_prompt", None)

    system = build_system_prompt(custom_prompt)

    chatModel = chat.get_chat()
    model = chatModel.bind_tools(tools)

    prompt = ChatPromptTemplate.from_messages([
        ("system", system),
        MessagesPlaceholder(variable_name="messages"),
    ])
    chain = prompt | model
    response = await chain.ainvoke(messages)
    return {"messages": [response], "image_url": image_url}

SKILL_USAGE_GUIDE = (
    "\n## Skill 사용 가이드\n"
    "위의 에 나열된 skill이 사용자의 요청과 관련될 때:\n"
    "1. 먼저 get_skill_instructions 도구로 해당 skill의 상세 지침을 로드하세요.\n"
    "2. 지침에 포함된 코드 패턴을 execute_code 도구로 실행하세요.\n"
    "3. 생성된 파일은 upload_file_to_s3로 업로드하고 URL을 사용자에게 전달하세요.\n"
    "4. skill 지침이 없는 일반 질문은 직접 답변하세요.\n"
)
def build_system_prompt(custom_prompt: Optional[str] = None) -> str:
    """Assemble the full system prompt with available skills metadata."""
    if custom_prompt:
        base = custom_prompt
    else:
        base = BASE_SYSTEM_PROMPT

    skills_xml = skill_manager.available_skills_xml()
    if skills_xml:
        return f"{base}\n\n{skills_xml}\n{SKILL_USAGE_GUIDE}"
    return base

Skill의 생성

OpenClaw의 [skill-creator](./application/skills/skill-creator/SKILL.md)를 참조하여 skill을 생성할 수 있도록 하였습니다.

├── SKILL.md (must required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

배포하기

EC2로 배포하기

AWS console의 EC2로 접속하여 Launch an instance를 선택합니다. [Launch instance]를 선택한 후에 적당한 Name을 입력합니다. (예: es) key pair은 "Proceed without key pair"을 선택하고 넘어갑니다.

Instance가 준비되면 [Connet] - [EC2 Instance Connect]를 선택하여 아래처럼 접속합니다.

이후 아래와 같이 python, pip, git, boto3를 설치합니다.

sudo yum install python3 python3-pip git docker -y
pip install "boto3>=1.43.32" "botocore>=1.43.32"

Workshop의 경우에 아래 형태로 된 Credential을 복사하여 EC2 터미널에 입력합니다.

아래와 같이 git source를 가져옵니다.

git clone https://github.com/kyopark2014/agent-skills

아래와 같이 installer.py를 이용해 설치를 시작합니다.

cd agent-skills && python3 installer.py

API 구현에 필요한 credential은 secret으로 관리합니다. 따라서 설치시 필요한 credential 입력이 필요한데 아래와 같은 방식을 활용하여 미리 credential을 준비합니다.

• 일반 인터넷 검색: Tavily Search에 접속하여 가입 후 API Key를 발급합니다. 이것은 tvly-로 시작합니다.
• 날씨 검색: openweathermap에 접속하여 API Key를 발급합니다. 이때 price plan은 "Free"를 선택합니다.

설치가 완료되면 CloudFront로 접속하여 Agent를 실행합니다.

인프라가 더이상 필요없을 때에는 uninstaller.py를 이용해 제거합니다.

python uninstaller.py

배포된 Application 업데이트 하기

AWS console의 EC2로 접속하여 Launch an instance를 선택하여 아래와 같이 아래와 같이 "app-for-agent-skills"라는 이름을 가지는 instance id를 선택합니다.

[connect]를 선택한 후에 Session Manager를 선택하여 접속합니다.

이후 아래와 같이 업데이트한 후에 다시 브라우저에서 확인합니다.

cd ~/agent-skills/ && sudo ./update.sh

실행 로그 확인

EC2 console에서 "app-for-agent-skills"라는 이름을 가지는 instance id를 선택 한 후에, EC2의 Session Manager를 이용해 접속합니다.

먼저 아래와 같이 현재 docker container ID를 확인합니다.

sudo docker ps

이후 아래와 같이 container ID를 이용해 로그를 확인합니다.

sudo docker logs [container ID]

실제 실행시 결과는 아래와 같습니다.

Local에서 실행하기

AWS 환경을 잘 활용하기 위해서는 AWS CLI를 설치하여야 합니다. EC2에서 배포하는 경우에는 별도로 설치가 필요하지 않습니다. Local에 설치시는 아래 명령어를 참조합니다.

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" 
unzip awscliv2.zip
sudo ./aws/install

AWS credential을 아래와 같이 AWS CLI를 이용해 등록합니다.

aws configure

설치하다가 발생하는 각종 문제는 Kiro-cli를 이용해 빠르게 수정합니다. 아래와 같이 설치할 수 있지만, Windows에서는 Kiro 설치에서 다운로드 설치합니다. 실행시는 셀에서 "kiro-cli"라고 입력합니다.

curl -fsSL https://cli.kiro.dev/install | bash

venv로 환경을 구성하면 편리하게 패키지를 관리합니다. 아래와 같이 환경을 설정합니다.

python -m venv .venv
source .venv/bin/activate

이후 다운로드 받은 github 폴더로 이동한 후에 아래와 같이 필요한 패키지를 추가로 설치 합니다.

pip install -r requirements.txt

이후 아래와 같은 명령어로 streamlit을 실행합니다.

streamlit run application/app.py

MCP

Plugin의 Connector는 MCP를 이용해 구현합니다. 이때 필요한 MCP 설정은 아래를 참조합니다.

• Slack: Slack 내용을 조회하고 메시지를 보낼 수 있습니다. SLACKTEAMID, SLACKBOT_TOKEN으로 설정합니다.

• Tavily: Tavily를 이용해 인터넷을 검색합니다. [installer.py](./installer.py)에서 secret으로 설정후에 [utils.py](./application/utils.py)에서 TAVILYAPI_KEY로 등록하여 활용합니다.

• RAG: Knowledge Base를 이용해 RAG를 활용합니다. IAM 인증을 이용하므로 별도로 credential 설정하지 않습니다.

• webfetch: playwright기반으로 url의 문서를 markdown으로 불러올 수 있습니다. 별도 인증이 필요하지 않습니다.

• Google 메일/캘린더: 구글 메일을 조회하거나 보낼 수 있습니다. Gog CLI를 설치하여 google 인증을 통해 활용합니다.

• Notion: Notion을 읽거나 쓸 수 있습니다. [installer.py](./installer.py)에서 secret으로 설정후에 [utils.py](./application/utils.py)에서 NOTIONTOKEN을 등록하여 활용합니다.

• textextraction: 이미지의 텍스트를 추출합니다. 별도 인증이 필요하지 않습니다.

Telegram과 연동

python-telegram-bot을 활용하여, polling 방식으로 Telegram 서버에 주기적으로 새 메시지를 확인하고, 메시지가 오면 chat.runlanggraphagent를 호출해 Agent 응답을 생성한 뒤 다시 Telegram으로 보내줍니다. 상세한 코드는 [telegrambot.py](./application/telegram_bot.py)을 참조합니다.

Telegram Token을 아래와 같이 생성합니다.

1. Telegram에서 @BotFather와 대화 시작하거나, https://t

…

Source & license

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

• Author: kyopark2014
• Source: kyopark2014/agent-skills
• License: MIT

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