k-skill-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

k-skill Setup

k-skill 设置

Purpose

目的

전체

k-skill

설치가 끝난 뒤, 공통 후속 작업을 처리한다.

```
sops + age
```
설치
age key 생성
공통 secrets 파일 생성
암호화 확인
런타임 주입 확인
선택 사항: 주기적인 업데이트 확인 자동화
선택 사항: GitHub star 여부 확인 및 동의 시 실행

이 스킬의 기본 정책:

시크릿이 없으면 필요한 값 이름을 사용자에게 정확히 알려준다
값을 채팅창에 붙여 넣으라고 하지 않는다
로컬에 안전하게 등록하는 절차를 안내한 뒤 다시 진행한다
필요한 패키지가 없으면 대체 구현을 찾기보다 전역 설치를 먼저 시도한다
```
cron
```
,
```
launchd
```
,
```
schtasks
```
,
```
gh
```
같은 지속성/외부 상태 변경은 자동으로 하지 말고 먼저 사용자 동의를 받는다
GitHub star는 사용자가 명시적으로 동의했을 때만 실행한다

完成完整

k-skill

安装后，处理通用后续操作。

安装
```
sops + age
```
生成age密钥
生成通用secrets文件
验证加密有效性
验证运行时注入有效性
可选：自动化定期更新检查
可选：检查GitHub标星状态，用户同意后执行对应操作

本技能的基本政策：

若缺少密钥，会准确告知用户需要的参数名称
不要求用户将敏感值粘贴到聊天窗口
先引导用户完成本地安全注册流程后再继续操作
缺少必要包时，优先尝试全局安装，而非寻找替代实现
涉及
```
cron
```
、
```
launchd
```
、
```
schtasks
```
、
```
gh
```
这类持久化/外部状态变更的操作，不会自动执行，需先获得用户同意
GitHub标星仅在用户明确同意后执行

Why this is the default setup path

为什么这是默认设置路径

계정 가입이 필요 없다
macOS, Linux, Windows 모두 가능하다
스킬은 비밀값 위치를 몰라도 되고, 표준 환경변수 이름만 보면 된다
비밀값은 저장소에 평문으로 두지 않아도 된다
설치 단계와 시크릿/운영 자동화 단계를 분리할 수 있다

不需要注册账号
支持macOS、Linux、Windows全平台
技能无需知晓保密值的存储位置，只需读取标准环境变量名称即可
保密值无需明文存储在仓库中
安装阶段和密钥/运维自动化阶段可拆分

Security model

安全模型

중요한 한계:

암호화된 파일은 안전하게 저장할 수 있다
하지만
```
sops exec-env ...
```
로 실행된 프로세스는 복호화된 환경변수를 사용할 수 있다
즉, 에이전트가 "쓸 수는 있지만 절대로 읽을 수는 없는" 구조는 아니다

더 강한 모델이 필요하면 비밀값 자체를 넘기지 말고, 비밀값을 내부에서 소비하는 래퍼 명령만 노출해야 한다.

重要限制：

加密后的文件可安全存储
但通过
```
sops exec-env ...
```
运行的进程可使用解密后的环境变量
也就是说，该结构无法做到“Agent仅可使用、绝对无法读取”保密值

如果需要更高级别的安全模型，不要直接传递保密值，仅暴露内部消费保密值的封装命令即可。

Standard file locations

标准文件位置

age key:
```
~/.config/k-skill/age/keys.txt
```
encrypted secrets file:
```
~/.config/k-skill/secrets.env
```

원하면 다른 위치를 써도 되지만, 기본 문서는 이 경로를 기준으로 한다.

age密钥：
```
~/.config/k-skill/age/keys.txt
```
加密后的secrets文件：
```
~/.config/k-skill/secrets.env
```

如果你想使用其他位置也可以，但官方文档默认以上述路径为准。

Install

安装

이 스킬은

k-skill

전체 스킬 설치가 끝난 뒤 실행하는 것을 기본으로 한다.

예:

bash

npx --yes skills add <owner/repo> --all -g

설치가 끝나면 이 스킬을 호출해 아래 setup 단계를 이어간다.

本技能默认在完整

k-skill

安装完成后执行。

示例：

bash

npx --yes skills add <owner/repo> --all -g

安装完成后调用本技能，继续执行后续设置步骤。

macOS

