한 줄 정의
마크다운 기반 스킬 정의는 별도의 인프라 구축이나 코어 엔진 수정 없이 순수한 마크다운(.md) 문서 형태로 코딩 에이전트 및 에이전트형 AI의 동작 지침, 절차적 규칙, 프롬프트 트리거 및 포맷 구조를 선언하여 기능을 확장하는 실용적 에이전트 스킬 구축 기법이다.
핵심 요지
- 자연어 입력과
.md파일 출력의 선언적 통제: 에이전트의 지능적 처리 능력을 복잡한 데이터베이스나 백엔드 코드 변경 없이 마크다운 문서 형태의 지침(Instructions)만으로 제어한다 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md). - 투명한 데이터 소유권 및 제로-인프라 구성: 상시 가동 서버나 전용 DB 없이 Git 저장소 내 일반 텍스트 파일로 스킬과 데이터를 관리하므로 특정 구독 서비스나 클라우드 플랫폼에 구속되지 않고 영구 지속 가능하다 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md).
- 에이전트 도구 생태계와의 상호운용성: Claude Code, Cursor, Kiro 등 도구 종류에 따라
.claude/skills/SKILL.md,POWER.md, 혹은 AGENTS md 형태의 마크다운 레코드로 직관적인 스킬 확장 환경(Skill Surface)을 제공한다 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md). - 고난도 추론과 작업 분리(Head-Worker 패턴): 스킬 지침 내부에서 의사결정은 고성능 모델(Claude Opus)이 조율하고, 수집/포맷 변환 등 기계적 데이터 I/O는 하위 워커 에이전트(Claude Sonnet 6개 등)에 이관하도록 명시하여 컨텍스트 윈도우 비용을 최적화한다 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md).
- 우아한 성능 저하(Graceful Degradation) 및 독립성: 외부 integration(MCP, GitHub CLI
gh등)이 미설치된 상황에서도 전체 시스템 파손 없이 기본 기능으로 유연하게 대처하도록 스킬 절차를 설계한다 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md).
상세
1. 개요 및 설계 철학
마크다운 기반 스킬 정의는 COG(huytieu/COG-second-brain, MIT 라이선스) 시스템과 같은 세컨드 브레인 및 하네스 엔지니어링 환경에서 대표적으로 활용된다 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md). 스킬이란 에이전트가 특정 도메인의 작업(브레인덤프, 일일 브리핑, 주간 리뷰 등)을 수행할 때 참고하는 표준 행동 수칙(Playbook)이다.
스킬 구현 시 백엔드 코드 작성 대신 프롬프트, 트리거 조건, 세부 실행 단계(Steps), 출력 포맷 규격을 마크다운 파일 형태로 선언한다. 이를 통해 개발 지식이 부족한 사용자나 도메인 전문가도 텍스트 편집만으로 에이전트의 기능을 자유롭게 확장할 수 있다 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md).
2. 주요 구조 및 도구별 확장 방식
에이전트 환경에 따라 마크다운 스킬 정의의 파일 위치와 명칭은 일부 차이가 있으나 공통적으로 선언적 구조를 지닌다 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md):
- Claude Code:
.claude/skills/SKILL.md(혹은 개별 기능 단위 마크다운 문서) - Kiro:
POWER.md - 범용 에이전트 환경: AGENTS md 내 스킬 레코드 또는
.claude/agents/
마크다운 스킬 파일 내부에는 다음 요소가 체계적으로 기술된다:
- Description & Trigger: 에이전트가 어떤 자연어 입력(
I need to braindump,Give me my daily brief,Weekly review등)에서 해당 스킬을 활성화할지 정의. - Steps: 작업을 단계별로 수행하기 위한 세부 가이드라인.
- Output Format: 날짜 포맷(
📅 YYYY-MM-DD), 옵시디언 태스크(Obsidian Tasks) 이모지 포맷, 7일 이내 최신성 유지 가이드라인(7-day recency heuristic) 등 엄격한 출력 규격 명시. - Degradation Rule: GitHub CLI (
gh), Linear, Slack, PostHog 등 외부 MCP 연결이 미비할 때 단일 채널로 자동 전환하는 예외 처리 수칙.
3. 하위 워커 에이전트 오케스트레이션
마크다운 스킬 지침은 단순 프롬프트 전달을 넘어, 멀티 에이전트 협업 구조를 지시할 수 있다. COG 시스템 아키텍처에서는 고성능 메인 에이전트(Claude Opus)가 전체 추론과 전략 판단을 지배하고, 6개의 경량 워커 에이전트(Claude Sonnet)가 세부 정보 추출, 자료 수집, 파일 업데이트 등의 작업을 분담하도록 마크다운 지침으로 정의한다 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md).
워커 에이전트는 기계적 연산 결과물을 지정된 로컬 임시 디렉터리(_/tmp/_)에 저장하고 경로만 부모 에이전트에 보고함으로써, 방대한 로우 데이터가 메인 대화창의 컨텍스트를 불필요하게 차지하지 않도록 제어한다 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md).
4. 프라이머시와 자가 진화(Self-Evolving) 성찰 루프
마크다운 기반 스킬은 모델 내부 파라미터를 직접 파인튜닝(fine-tuning)하지 않고도 자가 진화하는 정보 관리 체계를 형성한다. 일상적인 아이디어 수집(Capture)이 주간 분석(Weekly review) 및 월간 데이터 통합(Consolidate my knowledge) 마크다운 스킬을 거치며 파편화된 메모에서 유기적인 프레임워크로 승격되는 성찰 루프(Reflection Loop)가 순환된다 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md).
또한 프레임워크 업데이트 시에도 사용자 원본 데이터와 .md 스킬 정의 계층이 철저히 분리되어 있어, cog-update.sh 스크립트 실행 시 백업 및 버전 충돌을 안전하게 대조·조율하며 데이터를 보존한다 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md).
예시
예시 1: 마크다운 기반 주간 리포트 생성 스킬 (SKILL.md)
아래는 COG 아키텍처 스타일의 마크다운 스킬 정의 예시이다:
---
name: weekly-review
description: 일주일간 축적된 노트를 상호 참조하여 유기적 패턴과 실행 태스크를 추출하는 주간 리뷰 스킬
triggers:
- "Weekly review"
- "주간 리뷰 해줘"
---
# Weekly Review Skill
## Overview
보관소 내 `00-inbox/` 및 `01-projects/` 폴더에 저장된 지난 7일간의 마크다운 노트를 읽고 분석하여 통찰 리포트를 작성한다.
## Execution Steps
1. **노트 수집**: 지난 7일 이내 작성된 `.md` 파일 목록을 추출한다.
2. **워커 위임 (Worker Delegation)**:
- 본문 요약 및 키워드 추출 작업은 경량 워커 에이전트(Sonnet)에 이관한다.
- 워커 결과물은 `_/tmp/weekly_summary.json_`에 수집한다.
3. **패턴 분석**: 헤드 에이전트(Opus)가 수집된 요약본을 상호 참조하여 공통 주제와 보이지 않는 연결고리를 도출한다.
4. **태스크 정리**: 미완료 항목은 Obsidian Tasks 이모지 포맷(`📅 YYYY-MM-DD`)으로 재정리한다.
5. **결과 저장**: `05-reviews/YYYY-Www.md` 경로에 마크다운 형태로 최종 출력한다.
## Fallback & Graceful Degradation
- Git 커밋 로그가 없거나 연동되지 않은 경우, 로컬 마크다운 파일의 생성/수정 시각(mtime)을 기준으로 7일 유효성을 판단한다.예시 2: 활용 시나리오 (브레인덤프에서 자동 분류까지)
- 사용자 입력:
I need to braindump입력 후 무질서한 프로젝트 아이디어와 회의 피드백 전달. - 스킬 감지: 에이전트가 저장소의 마크다운 스킬 지침을 참조하여 입력 데이터를 주제별로 분해.
- 파일 생성 및 분류: 태스크 항목은
📅 2026-08-28날짜 태그가 붙은 마크다운 노트로 정돈되어 적절한 도메인 폴더(00-inbox,01-projects등)에 수동 개입 없이 자동 분류 저장됨 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md).
충돌
현재 명시된 정보 간의 충돌 사항은 존재하지 않음. 단, 기술적 관점에서 ‘자가 진화(Self-evolving)‘라는 표현이 LLM 가중치(Weight)의 직접적인 파인튜닝을 의미하는 것으로 오해될 수 있으나, 본 마크다운 기반 스킬 아키텍처에서는 단순 파라미터 학습이 아니라 마크다운 파일에 대한 주기적인 성찰 루프(Reflection Loop) 및 텍스트 데이터의 단계적 구조화를 뜻함을 유의해야 한다 (raw/Build a Second Brain in 15 Minutes. Just Markdown, Git, and an AI Agent.md).