scientific-agent-skills 딥다이브
— 연구자의 절차를 AI가 읽고 검증할 수 있는 코드로

1프로젝트 한줄 요약

scientific-agent-skills는 생물학·화학·의학·물리·데이터 분석 등에 필요한 작업 절차를 AI 에이전트에게 전달하는 라이브러리입니다. 하나의 스킬에는 언제 사용할지, 무엇을 입력받을지, 어떤 검사를 거칠지, 어떤 코드를 호출할지가 들어 있습니다.

이 저장소에서 배우는 핵심은 전문 지식을 긴 설명으로 남기는 데서 나아가, 입력 조건과 검증 가능한 코드까지 묶는 방법입니다. 모델 자체를 학습시키는 코드보다 skills/<이름>/SKILL.md와 그 주변 파일이 중심입니다.

1-1. 한 가지 요청이 실제 파일과 연결되는 방식

예를 들어 “이 단일세포 RNA 데이터의 품질을 확인하고 군집을 나눠 줘”라는 요청을 생각해 봅시다. skills/scanpy/SKILL.md는 원본 카운트를 확인하고, 품질 검사·정규화·차원 축소·군집화로 이어지는 절차를 설명합니다. 반복되는 작업은 skills/scanpy/scripts/run_pipeline.py의 main()이 맡습니다.

사용자 요청
  → 호스트가 scanpy 스킬의 이름·설명을 바탕으로 선택
  → SKILL.md에서 입력 조건과 작업 순서 확인
  → 필요한 참고 문서와 보조 코드 읽기
  → 호스트의 허용된 도구로 분석 수행
  → 결과 파일과 검증 근거를 사용자에게 설명

이 흐름의 스킬 선택과 도구 호출은 호스트의 책임입니다. 저장소 루트의 plugin.json은 이름·버전·작성자 등을 선언하지만, 요청을 받아 작업을 배정하는 상시 실행 서버를 정의하지는 않습니다. 표준 호환성을 선언하는 것과 모든 호스트에서 같은 행동을 보장하는 것은 구분해야 합니다.

1-2. 어떤 독자가 무엇을 얻는가

2왜 주목받는가

2-1. 범용 에이전트에 분야별 작업 절차를 더한다

2026-10-23 GitHub 기준 스타는 54,016개, 포크는 4,767개입니다. GitHub Trending Weekly 5위라는 선정 맥락과 함께 보면 관심의 크기를 보여 줍니다. 다만 이 수치만으로 연구 정확도나 생산성 향상률까지 알 수는 없습니다.

README는 프로젝트가 Claude Scientific Skills에서 Scientific Agent Skills로 이름을 바꾸었다고 설명합니다. 특정 클라이언트 이름을 벗고 Agent Skills 표준을 따르는 호스트를 대상으로 한다는 점이 확산에 유리합니다. 실제로 루트에는 Agent Plugins 1.0.0 스키마를 지정한 plugin.json이 있고, 스킬은 독립된 폴더로 배치되어 있습니다.

소스 구조에서 읽을 수 있는 인기 요인은 세 가지입니다. 첫째, 연구 도구의 사용법을 찾는 비용을 줄입니다. 둘째, 스킬별로 선택해 가져가기 쉽습니다. 셋째, 절차 설명에 보조 코드와 검사 조건이 붙습니다. 이는 구조를 근거로 한 해석이며, 트렌딩 순위 상승의 인과관계를 측정한 결과는 아닙니다.

2-2. “코드를 만들어 줘”에서 빠지기 쉬운 조건을 적어 둔다

skills/scanpy/scripts/_common.py의 prepare_counts()는 카운트의 수치 조건과 기록된 변환 이력을 검사해 잘못된 입력을 거부합니다. skills/genomic-coordinates/scripts/convert_coords.py의 convert_one()은 변환할 수 없는 구간을 억지로 정상 값으로 바꾸지 않고 상태로 돌려줍니다.

과학 코딩에서 재사용할 가치가 큰 부분은 정상 입력의 계산식뿐 아니라, 그 계산을 적용하면 안 되는 조건까지 명시한 코드입니다. 이 저장소는 그러한 조건을 문서와 함수 양쪽에 두는 사례를 제공합니다.