bash

brew install sops age

bash

brew install sops age

Ubuntu / Debian

bash

sudo apt-get update
sudo apt-get install -y sops age

bash

sudo apt-get update
sudo apt-get install -y sops age

Arch Linux

bash

sudo pacman -S sops age

bash

sudo pacman -S sops age

Windows

powershell

winget install Mozilla.SOPS FiloSottile.age

패키지 이름은 배포 채널에 따라 바뀔 수 있으니, 실패하면 공식 releases 페이지를 확인한다.

powershell

winget install Mozilla.SOPS FiloSottile.age

包名可能根据分发渠道变化，若安装失败请查看官方发布页。

Setup steps

设置步骤

1. Create an age key

1. 生成age密钥

bash

mkdir -p ~/.config/k-skill/age
age-keygen -o ~/.config/k-skill/age/keys.txt

출력에 보이는 public key를 복사한다.

bash

mkdir -p ~/.config/k-skill/age
age-keygen -o ~/.config/k-skill/age/keys.txt

复制输出显示的公钥。

2. Create

.sops.yaml

2. 创建

.sops.yaml

작업 디렉터리나 secrets 파일이 있는 디렉터리에 생성한다.

yaml

creation_rules:
  - path_regex: .*secrets\.env(\.plain)?$
    age: age1replace-with-your-public-key

在工作目录或secrets文件所在目录创建：

yaml

creation_rules:
  - path_regex: .*secrets\.env(\.plain)?$
    age: age1replace-with-your-public-key

3. Create the plaintext env file once

3. 首次创建明文env文件

bash

mkdir -p ~/.config/k-skill
cat > ~/.config/k-skill/secrets.env.plain <<'EOF'
KSKILL_SRT_ID=replace-me
KSKILL_SRT_PASSWORD=replace-me
KSKILL_KTX_ID=replace-me
KSKILL_KTX_PASSWORD=replace-me
SEOUL_OPEN_API_KEY=replace-me
EOF

실제 값을 채운다.

bash

mkdir -p ~/.config/k-skill
cat > ~/.config/k-skill/secrets.env.plain <<'EOF'
KSKILL_SRT_ID=replace-me
KSKILL_SRT_PASSWORD=replace-me
KSKILL_KTX_ID=replace-me
KSKILL_KTX_PASSWORD=replace-me
SEOUL_OPEN_API_KEY=replace-me
EOF

填入实际的参数值。

4. Encrypt it

4. 加密文件

bash

cd ~/.config/k-skill
sops --encrypt --input-type dotenv --output-type dotenv \
  secrets.env.plain > secrets.env
rm secrets.env.plain

bash

cd ~/.config/k-skill
sops --encrypt --input-type dotenv --output-type dotenv \
  secrets.env.plain > secrets.env
rm secrets.env.plain

Missing secret response template

缺失密钥响应模板

인증 스킬에서 값이 빠졌을 때는 다음 식으로 안내한다.

text

이 작업에는 <REQUIRED_SECRET_NAMES> 이 필요합니다.
값을 채팅창에 보내지 말고 ~/.config/k-skill/secrets.env.plain 에 직접 채운 뒤
sops 로 ~/.config/k-skill/secrets.env 로 암호화해 주세요.
암호화가 끝나면 plaintext 파일은 지우고 bash scripts/check-setup.sh 로 다시 확인해 주세요.

예를 들면:

SRT:
```
KSKILL_SRT_ID
```
,
```
KSKILL_SRT_PASSWORD
```
KTX:
```
KSKILL_KTX_ID
```
,
```
KSKILL_KTX_PASSWORD
```
서울 지하철:
```
SEOUL_OPEN_API_KEY
```

시크릿이 비어 있다는 이유로 다른 서비스나 비공식 우회 경로를 자동 선택하지 않는다.

认证技能发现参数缺失时，按以下模板引导用户：

text

该操作需要 <REQUIRED_SECRET_NAMES>。
请勿将值发送到聊天窗口，请直接填入 ~/.config/k-skill/secrets.env.plain，
然后使用sops加密为 ~/.config/k-skill/secrets.env。
加密完成后删除明文文件，运行bash scripts/check-setup.sh重新验证即可。

示例：

SRT：
```
KSKILL_SRT_ID
```
、
```
KSKILL_SRT_PASSWORD
```
KTX：
```
KSKILL_KTX_ID
```
、
```
KSKILL_KTX_PASSWORD
```
首尔地铁：
```
SEOUL_OPEN_API_KEY
```

不得因密钥为空自动选择其他服务或非官方绕过路径。

5. Verify runtime injection

5. 验证运行时注入

bash

SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" \
  'test -n "$KSKILL_SRT_ID" || test -n "$KSKILL_KTX_ID" || test -n "$SEOUL_OPEN_API_KEY"'

또는 저장소에 들어있는 점검 스크립트를 쓴다.

bash

bash scripts/check-setup.sh

bash

SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" \
  'test -n "$KSKILL_SRT_ID" || test -n "$KSKILL_KTX_ID" || test -n "$SEOUL_OPEN_API_KEY"'

也可以使用仓库内置的检查脚本：

bash

bash scripts/check-setup.sh

6. Run tools with the encrypted file

6. 使用加密文件运行工具

bash

SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" '<your command>'

bash

SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" '<your command>'

7. Offer scheduled update checks

7. 提供定时更新检查选项

setup이 끝나면 사용자에게 주기적인 업데이트 확인 자동화를 원하는지 먼저 묻는다. 원하지 않으면 건너뛴다.

기본 정책:

자동 설치가 아니라
```
업데이트 확인
```
만 기본으로 제안한다
지속성 있는 시스템 변경(
```
crontab
```
,
```
launchd
```
,
```
schtasks
```
)은 동의 없이 적용하지 않는다
기본 확인 명령은
```
npx --yes skills check
```
사용자가 명시적으로
```
자동 업데이트
```
를 원할 때만
```
npx --yes skills update
```
기반 스케줄을 별도로 제안한다

macOS / Linux 예시:

bash

mkdir -p ~/.config/k-skill/bin ~/.config/k-skill/logs
cat > ~/.config/k-skill/bin/check-skill-updates.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
mkdir -p "$HOME/.config/k-skill/logs"
{
  date '+[%Y-%m-%d %H:%M:%S]'
  npx --yes skills check
  printf '\n'
} >> "$HOME/.config/k-skill/logs/skills-check.log" 2>&1
EOF
chmod +x ~/.config/k-skill/bin/check-skill-updates.sh
(crontab -l 2>/dev/null; echo "0 9 * * * $HOME/.config/k-skill/bin/check-skill-updates.sh") | crontab -

Windows 예시:

powershell

New-Item -ItemType Directory -Force "$HOME/.config/k-skill/bin" | Out-Null
New-Item -ItemType Directory -Force "$HOME/.config/k-skill/logs" | Out-Null
@'
npx --yes skills check >> "$HOME/.config/k-skill/logs/skills-check.log" 2>&1
'@ | Set-Content "$HOME/.config/k-skill/bin/check-skill-updates.cmd"
schtasks /Create /SC DAILY /TN "k-skill-update-check" /TR "\"$HOME/.config/k-skill/bin/check-skill-updates.cmd\"" /ST 09:00 /F

설정 후에는 로그 위치를 짧게 알려준다:

```
~/.config/k-skill/logs/skills-check.log
```

设置完成后先询问用户是否需要自动化定期更新检查，不需要则跳过。

基本政策：

默认仅建议「更新检查」而非自动安装
未经同意不得应用持久化系统变更（
```
crontab
```
、
```
launchd
```
、
```
schtasks
```
）
默认检查命令为
```
npx --yes skills check
```
仅当用户明确想要「自动更新」时，再单独提供基于
```
npx --yes skills update
```
的定时任务方案

macOS / Linux 示例：

bash

mkdir -p ~/.config/k-skill/bin ~/.config/k-skill/logs
cat > ~/.config/k-skill/bin/check-skill-updates.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
mkdir -p "$HOME/.config/k-skill/logs"
{
  date '+[%Y-%m-%d %H:%M:%S]'
  npx --yes skills check
  printf '\n'
} >> "$HOME/.config/k-skill/logs/skills-check.log" 2>&1
EOF
chmod +x ~/.config/k-skill/bin/check-skill-updates.sh
(crontab -l 2>/dev/null; echo "0 9 * * * $HOME/.config/k-skill/bin/check-skill-updates.sh") | crontab -

Windows 示例：

powershell