2-3. 경쟁하는 접근 방식과 비교하기

비교 기준은 “어느 제품이 더 똑똑한가”보다 어떤 층을 맡는가입니다. 다음 표는 구조와 책임의 차이를 보여 줍니다. 각 제품의 최신 기능을 모두 비교한 성능표는 아닙니다.

2-4. 소개 수치를 실제 구성과 대조하기

README의 2.72.0 변경 안내는 문서용 docx·pdf·pptx·xlsx 스킬 네 개가 더 이상 포함되지 않는다고 설명합니다. 이전 2.71.0 소개의 181개와 현재 177개의 차이는 이 맥락에서 읽어야 합니다. 개수가 바뀌었다는 이유만으로 기능 전체의 후퇴나 품질 향상을 단정할 수는 없습니다.

3기술 스택 전체 지도

3-1. 백엔드에 해당하는 부분: Python 보조 도구와 검증 계층

루트에 웹 API 서버의 엔트리포인트는 없습니다. 실질적인 실행 코드는 개별 스킬의 Python CLI와 저장소 관리 도구에 분산되어 있습니다. 루트 pyproject.toml의 프로젝트 버전은 2.72.0, 관리 도구의 Python 요구 조건은 >=3.13입니다.

# pyproject.toml 발췌
[project]
name = "scientific-agent-skills"
version = "2.72.0"
requires-python = ">=3.13"
dependencies = [
    "cisco-ai-skill-scanner>=2.0.12",
    "pytest>=9.1.1",
    "python-dotenv>=1.0.0",
]

3-2. 과학 계산 패키지는 스킬별로 다르다

tests/skill-requirements.toml에는 174개 스킬의 환경 항목이 있습니다. 이것은 174개를 한 환경에 설치하는 목록이 아니라, 테스트 실행기가 스킬마다 별도 환경을 만들 때 읽는 설정입니다. 모든 항목에 버전이 고정된 것은 아닙니다.

스킬 모음 전체의 Python 버전과 개별 분석에 필요한 Python 버전은 다르므로, 실행 환경은 선택한 스킬의 계약을 기준으로 정해야 합니다. 이 구분을 놓치면 “최신 Python을 깔았는데 설치가 실패한다”는 문제에 부딪힐 수 있습니다.

3-3. 프론트엔드: 호스트 UI와 문서가 접점이다

루트에는 package.json·Cargo.toml·go.mod·Dockerfile이 없습니다. 추적된 JavaScript는 두 파일·223줄이며, skills/fictiv/scripts/list_dropdown_options.js와 skills/fictiv/scripts/quote_state.js입니다. 이것을 저장소 전체의 웹 프론트엔드로 해석할 근거는 없습니다.

독자가 만나는 화면은 주로 에이전트 호스트의 UI와 GitHub의 Markdown 문서입니다. docs/skill-guides/와 docs/images/는 스킬을 설명하는 자료입니다. 별도 React 앱을 빌드해 스킬을 서비스하는 구조로 읽으면 실제 설계와 멀어집니다.

3-4. 인프라·빌드: 실행 파일보다 검증과 릴리스가 중심

.github/workflows/release.yml은 main의 pyproject.toml 변경 또는 수동 실행에 반응합니다. 버전을 읽어 v2.72.0 같은 태그 이름을 만들고, 같은 태그가 이미 있으면 생성을 건너뜁니다. 관리 코드와 문서 패키지에 맞춘 배포 자동화입니다.

4아키텍처 심화 분석

4-1. 전체 구조: 읽는 경로와 검사하는 경로

아래 도식에서 위쪽은 사용 경로, 아래쪽은 유지보수 경로입니다. 호스트가 스킬을 발견하고 필요한 파일을 읽습니다. 저장소의 테스트와 보안 검사기는 배포할 파일의 구조와 일부 동작을 확인합니다. 둘을 연결하되 같은 실행 흐름으로 혼동하지 않는 것이 출발점입니다.

이 구조의 장점은 지식·계산·검증의 경계를 파일로 드러내어, 한 부분을 읽거나 바꿀 때 확인할 범위를 좁힐 수 있다는 데 있습니다. 다만 폴더 경계 자체가 권한 격리나 보안 경계를 만들어 주지는 않습니다.

4-2. 패턴 ① 작은 진입 문서와 필요할 때 읽는 참고 자료

진입점은 짧게, 상세 내용은 밖으로라는 패턴입니다. 각 SKILL.md 앞의 YAML frontmatter에는 이름·설명·호환 조건·버전 등이 들어갑니다. 본문은 작업을 안내하고, 긴 설명은 references/로 연결합니다. 177개 중 176개 스킬에 참고 문서 폴더가 있습니다.

# skills/scanpy/SKILL.md의 일부 필드
name: scanpy
license: BSD-3-Clause
metadata:
  version: "1.8"
  last-reviewed: "2026-10-01"
  upstream-version: "1.12.4"
  skill-author: K-Dense Inc.

description은 “어떤 작업에 이 스킬을 쓸지”를 설명합니다. compatibility는 필요한 환경을 설명합니다. metadata.version은 스킬 문서·도구 묶음의 버전이고, upstream-version은 대상으로 삼은 외부 라이브러리 버전입니다. 위 예의 1.8과 1.12.4는 서로 다른 대상을 가리킵니다.

이 분리를 흔히 점진적 공개라고 부릅니다. 전체 매뉴얼을 한꺼번에 읽히는 대신 현재 작업에 필요한 설명을 따라갑니다. 실제 로딩 정책은 호스트가 구현하므로, 이 저장소만으로 토큰 사용량이나 선택 정확도를 측정할 수는 없습니다.

이 설계의 검증 지점은 tests/_meta/test_repo_contract.py의 AgentPluginTests.test_skills_component_is_discoverable()입니다. 직계 하위 폴더의 SKILL.md 존재를 확인합니다. tests/_contract/structure.py의 frontmatter_problems()와 length_problems()는 문서 계약을 검사합니다. 현재 가장 긴 SKILL.md는 499줄입니다.

배울 점: 입력 문서가 커질 때 무작정 요약하기보다, 선택에 필요한 정보와 실행에 필요한 정보를 분리해 보세요. 단, 너무 잘게 나누면 링크 관리 비용이 생기므로 link_problems()처럼 내부 참조도 검사해야 합니다.

4-3. 패턴 ② 모든 좌표를 하나의 기준 형식으로 바꾼다

skills/genomic-coordinates/scripts/_common.py의 Convention은 @dataclass(frozen=True)로 정의되어 있습니다. 형식 이름, 시작 번호 base, 끝 제외 여부를 나타내는 half_open을 한 객체에 담고, 생성 뒤 필드의 재할당을 막습니다.

핵심은 아래 두 함수입니다. 입력을 0부터 시작하고 끝은 포함하지 않는 구간으로 바꾼 뒤, 목적 형식으로 되돌립니다. 형식 A와 B의 조합마다 별도 계산식을 만드는 부담을 줄입니다.

# skills/genomic-coordinates/scripts/_common.py 발췌
def to_canonical(conv: Convention, start: int, end: int) -> tuple[int, int]:
    start0 = start - conv.base
    end0 = end if conv.half_open else end - conv.base + 1
    return start0, end0

def from_canonical(conv: Convention, start0: int, end0: int) -> tuple[int, int]:
    start = start0 + conv.base
    end = end0 if conv.half_open else end0 + conv.base - 1
    return start, end

convert_coords.py의 convert_one()은 계산 결과에 status와 detail을 붙입니다. 길이 0인 BED 구간은 반열린 형식에서는 zero_length, 일반적인 포함 구간 변환에서는 unrepresentable로 보고합니다. 삽입 지점의 의미를 모르는 상태에서 길이 1인 구간으로 바꾸지 않습니다.

tests/genomic-coordinates/test_scripts.py에는 test_round_trip_through_canonical_is_identity(), test_length_is_convention_independent()가 있습니다. 특정 예제 하나뿐 아니라 왕복하면 원래 값으로 돌아온다는 성질을 검사합니다. 좌표 번호 변환은 서로 다른 참조 유전체 사이의 위치 이동인 liftover까지 해결하지는 않습니다.

4-4. 패턴 ③ 데이터의 의미와 원본을 보존하는 파이프라인