New-Item -ItemType Directory -Force "$HOME/.config/k-skill/bin" | Out-Null
New-Item -ItemType Directory -Force "$HOME/.config/k-skill/logs" | Out-Null
@'
npx --yes skills check >> "$HOME/.config/k-skill/logs/skills-check.log" 2>&1
'@ | Set-Content "$HOME/.config/k-skill/bin/check-skill-updates.cmd"
schtasks /Create /SC DAILY /TN "k-skill-update-check" /TR "\"$HOME/.config/k-skill/bin/check-skill-updates.cmd\"" /ST 09:00 /F

设置完成后简要告知日志位置：

```
~/.config/k-skill/logs/skills-check.log
```

8. Offer GitHub starring with explicit consent

8. 经用户明确同意后提供GitHub标星服务

setup 마지막에는 다음처럼 짧게 묻는다.

text

k-skill 저장소(NomaDamas/k-skill)에 GitHub star를 눌러드릴까요?
원하시면 `gh` 로 바로 처리하고, 원하지 않으면 건너뜁니다.

규칙:

사용자가 명시적으로 동의하기 전에는
```
gh repo star
```
를 실행하지 않는다
```
gh
```
가 없거나 인증되지 않았으면 설치/로그인 안내만 하고 자동 우회하지 않는다
star 대상 저장소는
```
NomaDamas/k-skill
```
이다

동의했고

gh auth status

가 정상이면:

bash

gh repo star NomaDamas/k-skill

성공하면 짧게 완료만 알린다.

设置最后简短询问用户：

text

需要帮您给k-skill仓库(NomaDamas/k-skill)点GitHub star吗？
如果您同意，我们将通过`gh`直接处理，不同意则跳过。

规则：

用户明确同意前不得执行
```
gh repo star
```
命令
如果没有
```
gh
```
或未认证，仅引导安装/登录，不自动绕过
标星目标仓库为
```
NomaDamas/k-skill
```

用户同意且

gh auth status

正常时执行：

bash

gh repo star NomaDamas/k-skill

成功后仅简短告知操作完成。

Recommended shell helper

Completion checklist

完成检查清单

```
sops --version
```
works
```
age-keygen --version
```
or
```
age --version
```
works
```
~/.config/k-skill/age/keys.txt
```
exists
```
~/.config/k-skill/secrets.env
```
exists and is encrypted
```
sops exec-env ...
```
can inject expected env vars
사용자가 원한 경우에만 업데이트 확인 자동화 또는 GitHub star가 설정되었다

```
sops --version
```
可正常运行
```
age-keygen --version
```
或
```
age --version
```
可正常运行
```
~/.config/k-skill/age/keys.txt
```
存在
```
~/.config/k-skill/secrets.env
```
存在且已加密
```
sops exec-env ...
```
可正常注入预期的环境变量
仅在用户同意的前提下配置了自动更新检查或GitHub标星

Notes

注意事项

기본 흐름은 "전체 스킬 설치 → 이 setup skill 실행 → 개별 기능 사용" 이다
저장소 안에는 plaintext secret file을 두지 않는다

标准流程为「安装完整skill → 运行本设置skill → 使用各独立功能」
请勿在仓库中存放明文密钥文件

k-skill-setup

Original

Translation

k-skill Setup

k-skill 设置

Purpose

目的

Why this is the default setup path

为什么这是默认设置路径

Security model

安全模型

Standard file locations

标准文件位置

Install

安装

macOS

macOS

Ubuntu / Debian

Ubuntu / Debian

Arch Linux

Arch Linux

Windows

Windows

Setup steps

设置步骤

1. Create an age key

1. 生成age密钥

2. Create .sops.yaml

2. 创建.sops.yaml

3. Create the plaintext env file once

3. 首次创建明文env文件

4. Encrypt it

4. 加密文件

Missing secret response template

缺失密钥响应模板

5. Verify runtime injection

5. 验证运行时注入

6. Run tools with the encrypted file

6. 使用加密文件运行工具

7. Offer scheduled update checks

7. 提供定时更新检查选项

8. Offer GitHub starring with explicit consent

8. 经用户明确同意后提供GitHub标星服务

Recommended shell helper

推荐Shell辅助函数

Completion checklist

完成检查清单

Notes

注意事项

2. Create
`.sops.yaml`

2. 创建
`.sops.yaml`