Scanpy 보조 코드의 중심은 skills/scanpy/scripts/_common.py입니다. validate_counts()는 값이 유한하고 음수가 없으며 정수 값인지 확인하고, 기본 설정에서는 각 세포의 합계가 양수인지도 검사합니다. 희소 행렬이면 전체를 밀집 배열로 바꾸지 않고 저장된 matrix.data를 검사합니다.

정수처럼 생긴 값이라고 원본이라는 사실까지 증명되지는 않습니다. prepare_counts()는 선택한 카운트를 복사하여 adata.X와 adata.layers["counts"]에 둡니다. 원본 레이어를 지정하지 않은 상태에서 log1p 기록이 있거나 보관된 카운트와 X가 다르면, 레이어를 명시적으로 선택하도록 요구합니다.

normalize_hvg()의 기본값은 target_sum=1e4, n_top_genes=2000, flavor="seurat"입니다. seurat_v3 계열은 원본 카운트로 변동이 큰 유전자를 고르고, seurat 계열은 로그 정규화 뒤에 고릅니다. 같은 함수 호출 이름이라도 입력 표현에 따라 순서가 달라집니다.

# normalize_hvg()의 핵심 분기 발췌
count_flavor = flavor in {"seurat_v3", "seurat_v3_paper"}
if count_flavor:
    sc.pp.highly_variable_genes(adata, layer="counts", n_top_genes=n_top_genes,
                                flavor=flavor, batch_key=batch_key)
sc.pp.normalize_total(adata, target_sum=target_sum)
sc.pp.log1p(adata)
if not count_flavor:
    sc.pp.highly_variable_genes(adata, n_top_genes=n_top_genes,
                                flavor=flavor, batch_key=batch_key)

run_pipeline.py의 main()은 품질 검사 뒤 변동이 큰 유전자만 뽑은 work 객체로 PCA·이웃 그래프·군집화를 수행합니다. 이후 군집과 임베딩을 전체 유전자가 있는 객체로 옮깁니다. 계산에 쓴 부분집합 때문에 뒤의 유전자 비교 대상이 사라지는 문제를 줄이는 설계입니다.

이 계약은 tests/scanpy/test_numerical_contracts.py의 test_counts_and_raw_are_independent_and_normalization_is_numerically_correct()가 검사합니다. 밀집·희소 입력 모두에서 정규화 식을 비교하고, 스케일링 뒤에도 원본 카운트와 raw가 보존되는지 확인합니다. 생물학적 발견이 맞다는 검증과는 범위가 다릅니다.

4-5. 패턴 ④ 스킬마다 테스트 프로세스와 의존성 환경을 나눈다

여러 스킬이 skills/<이름>/scripts/_common.py 형태의 경로에 같은 이름의 모듈을 둡니다. 서로 다른 스킬의 테스트를 같은 Python 프로세스에 모으면 먼저 불러온 모듈을 다른 스킬에서도 참조할 수 있습니다. 실제 코드보다 우연히 잡힌 import 순서를 검사하는 셈입니다.

tests/conftest.py의 pytest_sessionstart()는 두 개 이상 스킬을 한 세션에서 수집하면 pytest.UsageError를 발생시킵니다. tests/run_all.py의 main()은 각 스킬을 subprocess.run()으로 분리하고, isolated_command()는 추가로 환경을 분리할 명령을 만듭니다.

# tests/run_all.py의 isolated_command() 핵심 구성
command = [
    "uv", "run",
    "--no-project",
    "--python", entry.get("python", default_python),
    "--with", "pytest",
]
# 스킬별 packages에 있는 패키지를 차례로 추가
for package in entry.get("packages", []):
    command += ["--with", package]
return [*command, "python", "-m", "pytest", target, *pytest_args]

--no-project는 프로젝트 환경에 기대지 않도록 합니다. 기본 실행은 프로세스만 분리하고, --isolated를 지정해야 스킬별 패키지·인터프리터 환경까지 나눕니다. 가상환경과 프로세스 격리도 파일 접근을 막는 샌드박스는 아닙니다.

공통 검사 자체는 tests/_contract/에 모으고, tests/conftest.py의 _install_contract()가 이를 skill_contract라는 고유 이름으로 불러옵니다. 공통 규칙은 공유하되 스킬별 일반 모듈 이름은 충돌하지 않게 하려는 선택입니다.

5디렉토리 구조 해부

5-1. 폴더 이름보다 배포 경계를 먼저 보기

skills/는 호스트에 전달할 내용입니다. tests/는 그 내용을 검사하는 유지보수 도구입니다. docs/images/는 사람에게 보여 주는 설명 그림입니다. 이 저장소는 테스트와 그림을 스킬 폴더 밖에 두어, 에이전트가 읽는 패키지와 개발 자료를 나눕니다.

모든 스킬의 구성이 같은 것은 아닙니다. 177개 모두 SKILL.md가 있고, 121개에는 scripts/, 176개에는 references/, 43개에는 assets/가 있습니다. 보조 코드가 없는 스킬도 설명서로서 역할을 할 수 있습니다.

5-2. 코드 규모를 직접 해석하기

아래는 커밋 593377b의 Git 추적 파일을 대상으로 줄바꿈 바이트를 센 값입니다. 빈 줄·주석·문자열을 포함하며, 실행문만 센 수치가 아닙니다. 이미지·압축 파일의 바이트를 코드 줄 수로 세지 않았고, Markdown 안의 코드 예제는 Markdown 쪽에 포함됩니다.

Python 248,635줄 중 skills/는 167,389줄·531개 파일, tests/는 79,276줄·237개 파일, 루트 검사기 두 개와 scripts/의 관리 도구는 합계 1,970줄·3개 파일입니다. 테스트 줄 수가 많다는 사실은 확인할 수 있지만, 커버리지 측정값으로 바꿔 말할 수는 없습니다.

전체 추적 파일은 2,780개이고, 그 안에는 PNG 177개도 있습니다. 따라서 전체 파일 용량을 곧바로 실행 코드의 규모나 모델 크기로 해석하면 안 됩니다. 개별 스킬 테스트 폴더는 155개이며, 보조 스크립트 폴더를 가진 121개 스킬에는 각각 대응하는 테스트 폴더가 있습니다.

# 같은 범위로 Python 줄 수를 세는 읽기 전용 예시
from pathlib import Path
import subprocess

files = subprocess.check_output(["git", "ls-files"], text=True).splitlines()
python_files = [Path(name) for name in files if name.endswith(".py")]
lines = sum(path.read_bytes().count(b"\n") for path in python_files)
print(len(python_files), lines)
# 커밋 593377b 기준: 771 248635

6학습 포인트 (기술별)

6-1. Python: 작은 계산 함수와 입출력의 경계를 나누기

genomic-coordinates의 to_canonical()과 from_canonical()은 파일을 열거나 API를 부르지 않습니다. 입력을 받아 계산 결과를 돌려주므로 손으로 예상값을 만들기 쉽습니다. build_parser()와 main()은 명령줄 입력과 출력 형식, 종료 코드를 담당합니다.

이처럼 계산과 입출력을 나누면 “결과가 틀렸다”와 “파일을 읽지 못했다”를 구분하기 쉽습니다. 학습할 때는 convert_one()이 반환하는 사전의 length·status·detail을 먼저 읽고, 마지막에 CLI 옵션을 따라가 보세요.

6-2. 데이터 처리: 원본·변환본·메타데이터를 함께 관리하기

AnnData는 행렬만 담는 통이 아닙니다. X는 현재 표현, obs는 세포별 정보, var는 유전자별 정보, layers는 같은 축의 다른 표현을 담습니다. raw라는 이름도 자동으로 실험 원본을 뜻하지 않습니다. 이 스킬에서는 전체 유전자의 로그 정규화 스냅샷으로 설정합니다.

좋은 데이터 파이프라인은 배열의 모양뿐 아니라 그 값이 원본인지, 정규화되었는지, 어떤 집단을 나타내는지까지 보존해야 합니다. 이 관점은 금융 시계열·로그 분석·이미지 전처리에도 그대로 적용됩니다.

6-3. 테스트: 구현과 같은 코드 대신 지켜야 할 성질을 검사하기

좌표 변환의 왕복 동일성, 구간 길이 보존, 정규화 후 원본 보존은 계약입니다. 원래 함수의 계산식을 복사한 테스트보다, 서로 다른 입력과 표현 사이에서도 유지되어야 하는 조건을 검사할 수 있습니다.

tests/scanpy/test_numerical_contracts.py는 음수·0.25·NaN·무한대를 매개변수로 넣어 실패를 확인합니다. 정상 데이터 하나를 통과시키는 것보다 입력 경계를 더 구체적으로 설명합니다. 다만 일부 테스트에는 pytest.importorskip()가 있어 패키지가 없으면 실행되지 않습니다.

6-4. CI: 빠른 공통 검사와 무거운 선택 검사를 나누기

.github/workflows/skill-tests.yml은 먼저 tests/_meta를 검사합니다. compile_problems()는 ast.parse()로 Python 문법을 읽고, dynamic_execution_problems()는 특정 동적 실행 호출을 찾습니다. 검사 대상 스크립트를 실행하지 않고 얻는 신호입니다.

그다음 CI는 테스트 환경 목록에서 packages = []이고 Python 재지정이 없으며 테스트 폴더가 있는 스킬을 고릅니다. 현재 선택 조건에 맞는 것은 24개입니다. 모든 과학 패키지를 준비하는 전체 --isolated 실행은 이 CI에 포함되어 있지 않습니다.

tests/run_all.py는 pytest의 “수집된 테스트 없음” 종료 코드 5를 empty로 보고하고 전체 실패로 처리하지 않습니다. 통과·건너뜀·빈 테스트를 구분하려면 개별 pytest 출력도 읽어야 합니다. 실행기 요약은 종료 코드에 따라 passed·failed·empty로 나누며 건너뛴 테스트 수를 따로 집계하지 않습니다.

6-5. 보안 검사: 탐지 결과와 실제 판정을 구분하기

scan_skills.py의 build_scanner()는 BehavioralAnalyzer·TriggerAnalyzer·LLMAnalyzer를 조합합니다. 정책은 balanced, 전체 입력 문자 상한은 500_000으로 설정합니다. LLM 검사는 네트워크와 API 키에 의존합니다.

content_hash()는 상대 경로와 파일 바이트를 함께 SHA-256에 넣습니다. 이름 변경과 삭제도 지문에 영향을 주며, __pycache__는 제외합니다. cache_invalidation_reason()은 검사기 버전·모델·마지막 전체 검사 시점을 확인합니다. 기본 재검사 기한은 30일입니다.

여기서 배울 점은 “내용이 같으면 무조건 이전 결과 사용”으로 끝내지 않는 것입니다. 판정 도구가 바뀌어도 캐시를 무효화해야 합니다. ThreadPoolExecutor와 스레드별 검사기는 API 대기 시간을 겹쳐 처리하되, 서비스의 호출 한도라는 별도 제약을 받습니다.

7하드웨어 / 시스템 요구사항

7-1. 무엇을 하느냐에 따라 요구 환경이 달라진다

저장소 전체에 적용되는 공식 최소 RAM·CPU·GPU 수치는 없습니다. README의 시스템 안내는 macOS·Linux 또는 WSL2를 사용하는 Windows이며, 관리 도구는 Python 3.13 이상을 요구합니다. 개별 스킬의 compatibility가 더 구체적인 기준입니다.

skills/genomic-coordinates/SKILL.md는 변이 정규화에 참조 FASTA가 필요하고, .fai 인덱스가 없으면 전체 FASTA를 메모리에 읽는다고 설명합니다. “표준 라이브러리만 사용”이라는 말도 “입력 크기와 무관하게 가볍다”는 뜻은 아닙니다.

필요한 자원은 저장소의 스타 수나 스킬 수가 아니라, 선택한 작업의 데이터 크기와 중간 계산 방식으로 결정됩니다. 특히 희소 행렬을 밀집 행렬로 바꾸는 연산과 여러 복사본이 공존하는 단계를 먼저 확인하세요.

7-2. 메모리 계산을 숫자로 이해하기

학습용 계산 예로 세포 100,000개·유전자 20,000개의 밀집 float32 행렬을 생각하면, 원소만 100000 × 20000 × 4 = 8,000,000,000바이트, 약 7.45 GiB입니다. 인덱스·메타데이터·복사본·임시 배열은 포함하지 않은 값입니다. 권장 RAM이나 측정 성능으로 읽으면 안 됩니다.

원본 카운트·정규화본·작업용 부분집합을 별도로 유지하면 신뢰성은 높아지지만 저장 공간과 메모리를 더 씁니다. 희소 행렬은 0이 많을 때 유리하지만 인덱스 비용도 있습니다. skills/scanpy/SKILL.md는 스케일링·회귀가 밀집화를 유발할 수 있고, 이 도구 묶음이 일반적인 디스크 기반 대용량 파이프라인은 아니라고 설명합니다.

7-3. 자원 탐지와 실행 계획도 분리한다

skills/get-available-resources/scripts/detect_resources.py의 collect_snapshot()은 호스트 자원, 프로세스 CPU 제한, Linux cgroup v2, 스케줄러 할당을 따로 수집합니다. read_text와 run_command를 인자로 받을 수 있어 테스트에서는 관찰값을 대체할 수 있습니다.

plan_workload.py의 build_plan()은 그 스냅샷을 받아 병렬 작업 수를 계산하지만 실제 작업을 실행하지 않습니다. CPU 작업에서는 유효 CPU, 메모리, 작업 수, 사용자 요청의 상한 가운데 가장 작은 값을 고릅니다. 관찰 실패는 무제한이 아니라 알 수 없음으로 다룹니다.

# build_plan()의 상한 선택을 이해하기 위한 가정
유효 CPU 상한       = 8개
사용 가능 메모리    = 12 GiB
명시한 예비 메모리  = 2 GiB
작업 하나의 메모리  = 3 GiB
전체 작업 수       = 10개
사용자 요청        = 6개

메모리 상한 = floor((12 - 2) / 3) = 3
제안 작업 수 = min(8, 3, 10, 6) = 3

작업당 메모리를 명시하지 않으면 메모리 상한을 적용하지 않으며, I/O 작업에는 별도 휴리스틱이 있습니다. 위 숫자는 CPU 작업의 원리를 설명하는 예입니다. skills/get-available-resources/scripts/accelerator_diagnostics.py의 build_diagnostic_plan()도 고정된 진단 명령을 제안할 뿐 실행하지 않습니다. 관리 도구에 GPU가 보인다는 사실과 현재 프레임워크에서 사용할 수 있다는 사실을 구분합니다.

8직접 해볼 수 있는 실습 과제

실습 명령의 경로는 저장소 루트 기준입니다. 실행·수정 과제는 별도의 학습용 사본과 해당 의존성을 준비한 뒤 진행하세요. 아래 결과값은 소스와 테스트에 근거한 예상값이며, API 응답이나 벤치마크 결과를 재현한 표는 아닙니다.

실습의 완료 기준은 명령이 끝났다는 사실보다, 왜 그 결과가 나와야 하는지와 어떤 입력에서 실패해야 하는지를 설명하는 것입니다.

sed -n '1,120p' skills/genomic-coordinates/SKILL.md
sed -n '1,115p' skills/genomic-coordinates/scripts/_common.py
sed -n '1,100p' skills/genomic-coordinates/scripts/convert_coords.py

python skills/genomic-coordinates/scripts/convert_coords.py \
  --from bed --to gff chr1 999 1000

# 예상 핵심 필드: output=1000-1000, length=1, status=ok

python skills/genomic-coordinates/scripts/convert_coords.py \
  --from bed --to gff chr1 500 500

# 예상: status=unrepresentable, 종료 코드 1

# NumPy를 사용하는 독립된 학습 예시
import numpy as np

counts = np.array([[1., 3.], [2., 2.]])
saved = counts.copy()
normalized = np.log1p(counts / counts.sum(axis=1, keepdims=True) * 1e4)

assert np.array_equal(counts, saved)
assert np.isfinite(normalized).all()
# 값 하나를 -1, 0.25, NaN으로 바꿀 때 필요한 검사를 설계해 보세요.

# 해당 환경이 준비된 학습용 사본에서 선택적으로 실행
python tests/run_all.py --isolated genomic-coordinates

# 한 스킬을 명시하면 전체 _meta 검사는 자동으로 선행하지 않습니다.
# 이름을 생략한 전체 실행에서 run_meta()를 먼저 호출합니다.

9관련 기술 심화 학습 로드맵

처음부터 177개 스킬을 모두 읽을 필요는 없습니다. 하나의 스킬을 문서부터 테스트까지 따라가고, 다음 스킬에서 비슷한 문제와 다른 제약을 찾아보세요. 아래 주차는 순서를 위한 단위이며 학습 속도에 맞게 조정할 수 있습니다.

학습 범위를 넓히기 전에 작은 입력의 예상 결과와 실패 조건을 직접 설명할 수 있어야, 더 큰 파이프라인도 근거를 갖고 읽을 수 있습니다.

9-1. 기초를 마친 뒤 갈라지는 세 방향

• 에이전트 지식 설계: SKILL.md의 선택 조건과 작업 절차를 개선하고, 필요한 참고 문서만 연결하는 방법을 연습합니다. 선택 정확도는 호스트와 모델에 따라 따로 평가합니다.
• 데이터 엔지니어링: 원본·변환본·메타데이터의 연결을 다른 데이터 형식에도 적용합니다. 큰 데이터를 만나면 희소 구조, 부분 읽기, 메모리 예산부터 조사합니다.
• 품질 자동화: 구조 검사와 동작 검사를 분리하고, 무거운 테스트가 생략되는 조건을 명시합니다. 결과표에는 통과뿐 아니라 건너뜀과 미검증 범위를 남깁니다.

10핵심 키워드 사전

11참고 링크

11-1. 공식 저장소·사용 문서

• 공식 GitHub 저장소 — 프로젝트의 최신 상태와 안내
• README — 지원 범위, 설치 방식, 버전 변경 안내
• 전체 스킬 목록 — 관심 분야의 스킬 찾기
• 저장소 구조·기여 규칙 — frontmatter, 테스트 위치, 환경 분리의 이유
• v2.72.0 릴리스 — 해당 버전의 배포 기록
• 보안 정책 — 자동 생성 보고서와 별도로 관리되는 정책 문서

11-2. 코드로 다시 확인할 핵심 경로

• pyproject.toml · plugin.json — 관리 도구 의존성과 패키지 버전
• 좌표 변환의 기준 형식 · 변환과 오류 상태
• Scanpy 공통 처리 · 수치·데이터 보존 계약
• 스킬별 테스트 실행기 · 스킬별 의존성·Python 설정
• 저장소 계약·플러그인 검사 · CI에서 실행하는 검사 범위
• 자원 예산 계획 코드 · 보안 검사·캐시 코드
• 2026-10-19 보안 보고서 · 검사 세부 데이터 · 별도 검토 문서

11-3. 관련 기술의 공식 학습 자료

• Agent Skills 규격 · Agent Plugins — 스킬과 패키지의 공통 형식
• Python argparse · Python dataclasses · Python ast
• uv · pytest · JSON Schema
• Scanpy · AnnData · SciPy 희소 행렬
• Cisco AI Defense Skill Scanner — 저장소에서 사용하는 자동 검사기의 공식 소스

11-4. 현재 상태 (2026-10-23 확인)

GitHub 수치는 2026-10-23 기준입니다. 파일 구성과 줄 수, 설정값은 커밋 593377b 기준이며 최신 릴리스의 모든 상태와 동일하다고 가정하지 않습니다. 이후에는 기본 브랜치의 코드와 외부 패키지 API가 달라질 수 있습니다.

11-5. 보안 보고서를 읽을 때 놓치기 쉬운 차이

docs/security-report.json의 466개 항목 중 377개는 스킬 간 비교 탐지입니다. 보고서의 safe_skills=159는 스킬별 분류이며 “모든 검증을 마친 159개”나 “탐지 항목이 전혀 없는 159개”를 뜻하지 않습니다. 전체 항목 수와 스킬별 표의 수를 단순히 더해 비교하면 어긋날 수 있습니다.

docs/security-triage.md의 현재 보고서 절은 2026-09-13·165개 스킬을 설명합니다. 10월 19일 자동 보고서와 시점이 다르므로, 이전 검토가 새 탐지 결과를 모두 해소했다고 볼 수 없습니다. 탐지는 코드 검토의 단서이고, 악성 여부의 최종 증명도 안전성 인증도 아닙니다.