xixu-me/skills
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: initialize skills repository

Browse Source
This commit is contained in:
xixu-me committed 2026-03-27 16:08:49 +08:00
commit 48681eec36
28 files changed
+2556
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.editorconfig
+13
View File
@@ -0,0 +1,13 @@
root = true
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 2
tab_width = 2
trim_trailing_whitespace = true
[*.md]
trim_trailing_whitespace = false
.gitattributes
+2
View File
@@ -0,0 +1,2 @@
# Auto detect text files and perform LF normalization
* text=auto
.github/workflows/markdown-fix.yml
+65
View File
@@ -0,0 +1,65 @@
name: Markdown Fix
on:
workflow_dispatch:
inputs:
commit_message:
description: Commit message for Markdown formatting changes
required: true
default: "style: format markdown"
type: string
permissions:
contents: write
jobs:
prettier:
name: Format and commit Markdown
runs-on: ubuntu-latest
timeout-minutes: 10
concurrency:
group: markdown-fix-${{ github.ref }}
cancel-in-progress: false
steps:
- name: Check out repository
uses: actions/checkout@v5
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: npm
- name: Install dependencies
run: npm ci
- name: Format Markdown
run: npm run format:md
- name: Detect changes
id: changes
shell: bash
run: |
if git diff --quiet; then
echo "changed=false" >> "$GITHUB_OUTPUT"
else
echo "changed=true" >> "$GITHUB_OUTPUT"
fi
- name: Commit formatting changes
if: steps.changes.outputs.changed == 'true'
shell: bash
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add --all -- '*.md'
git commit -m "${{ inputs.commit_message }}"
- name: Push formatting changes
if: steps.changes.outputs.changed == 'true'
run: git push
- name: No changes
if: steps.changes.outputs.changed != 'true'
run: echo "Markdown files are already formatted."
.github/workflows/markdown.yml
+47
View File
@@ -0,0 +1,47 @@
name: Markdown
on:
push:
paths:
- "**/*.md"
- ".editorconfig"
- ".prettierignore"
- ".prettierrc.json"
- "package.json"
- "package-lock.json"
- ".github/workflows/markdown.yml"
pull_request:
paths:
- "**/*.md"
- ".editorconfig"
- ".prettierignore"
- ".prettierrc.json"
- "package.json"
- "package-lock.json"
- ".github/workflows/markdown.yml"
workflow_dispatch:
permissions:
contents: read
jobs:
prettier:
name: Check Markdown formatting
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Check out repository
uses: actions/checkout@v5
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: npm
- name: Install dependencies
run: npm ci
- name: Check Markdown formatting
run: npm run check:md
.gitignore
+1
View File
@@ -0,0 +1 @@
node_modules/
.prettierignore
+2
View File
@@ -0,0 +1,2 @@
node_modules/
.git/
.prettierrc.json
+4
View File
@@ -0,0 +1,4 @@
{
"$schema": "https://json.schemastore.org/prettierrc",
"proseWrap": "preserve"
}
LICENSE
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Xi Xu
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
README.md
+96
View File
@@ -0,0 +1,96 @@
# Agent Skills
**_[汉语](./README.zh.md)_**
[Agent Skills](https://agentskills.io) maintained by me for practical engineering work.
This repository is continuously updated. I also maintain bundled skills in [`xixu-me/xget`](https://github.com/xixu-me/xget) and [`xixu-me/xdrop`](https://github.com/xixu-me/xdrop).
## How To Use
You can use these skills in two ways:
1. Restore a reviewed baseline with [Skills Vault](https://github.com/xixu-me/skills-vault) and [`xixu-me/skvlt`](https://github.com/xixu-me/skvlt).
2. Add a source repository directly with `bunx skills add` or `npx skills add`.
> [!TIP]
> If you want a ready-to-use manifest of common skills, start with [`xixu-me/skvlt`](https://github.com/xixu-me/skvlt). Its `skvlt.yaml` is maintained as a reviewed baseline for a broader set of commonly used skills.
### Option 1: Use Skills Vault
Back up and restore through Skills Vault:
```bash
git clone https://github.com/xixu-me/skvlt.git
cd skvlt
bunx skvlt restore --all
```
This is the best option if you want a portable baseline that can be reapplied across machines.
### Option 2: Add Repositories Directly
Install this repository as a skill source:
```bash
bunx skills add xixu-me/skills
```
or:
```bash
npx skills add xixu-me/skills
```
Install the bundled skill sources from `xixu-me/xget` and `xixu-me/xdrop`:
```bash
bunx skills add xixu-me/xget
bunx skills add xixu-me/xdrop
```
or:
```bash
npx skills add xixu-me/xget
npx skills add xixu-me/xdrop
```
## Skills Catalog
The table below lists the skills maintained across this repository and the related bundled-skill repositories.
| Skill | Description | Bundled Assets |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| [GitHub Actions Docs](./skills/github-actions-docs/SKILL.md) | Official-docs-grounded help for writing, migrating, securing, and troubleshooting GitHub Actions workflows. | `references/` |
| [OpenClaw Secure Linux Cloud](./skills/openclaw-secure-linux-cloud/SKILL.md) | Guidance for securely self-hosting OpenClaw on Linux VPS or cloud servers. | `references/` |
| [Open Source Guide Coach](./skills/opensource-guide-coach/SKILL.md) | Coaching for starting, growing, governing, funding, and sustaining open source projects. | `references/` |
| [Running Claude Code via LiteLLM Copilot](./skills/running-claude-code-via-litellm-copilot/SKILL.md) | Help for routing Claude Code through LiteLLM and GitHub Copilot, including setup and troubleshooting. | `references/` |
| [Secure Linux Web Hosting](./skills/secure-linux-web-hosting/SKILL.md) | Practical Linux VPS and web hosting hardening for DNS, SSH, reverse proxies, HTTPS, and safe self-hosting. | `references/` |
| [Skills CLI](./skills/skills-cli/SKILL.md) | Help for discovering, installing, listing, backing up, restoring, syncing, and managing Agent Skills. | None |
| [Xget](https://github.com/xixu-me/xget/blob/main/skills/xget/SKILL.md) | Execution-focused skill for configuring and applying Xget acceleration to URLs, package managers, registries, containers, CI, and AI SDKs, etc. | `references/`, `scripts/` |
| [Xdrop](https://github.com/xixu-me/xdrop/blob/main/skills/xdrop/SKILL.md) | Skill for uploading to and downloading from Xdrop through the terminal, including encrypted share-link workflows. | `scripts/` |
## Repository Layout
Each skill lives in its own folder and follows the Agent Skills specification:
```text
skills/
<skill-name>/
SKILL.md
references/ # optional
scripts/ # optional
```
Skills are designed for progressive disclosure: agents load the instructions only when the task calls for them, while bundled references and scripts stay with the skill for repeatable execution.
## Notes
- This repository is meant to evolve over time as new workflows appear.
- `xixu-me/skvlt` is the easiest way to restore a reviewed common baseline.
- Direct `bunx` or `npx` installation is better when you only want a specific source repository.
## License
Licensed under MIT License. See [`LICENSE`](./LICENSE).
README.zh.md
+96
View File
@@ -0,0 +1,96 @@
# Agent Skills
**_[English](./README.md)_**
由我维护的、用于实际工程工作的 [Agent Skills](https://agentskills.io)。
本存储库会持续更新。我也在 [`xixu-me/xget`](https://github.com/xixu-me/xget) 和 [`xixu-me/xdrop`](https://github.com/xixu-me/xdrop) 中维护了它们附带的 skills。
## 如何使用
你可以通过两种方式使用这些 skills：
1. 使用 [Skills Vault](https://github.com/xixu-me/skills-vault) 和 [`xixu-me/skvlt`](https://github.com/xixu-me/skvlt) 恢复一套经过审阅的基线配置。
2. 直接用 `bunx skills add` 或 `npx skills add` 添加源存储库。
> [!TIP]
> 如果你想直接使用一份现成的常用 skills 清单，建议从 [`xixu-me/skvlt`](https://github.com/xixu-me/skvlt) 开始。它的 `skvlt.yaml` 维护了一套覆盖更广、经过审阅的常用基线。
### 方案 1：使用 Skills Vault
通过 Skills Vault 备份和恢复：
```bash
git clone https://github.com/xixu-me/skvlt.git
cd skvlt
bunx skvlt restore --all
```
如果你希望在多台机器之间复用一套可移植基线，这是最合适的方式。
### 方案 2：直接添加存储库
将本存储库作为 skill source 安装：
```bash
bunx skills add xixu-me/skills
```
或者：
```bash
npx skills add xixu-me/skills
```
安装 `xixu-me/xget` 和 `xixu-me/xdrop` 中打包的 skill sources：
```bash
bunx skills add xixu-me/xget
bunx skills add xixu-me/xdrop
```
或者：
```bash
npx skills add xixu-me/xget
npx skills add xixu-me/xdrop
```
## Skills 目录
下表列出了此存储库及相关附带 skills 的存储库中维护的 skills。
| Skill | 说明 | Bundled Assets |
| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------- |
| [GitHub Actions Docs](./skills/github-actions-docs/SKILL.md) | 基于官方文档，帮助编写、迁移、加固和排查 GitHub Actions workflows。 | `references/` |
| [OpenClaw Secure Linux Cloud](./skills/openclaw-secure-linux-cloud/SKILL.md) | 为在 Linux VPS 或云服务器上安全自托管 OpenClaw 提供指导。 | `references/` |
| [Open Source Guide Coach](./skills/opensource-guide-coach/SKILL.md) | 为开源项目的启动、增长、治理、资助与长期维护提供辅导。 | `references/` |
| [Running Claude Code via LiteLLM Copilot](./skills/running-claude-code-via-litellm-copilot/SKILL.md) | 帮助通过 LiteLLM 和 GitHub Copilot 路由 Claude Code，包括安装配置与排障。 | `references/` |
| [Secure Linux Web Hosting](./skills/secure-linux-web-hosting/SKILL.md) | 提供 DNS、SSH、反向代理、HTTPS 和安全自托管相关的 Linux VPS / Web Hosting 实践指南。 | `references/` |
| [Skills CLI](./skills/skills-cli/SKILL.md) | 帮助发现、安装、列出、备份、恢复、同步和管理 Agent Skills。 | None |
| [Xget](https://github.com/xixu-me/xget/blob/main/skills/xget/SKILL.md) | 面向执行的技能，用于将 Xget 加速能力应用到 URL、包管理器、存储库、容器、CI 和 AI SDK 等场景。 | `references/`, `scripts/` |
| [Xdrop](https://github.com/xixu-me/xdrop/blob/main/skills/xdrop/SKILL.md) | 通过终端上传到和下载自 Xdrop 的技能，也覆盖加密分享链接工作流。 | `scripts/` |
## 存储库结构
每个 skill 都位于独立目录中，并遵循 Agent Skills 规范：
```text
skills/
<skill-name>/
SKILL.md
references/ # 可选
scripts/ # 可选
```
这些 skills 采用渐进式披露设计：只有当任务真正需要时，智能体才会加载对应说明；而配套的 references 和 scripts 会跟随 skill 一起保留，以便重复执行。
## 说明
- 本存储库会随着新工作流的出现持续演进。
- `xixu-me/skvlt` 是恢复一套经过审阅的常用基线最简单的方式。
- 如果你只想使用某个特定 source repository，直接通过 `bunx` 或 `npx` 安装会更合适。
## 许可证
基于 MIT License 发布。详见 [`LICENSE`](./LICENSE)。
package-lock.json
Generated
+29
View File
@@ -0,0 +1,29 @@
{
"name": "xixu-me-skills",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "xixu-me-skills",
"devDependencies": {
"prettier": "^3.5.3"
}
},
"node_modules/prettier": {
"version": "3.8.1",
"resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.1.tgz",
"integrity": "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==",
"dev": true,
"license": "MIT",
"bin": {
"prettier": "bin/prettier.cjs"
},
"engines": {
"node": ">=14"
},
"funding": {
"url": "https://github.com/prettier/prettier?sponsor=1"
}
}
}
}
package.json
+12
View File
@@ -0,0 +1,12 @@
{
"name": "xixu-me-skills",
"private": true,
"description": "Formatting helpers for this Agent Skills repository",
"scripts": {
"format:md": "prettier --write \"**/*.md\"",
"check:md": "prettier --check \"**/*.md\""
},
"devDependencies": {
"prettier": "^3.5.3"
}
}
skills/github-actions-docs/SKILL.md
+100
View File
@@ -0,0 +1,100 @@
---
name: github-actions-docs
description: Use when users ask how to write, explain, customize, migrate, secure, or troubleshoot GitHub Actions workflows, workflow syntax, triggers, matrices, runners, reusable workflows, artifacts, caching, secrets, OIDC, deployments, custom actions, or Actions Runner Controller, especially when they need official GitHub documentation, exact links, or docs-grounded YAML guidance.
---
# GitHub Actions Docs
GitHub Actions questions are easy to answer from stale memory. Use this skill to ground answers in official GitHub documentation and return the closest authoritative page instead of generic CI/CD advice.
## When to Use
Use this skill when the request is about:
- GitHub Actions concepts, terminology, or product boundaries
- Workflow YAML, triggers, jobs, matrices, concurrency, variables, contexts, or expressions
- GitHub-hosted runners, larger runners, self-hosted runners, or Actions Runner Controller
- Artifacts, caches, reusable workflows, workflow templates, or custom actions
- Secrets, `GITHUB_TOKEN`, OpenID Connect, artifact attestations, or secure workflow patterns
- Environments, deployment protection rules, deployment history, or deployment examples
- Migrating from Jenkins, CircleCI, GitLab CI/CD, Travis CI, Azure Pipelines, or other CI systems
- Troubleshooting workflow behavior when the user needs documentation, syntax guidance, or official references
Do not use this skill for:
- A specific failing PR check, missing workflow log, or CI failure triage. Use `gh-fix-ci`.
- General GitHub pull request, branch, or repository operations. Use `github`.
- CodeQL-specific configuration or code scanning guidance. Use `codeql`.
- Dependabot configuration, grouping, or dependency update strategy. Use `dependabot`.
## Workflow
### 1. Classify the request
Decide which bucket the question belongs to before searching:
- Getting started or tutorials
- Workflow authoring and syntax
- Runners and execution environment
- Security and supply chain
- Deployments and environments
- Custom actions and publishing
- Monitoring, logs, and troubleshooting
- Migration
If you need a quick starting point, load `references/topic-map.md` and jump to the closest section.
### 2. Search official GitHub docs first
- Treat `docs.github.com` as the source of truth.
- Prefer pages under `https://docs.github.com/en/actions`.
- Search with the user's exact terms plus a focused Actions phrase such as `workflow syntax`, `OIDC`, `reusable workflows`, or `self-hosted runners`.
- When multiple pages are plausible, compare 2-3 candidate pages and pick the one that most directly answers the user's question.
### 3. Open the best page before answering
- Read the most relevant page, and the exact section when practical.
- Use the topic map only to narrow the search space or surface likely starting pages.
- If a page appears renamed, moved, or incomplete, say that explicitly and return the nearest authoritative pages instead of guessing.
### 4. Answer with docs-grounded guidance
- Start with a direct answer in plain language.
- Include exact GitHub docs links, not just the docs homepage.
- Only provide YAML or step-by-step examples when the user asks for them or when the docs page makes an example necessary.
- Make any inference explicit. Good phrasing:
- `According to GitHub docs, ...`
- `Inference: this likely means ...`
## Answer Shape
Use a compact structure unless the user asks for depth:
1. Direct answer
2. Relevant docs
3. Example YAML or steps, only if needed
4. Explicit inference callout, only if you had to connect multiple docs pages
Keep citations close to the claim they support.
## Search and Routing Tips
- For concept questions, prefer overview or concept pages before deep reference pages.
- For syntax questions, prefer workflow syntax, events, contexts, variables, or expressions reference pages.
- For security questions, prefer `Secure use`, `Secrets`, `GITHUB_TOKEN`, `OpenID Connect`, and artifact attestation docs.
- For deployment questions, prefer environments and deployment protection docs before cloud-specific examples.
- For migration questions, prefer the migration hub page first, then a platform-specific migration guide.
- If the user asks for a beginner walkthrough, start with a tutorial or quickstart instead of a raw reference page.
## Common Mistakes
- Answering from memory without verifying the current docs
- Linking the GitHub Actions docs landing page when a narrower page exists
- Mixing up reusable workflows and composite actions
- Suggesting long-lived cloud credentials when OIDC is the better documented path
- Treating repo-specific CI debugging as a documentation question when it should be handed to `gh-fix-ci`
- Letting adjacent domains absorb the request when `codeql` or `dependabot` is the sharper fit
## Bundled Reference
Read `references/topic-map.md` only as a compact index of likely doc entry points. It is intentionally incomplete and should never replace the live GitHub docs as the final authority.
skills/github-actions-docs/references/topic-map.md
+90
View File
@@ -0,0 +1,90 @@
# GitHub Actions Topic Map
This reference is a compact routing aid derived from the source catalog. It is intentionally selective and deduplicated. Use it to find the right documentation neighborhood quickly, then verify against the live docs on `docs.github.com`.
## Getting Started
- [Understanding GitHub Actions](https://docs.github.com/en/actions/get-started/understand-github-actions)
- [Quickstart for GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart)
- [Continuous integration](https://docs.github.com/en/actions/get-started/continuous-integration)
- [Continuous deployment](https://docs.github.com/en/actions/get-started/continuous-deployment)
- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax)
- [Events that trigger workflows](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows)
## Workflow Authoring
- [Workflows](https://docs.github.com/en/actions/concepts/workflows-and-actions/workflows)
- [Variables](https://docs.github.com/en/actions/concepts/workflows-and-actions/variables)
- [Contexts](https://docs.github.com/en/actions/concepts/workflows-and-actions/contexts)
- [Expressions](https://docs.github.com/en/actions/concepts/workflows-and-actions/expressions)
- [Using jobs in a workflow](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-jobs)
- [Running variations of jobs in a workflow](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations)
- [Passing information between jobs](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/pass-job-outputs)
- [Reuse workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows)
- [Reusing workflow configurations](https://docs.github.com/en/actions/reference/workflows-and-actions/reusing-workflow-configurations)
## Runners and Execution
- [GitHub-hosted runners](https://docs.github.com/en/actions/concepts/runners/github-hosted-runners)
- [Using GitHub-hosted runners](https://docs.github.com/en/actions/how-tos/manage-runners/github-hosted-runners/use-github-hosted-runners)
- [Choosing the runner for a job](https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/choose-the-runner-for-a-job)
- [Running jobs in a container](https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/run-jobs-in-a-container)
- [Self-hosted runners](https://docs.github.com/en/actions/concepts/runners/self-hosted-runners)
- [Larger runners](https://docs.github.com/en/actions/concepts/runners/larger-runners)
- [Actions Runner Controller](https://docs.github.com/en/actions/concepts/runners/actions-runner-controller)
- [Get started with Actions Runner Controller](https://docs.github.com/en/actions/tutorials/use-actions-runner-controller/get-started)
## Security and Supply Chain
- [Secure use reference](https://docs.github.com/en/actions/reference/security/secure-use)
- [Secrets](https://docs.github.com/en/actions/concepts/security/secrets)
- [GITHUB_TOKEN](https://docs.github.com/en/actions/concepts/security/github_token)
- [OpenID Connect](https://docs.github.com/en/actions/concepts/security/openid-connect)
- [OpenID Connect reference](https://docs.github.com/en/actions/reference/security/oidc)
- [Artifact attestations](https://docs.github.com/en/actions/concepts/security/artifact-attestations)
- [Using artifact attestations to establish provenance for builds](https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations)
- [Using OpenID Connect with reusable workflows](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-with-reusable-workflows)
- [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws)
## Deployments and Environments
- [Deployment environments](https://docs.github.com/en/actions/concepts/workflows-and-actions/deployment-environments)
- [Deployments and environments](https://docs.github.com/en/actions/reference/workflows-and-actions/deployments-and-environments)
- [Deploying with GitHub Actions](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments)
- [Managing environments for deployment](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)
- [Reviewing deployments](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/review-deployments)
- [Viewing deployment history](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/view-deployment-history)
- [Deploying to Amazon Elastic Container Service](https://docs.github.com/en/actions/how-tos/deploy/deploy-to-third-party-platforms/amazon-elastic-container-service)
- [Deploying Node.js to Azure App Service](https://docs.github.com/en/actions/how-tos/deploy/deploy-to-third-party-platforms/nodejs-to-azure-app-service)
## Custom Actions and Publishing
- [About custom actions](https://docs.github.com/en/actions/concepts/workflows-and-actions/custom-actions)
- [Metadata syntax reference](https://docs.github.com/en/actions/reference/workflows-and-actions/metadata-syntax)
- [Managing custom actions](https://docs.github.com/en/actions/how-tos/create-and-publish-actions/manage-custom-actions)
- [Creating a JavaScript action](https://docs.github.com/en/actions/tutorials/create-actions/create-a-javascript-action)
- [Creating a composite action](https://docs.github.com/en/actions/tutorials/create-actions/create-a-composite-action)
- [Creating a third party CLI action](https://docs.github.com/en/actions/how-tos/create-and-publish-actions/create-a-cli-action)
- [Publishing actions in GitHub Marketplace](https://docs.github.com/en/actions/how-tos/create-and-publish-actions/publish-in-github-marketplace)
- [Releasing and maintaining actions](https://docs.github.com/en/actions/how-tos/create-and-publish-actions/release-and-maintain-actions)
## Monitoring, Logs, and Troubleshooting
- [Using the visualization graph](https://docs.github.com/en/actions/how-tos/monitor-workflows/use-the-visualization-graph)
- [Viewing workflow run history](https://docs.github.com/en/actions/how-tos/monitor-workflows/view-workflow-run-history)
- [Using workflow run logs](https://docs.github.com/en/actions/how-tos/monitor-workflows/use-workflow-run-logs)
- [Viewing job condition expression logs](https://docs.github.com/en/actions/how-tos/monitor-workflows/view-job-condition-logs)
- [Enabling debug logging](https://docs.github.com/en/actions/how-tos/monitor-workflows/enable-debug-logging)
- [Troubleshooting workflows](https://docs.github.com/en/actions/how-tos/troubleshoot-workflows)
- [Viewing GitHub Actions metrics](https://docs.github.com/en/actions/how-tos/administer/view-metrics)
## Migration and Tutorials
- [Migrating to GitHub Actions](https://docs.github.com/en/actions/tutorials/migrate-to-github-actions)
- [Automating migration with GitHub Actions Importer](https://docs.github.com/en/actions/tutorials/migrate-to-github-actions/automated-migrations/use-github-actions-importer)
- [Migrating from Jenkins to GitHub Actions](https://docs.github.com/en/actions/tutorials/migrate-to-github-actions/manual-migrations/migrate-from-jenkins)
- [Migrating from CircleCI to GitHub Actions](https://docs.github.com/en/actions/tutorials/migrate-to-github-actions/manual-migrations/migrate-from-circleci)
- [Migrating from GitLab CI/CD to GitHub Actions](https://docs.github.com/en/actions/tutorials/migrate-to-github-actions/manual-migrations/migrate-from-gitlab-cicd)
- [Building and testing Node.js](https://docs.github.com/en/actions/tutorials/build-and-test-code/nodejs)
- [Use GITHUB_TOKEN for authentication in workflows](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token)
- [Store and share data with workflow artifacts](https://docs.github.com/en/actions/tutorials/store-and-share-data)
skills/openclaw-secure-linux-cloud/SKILL.md
+159
View File
@@ -0,0 +1,159 @@
---
name: openclaw-secure-linux-cloud
description: Use when self-hosting OpenClaw on a Linux VPS or cloud server, hardening a remote OpenClaw gateway, choosing between SSH tunneling, Tailscale, or reverse-proxy exposure, or reviewing Podman, pairing, sandboxing, token auth, and tool-permission defaults for a secure personal deployment.
---
# OpenClaw Secure Linux Cloud
## Overview
Use this skill for the conservative "deploy first, expose later" pattern for
OpenClaw on a Linux cloud host.
Default to a private control plane:
- Harden the Linux host before exposing anything.
- Keep the gateway bound to `127.0.0.1`.
- Reach the Control UI through an SSH tunnel first.
- Keep token authentication, pairing, and sandboxing enabled.
- Start with a narrow tool profile and loosen only with an explicit need.
This skill is for secure Linux cloud hosting. If the user only wants the
fastest generic OpenClaw install on a local machine, prefer the official
OpenClaw onboarding docs instead of forcing this flow.
Open [references/REFERENCE.md](references/REFERENCE.md) when you need the
command matrix, baseline config shape, checklist, or access-path comparison.
## When To Use
Use this skill when the user mentions any of the following:
- OpenClaw on a Linux server, VPS, VM, or cloud instance
- Secure self-hosting, hardening, or "run it privately"
- Podman, loopback binding, SSH tunneling, or remote Control UI access
- Tailscale vs reverse proxy for OpenClaw
- Pairing, sandboxing, token auth, or locked-down tool permissions
- Reviewing whether an existing OpenClaw host is too exposed
Do not use this skill for:
- General Linux hardening with no OpenClaw component
- Local single-machine onboarding where remote access is irrelevant
- Pure local onboarding with no remote-host hardening questions
- Non-Linux hosting unless the user explicitly wants this Linux-first pattern
adapted
## Workflow
### 1. Classify the request
Put the task in one of these buckets before giving detailed guidance:
1. **Fresh deploy**: the user wants to stand up OpenClaw securely on a Linux
cloud host from scratch.
2. **Hardening review**: the user already has OpenClaw running and wants to
reduce exposure or audit risky defaults.
3. **Access-model decision**: the user is choosing between SSH tunneling,
Tailscale, or a reverse proxy.
### 2. Start from the secure baseline
Unless the user clearly asks for something else, recommend this baseline:
- Harden the Linux host first: updates, SSH keys, SSH lock-down, and a
default-deny inbound firewall matched to the distro.
- Run OpenClaw under rootless Podman rather than as a root-owned long-lived
process.
- Keep the gateway on loopback only.
- Keep the Control UI private and access it through an SSH tunnel.
- Require token authentication.
- Keep pairing enabled for inbound messaging channels.
- Start with a minimal tool set and sandbox sessions by default.
Treat these as explicit red flags:
- Binding the gateway to `0.0.0.0`
- Opening port `18789` to the public internet
- Turning on broad runtime, filesystem, automation, or browser access by
default
- Leaving `~/.openclaw` readable by other local users
### 3. Separate local and server actions
Always distinguish between:
- **Local machine actions**: SSH key generation, tunnel setup, browser access
- **Server actions**: Linux hardening, Podman install path, OpenClaw service
setup, config permissions, service restarts
Do not blur the two execution contexts together. The user should be able to
tell which commands run on their laptop and which run on the Linux host.
### 4. Ask only for blocking facts
Only stop for missing facts that change the safe path, such as:
- Linux distro and host access details when package-manager or firewall
commands matter
- Whether OpenClaw is already installed
- Whether the user truly needs repeated remote private access or public access
- Whether an existing deployment is already reachable from the internet
If a detail is not safety-critical, make the reasonable secure assumption and
state it.
### 5. Use the access escalation ladder
Recommend remote access in this order:
1. **SSH tunnel**: default for first deployment and personal use
2. **Tailscale**: next step when the user needs repeated private access across
trusted devices
3. **Reverse proxy**: only when the user explicitly needs public exposure and
accepts the extra hardening burden
If the user asks for Tailscale or reverse proxy, still explain why the loopback
binding and private-first model remain the baseline.
## Output Expectations
For a fresh deployment, provide:
- A short architecture summary
- Local-vs-server steps
- A conservative config baseline
- A pre-launch checklist
- A short "what not to expose" warning
For a hardening review, provide:
- The likely risks in the current setup
- A prioritized remediation sequence
- Any immediate exposure concerns to fix before anything else
For an access-path decision, provide:
- A recommendation
- Why it is the lowest-risk fit
- What extra safeguards are required if the user chooses a broader exposure
model
## Common Mistakes
- Treating OpenClaw like a normal public web app on day one
- Assuming auth alone replaces network boundaries
- Turning on more tool power before the user has a clear workflow that needs it
- Disabling pairing just to save time during early setup
- Skipping follow-up audits after changing config or sandbox settings
## Reference Usage
Use [references/REFERENCE.md](references/REFERENCE.md) when you need:
- The cross-distro hardening flow and Debian/Ubuntu example commands
- The Podman-based OpenClaw setup outline
- The baseline config skeleton
- The pre-launch checklist
- The day-to-day audit commands
- The SSH tunnel vs Tailscale vs reverse-proxy comparison
skills/openclaw-secure-linux-cloud/references/REFERENCE.md
+344
View File
@@ -0,0 +1,344 @@
# OpenClaw Secure Linux Cloud Reference
This reference supports the `openclaw-secure-linux-cloud` skill.
It adapts the deployment pattern from Xi Xu's Debian-focused article, "Run
OpenClaw Securely on a Debian Cloud Server: A Complete Guide from Setup to
Hardening," published on March 13, 2026, along with current upstream OpenClaw
repository guidance. The package names and firewall commands in the article are
Debian-specific, but the security model generalizes well to Linux cloud hosts.
Source article:
[Xi Xu's Blog](https://blog.xi-xu.me/en/2026/03/13/Run-OpenClaw-Securely-On-Debian-Cloud-Server.html)
License note:
The source article is published under CC BY-SA 4.0. Keep attribution intact if
you redistribute derivative guidance from this bundle.
Maintainer note:
The security posture in this bundle is intentionally conservative and tied to
the article's March 13, 2026 recommendations. Check current upstream OpenClaw
docs and commands before future edits, because onboarding, config keys,
operational commands, and distro-specific package or firewall guidance may
drift over time.
## Architecture Summary
Target end state:
- Linux host exposes only SSH by default
- OpenClaw runs under rootless Podman
- The gateway listens on loopback only
- The Control UI is reached through an SSH tunnel
- Token authentication stays enabled
- Pairing stays enabled for inbound channels
- Tool access stays narrow by default
- Sandboxing remains enabled unless there is a deliberate reason to relax it
Core principle:
Treat the OpenClaw gateway as a private control plane, not a public-first web
service.
## Command Matrix
### Local Machine
Use these steps on the machine you are connecting from:
```bash
export VPS_USER="your_admin_user"
export VPS_HOST="your.server.ip.or.domain"
ssh-keygen -t ed25519 -C "openclaw-cloud"
ssh-copy-id "${VPS_USER}@${VPS_HOST}"
ssh "${VPS_USER}@${VPS_HOST}"
```
Create the Control UI tunnel without exposing the gateway publicly:
```bash
export VPS_USER="your_admin_user"
export VPS_HOST="your.server.ip.or.domain"
ssh -N -L 18789:127.0.0.1:18789 "${VPS_USER}@${VPS_HOST}"
```
Then open:
```text
http://127.0.0.1:18789/
```
### Linux Host: Cross-Distro Invariants
Keep these security goals constant even when package names or service
management differ:
- Install the baseline tools needed for Git, TLS helpers, rootless Podman,
firewall management, and unattended security updates.
- Harden SSH only after public-key login works.
- Apply a default-deny inbound firewall and keep the OpenClaw UI port private.
- Run OpenClaw under rootless Podman instead of as a long-lived root process.
- Keep the gateway bound to loopback only.
- Store the gateway token and config with tight per-user permissions.
Typical distro adaptations:
- Debian or Ubuntu: `apt`, `systemctl`, and either `nftables` or `ufw`
- Fedora, RHEL, Rocky, AlmaLinux: `dnf`, `systemctl`, and often `firewalld`
- Arch: `pacman`, `systemctl`, and distro-specific firewall preferences
If the distro is unknown and concrete commands are required, ask which distro
the host runs instead of pretending the Debian package names are universal.
### Debian/Ubuntu Example Commands
Update the host and install baseline packages:
```bash
sudo apt update
sudo apt full-upgrade -y
sudo apt install -y git curl openssl podman nftables unattended-upgrades apt-listchanges
```
Enable automatic security updates:
```bash
sudo tee /etc/apt/apt.conf.d/20auto-upgrades >/dev/null <<'EOF'
APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";
EOF
sudo systemctl enable --now unattended-upgrades
```
Harden SSH after key-based login works:
```bash
sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.bak.$(date +%F-%H%M%S)
sudo tee /etc/ssh/sshd_config.d/99-openclaw-hardening.conf >/dev/null <<'EOF'
PubkeyAuthentication yes
PasswordAuthentication no
KbdInteractiveAuthentication no
ChallengeResponseAuthentication no
PermitRootLogin no
UsePAM yes
X11Forwarding no
EOF
sudo sshd -t
sudo systemctl reload ssh
```
Apply a default-deny inbound firewall that leaves only SSH reachable:
```bash
sudo tee /etc/nftables.conf >/dev/null <<'EOF'
flush ruleset
table inet filter {
chain input {
type filter hook input priority 0;
policy drop;
iif lo accept
ct state established,related accept
tcp dport 22 accept
ip protocol icmp accept
ip6 nexthdr icmpv6 accept
}
chain forward {
type filter hook forward priority 0;
policy drop;
}
chain output {
type filter hook output priority 0;
policy accept;
}
}
EOF
sudo systemctl enable --now nftables
sudo nft -f /etc/nftables.conf
sudo nft list ruleset
```
Install OpenClaw from source with the Podman helper:
```bash
cd /opt
sudo git clone https://github.com/openclaw/openclaw.git
cd /opt/openclaw
sudo ./setup-podman.sh --quadlet
```
Check the service and logs:
```bash
sudo systemctl --machine openclaw@ --user status openclaw.service
sudo journalctl --machine openclaw@ --user -u openclaw.service -f
```
Run the initial setup flow:
```bash
cd /opt/openclaw
sudo ./scripts/run-openclaw-podman.sh launch setup
```
View the generated gateway token:
```bash
sudo -u openclaw grep '^OPENCLAW_GATEWAY_TOKEN=' /home/openclaw/.openclaw/.env
```
Restart after config changes:
```bash
sudo systemctl --machine openclaw@ --user restart openclaw.service
sudo systemctl --machine openclaw@ --user status openclaw.service
```
## Baseline Config Skeleton
Use this as a conservative starting shape on Linux, then verify the exact keys
against current upstream docs before applying it to a live system:
```json5
{
gateway: {
mode: "local",
bind: "loopback",
port: 18789,
controlUi: { enabled: true },
auth: {
mode: "token",
token: "${OPENCLAW_GATEWAY_TOKEN}",
},
},
session: {
dmScope: "per-channel-peer",
},
tools: {
profile: "messaging",
fs: { workspaceOnly: true },
deny: [
"group:runtime",
"group:fs",
"group:automation",
"browser",
"sessions_spawn",
],
},
agents: {
defaults: {
sandbox: {
mode: "all",
scope: "agent",
workspaceAccess: "none",
},
},
},
}
```
Lock down the config directory after writing the config:
```bash
sudo chmod 700 /home/openclaw/.openclaw
sudo chmod 600 /home/openclaw/.openclaw/openclaw.json
sudo chown -R openclaw:openclaw /home/openclaw/.openclaw
```
## Pairing and Day-Two Operations
Pairing should remain enabled unless the user has a strong reason to widen DM
access.
Typical pairing review and approval flow:
```bash
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
openclaw pairing list signal
openclaw pairing approve signal <CODE>
```
Day-two audit and health checks:
```bash
openclaw security audit
openclaw security audit --deep
openclaw security audit --fix
openclaw secrets audit
openclaw doctor
```
If sandbox policy changes later, recreate sandboxes so old state does not mask
the new policy:
```bash
openclaw sandbox recreate --all
```
## Access-Path Decision Table
| Need | Recommended path | Why | Main caution |
| ---------------------------------------------- | ---------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------- |
| First secure deployment | SSH tunnel | Smallest exposed surface and easiest to reason about | Requires an SSH session when you want the UI |
| Repeated private access across trusted devices | Tailscale | More convenient while keeping access private-first | Keep loopback binding and verify current upstream Tailscale docs |
| Intentional public exposure | Reverse proxy | Only for explicit public or broader remote access needs | Requires stronger auth, tighter monitoring, and more careful boundary design |
Decision rule:
1. Start with SSH tunneling.
2. Move to Tailscale when private convenience becomes a real need.
3. Consider a reverse proxy only after the private options no longer fit.
## Common Pitfalls
- Binding the gateway directly to `0.0.0.0`
- Allowing port `18789` through the firewall just because auth exists
- Enabling broad tool access before the user knows what capabilities they
really need
- Leaving `~/.openclaw` or the config file too open
- Disabling pairing just to shorten onboarding
- Treating the initial setup as the end of the job and skipping audits
## Pre-Launch Checklist
- SSH key login works
- Direct root login is disabled
- SSH passwords are disabled
- Automatic security updates are enabled
- Inbound firewall policy is deny-by-default
- Only SSH is intentionally exposed
- OpenClaw stays on loopback
- The Control UI is not public
- Token auth is enabled
- `~/.openclaw` permissions are tight
- Tool defaults are narrow
- Sandboxing is enabled
- Pairing is preserved
- Security and health checks have been run
## Scope Boundary
This bundle is intentionally Linux-specific and centered on the article's
private-first deployment pattern, with Debian or Ubuntu shown as the clearest
example path.
If the user wants:
- a generic local install
- a non-Linux system
- a Docker Compose tutorial
- a public SaaS-style deployment
then adapt carefully or defer to current upstream OpenClaw docs instead of
pretending these Debian/Ubuntu example commands are universal.
skills/opensource-guide-coach/SKILL.md
+220
View File
@@ -0,0 +1,220 @@
---
name: opensource-guide-coach
description: Use when a user wants guidance on starting, contributing to, growing, governing, funding, securing, or sustaining an open source project, or asks about contributor onboarding, community health, maintainer burnout, code of conduct, metrics, legal basics, or open source project adoption.
---
# Open Source Guide Coach
## Overview
Use the official Open Source Guides as a coaching framework for open source questions.
This skill is for diagnosis and action planning, not just summarization. Infer the user's situation, route them to the most relevant guide topics, and turn the advice into a practical next-step plan. Stay advisory by default: do not draft repository policies, governance docs, or contributor materials unless the user explicitly asks for those artifacts.
## Source Of Truth
- Use the official Open Source Guides site: `https://opensource.guide/`
- Use [`references/guide-map.md`](references/guide-map.md) to select the right topic quickly
- Use [`references/persona-router.md`](references/persona-router.md) to infer the closest audience persona
- Use [`references/attribution.md`](references/attribution.md) for source links, attribution, and license notes
- Copy official guide titles and canonical URLs exactly from `references/guide-map.md`
Treat the guides as curated community practice, not binding policy. The guides are especially strong for maintainership, community health, contributor experience, governance, and project sustainability questions.
## When To Use
Use this skill when the user is trying to:
- decide whether or how to open source a project
- attract users or contributors
- improve onboarding or contribution flow
- reduce maintainer overload or burnout
- set governance or decision-making expectations
- adopt or enforce a code of conduct
- choose useful project metrics
- think about funding or sustainability
- understand open source legal basics
- tighten project security practices
Do not use this skill for:
- GitHub product how-to questions that need product docs
- repository-specific legal advice that requires a lawyer
- deep software security implementation guidance unrelated to open source project operations
## Working Style
### 1. Identify the situation
Infer:
- the closest persona
- the project stage: considering launch, early launch, growing, overwhelmed, or formalizing
- the main pain point
- whether the user wants advice, a checklist, or actual drafted artifacts
If details are missing, make a reasonable inference and state it briefly. Do not interrogate the user for every unknown if a safe assumption will do.
### 2. Choose the smallest useful guide set
Pick `1-3` guide topics.
- Use `1` guide for narrow questions
- Use `2` guides for common combined situations
- Use `3` guides only when the request clearly spans multiple concerns
Do not dump the entire guide catalog on the user.
### 3. Convert guidance into action
Translate the guide themes into a prioritized plan that fits the user's scale.
- Prefer the next `3-6` concrete actions
- Match the level of process to the maturity of the project
- Avoid recommending heavyweight governance or documentation too early
- Keep the plan practical for solo maintainers and volunteer projects
### 4. Link back to the official source
For each recommended guide, include the official `opensource.guide` URL and one short sentence on why it applies.
- Use the canonical URL from `references/guide-map.md`
- Do not shorten, guess, or rewrite article slugs
- Use the official article title exactly as written in `references/guide-map.md`
### 5. Stay advisory by default
Unless the user explicitly asks for drafting help:
- do not write a full `CONTRIBUTING.md`
- do not write a governance charter
- do not write a code of conduct
- do not generate a full legal policy
If the user does ask for an artifact, say which guide(s) you are basing it on and then draft only the requested artifact.
## Routing Heuristics
Reach for these patterns first:
- Launch decision, project scope, expectations, readiness: `starting-a-project`
- How newcomers can help, contribution flow, first PR path: `how-to-contribute`
- Adoption, awareness, project discovery: `finding-users`
- Welcoming environment, community participation, contributor experience: `building-community`
- Maintainer workload, process clarity, saying no, automation: `best-practices`
- Shared decision-making, leadership models, formal rules: `leadership-and-governance`
- Sustainability, sponsorship, funding models: `getting-paid`
- Behavior expectations and enforcement norms: `code-of-conduct`
- Measuring health and progress: `metrics`
- Licensing and legal basics: `legal`
- Burnout, boundaries, maintainership balance: `maintaining-balance-for-open-source-maintainers`
- Security hygiene, project trust, dependency and vulnerability practices: `security-best-practices-for-your-project`
Common pairings:
- First launch + adoption: `starting-a-project` + `finding-users`
- Contributor growth + community experience: `how-to-contribute` + `building-community`
- Maintainer overload + burnout: `best-practices` + `maintaining-balance-for-open-source-maintainers`
- Governance + conduct expectations: `leadership-and-governance` + `code-of-conduct`
- Trust + sustainability for mature projects: `security-best-practices-for-your-project` + `best-practices` or `getting-paid`
Canonical title reminders:
- `starting-a-project` -> `Starting an Open Source Project`
- `code-of-conduct` -> `Your Code of Conduct`
- `security-best-practices-for-your-project` -> `Security Best Practices for your Project`
## Response Contract
Always use this structure:
Respond in plain Markdown only.
- Do not emit pseudo-tool calls
- Do not emit XML-like tags
- Do not emit internal reasoning markers
- Do not rename the section headings below
- If you begin responding, complete all five sections
- Never return empty wrappers, placeholders, or partial scaffolding
## Situation
State the inferred persona, project stage, and main challenge in plain language. If you made an assumption, note it in one sentence.
## Relevant Guides
List `1-3` guides. For each one include:
- official title copied exactly from `references/guide-map.md`, including capitalization
- why it applies here
- official URL
Preferred format:
`**Official Title**`
`Why it applies: ...`
`URL: https://opensource.guide/...`
## Recommended Next Steps
Provide a prioritized numbered list. Keep it concrete and proportionate to the user's scale.
## Watch-outs
Call out risks, anti-patterns, or ways the user could over-process the problem.
## Optional deeper reading
Include any extra guide links only if they are genuinely useful. If not, say that the guides above are enough for now.
Mini example:
## Situation
You are an early-stage solo maintainer deciding whether your side project is ready for open source.
## Relevant Guides
**Starting an Open Source Project**
Why it applies: It helps you decide whether to launch now and what basics to prepare first.
URL: https://opensource.guide/starting-a-project/
## Recommended Next Steps
1. Clarify the project scope and your maintenance boundaries.
2. Add a license, README, and minimal contributor expectations.
3. Share with a small early audience before a broader announcement.
## Watch-outs
Do not over-promise support or add heavyweight process before you need it.
## Optional deeper reading
If you want to think about early contributor experience, read How to Contribute to Open Source next.
## Quality Bar
Your answer should:
- sound like coaching, not policy boilerplate
- reflect the likely persona and maturity level
- use official guide links, not third-party summaries
- avoid presenting legal content as legal advice
- avoid copying long passages from the source material
- leave the user with a clear next move
## Escalation Rules
Escalate carefully when:
- the user is asking for legal certainty rather than general guidance
- the user needs incident response or code-level security help
- the user wants formal governance that may be disproportionate for a tiny project
- the user is clearly burned out and needs boundaries more than process
In those cases, keep the recommendation practical and say what this skill can and cannot confidently cover.
skills/opensource-guide-coach/references/attribution.md
+44
View File
@@ -0,0 +1,44 @@
# Attribution And Source Notes
This skill is based on the official Open Source Guides project and should keep attribution attached to the source material it summarizes.
## Primary Sources
- Open Source Guides site: `https://opensource.guide/`
- Upstream repository: `https://github.com/github/opensource.guide`
- Repository README: `https://github.com/github/opensource.guide/blob/main/README.md`
- Personas: `https://github.com/github/opensource.guide/blob/main/docs/personas.md`
- Content model: `https://github.com/github/opensource.guide/blob/main/docs/content-model.md`
- Style guide: `https://github.com/github/opensource.guide/blob/main/docs/styleguide.md`
## Article URLs
- `https://opensource.guide/starting-a-project/`
- `https://opensource.guide/how-to-contribute/`
- `https://opensource.guide/finding-users/`
- `https://opensource.guide/building-community/`
- `https://opensource.guide/best-practices/`
- `https://opensource.guide/leadership-and-governance/`
- `https://opensource.guide/getting-paid/`
- `https://opensource.guide/code-of-conduct/`
- `https://opensource.guide/metrics/`
- `https://opensource.guide/legal/`
- `https://opensource.guide/maintaining-balance-for-open-source-maintainers/`
- `https://opensource.guide/security-best-practices-for-your-project/`
## License Notes
Per the upstream README, Open Source Guides content is released under `CC-BY-4.0`.
Use this skill in a way that respects that license:
- summarize in your own words
- link back to the official source
- preserve attribution when quoting or closely paraphrasing
- avoid bundling large copied sections of article text into the skill
## Scope Notes
- The guides represent curated community practice, not legal advice.
- The guides are not GitHub-product documentation.
- Legal and security sections should be framed as general guidance unless the user asks for deeper domain-specific help.
skills/opensource-guide-coach/references/guide-map.md
+40
View File
@@ -0,0 +1,40 @@
# Open Source Guides Map
Use this file to route open source questions to the smallest useful set of official guide topics.
## Current English Guide Set
| Slug | Official title | Use when | Common signals | Official URL |
| ------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `starting-a-project` | Starting an Open Source Project | Someone is deciding whether to open source a project or wants to prepare for launch. | "should I open source this", "what do I need before launch", "how do I start" | `https://opensource.guide/starting-a-project/` |
| `how-to-contribute` | How to Contribute to Open Source | The user wants better contributor onboarding or wants to help with an open source project. | "how can people contribute", "first contribution", "new contributor path" | `https://opensource.guide/how-to-contribute/` |
| `finding-users` | Finding Users for Your Project | The project exists, but adoption, discoverability, or user feedback is weak. | "how do we get users", "nobody knows about the project", "how do we grow adoption" | `https://opensource.guide/finding-users/` |
| `building-community` | Building Welcoming Communities | The user wants a healthier community experience, better participation, or a more inclusive project culture. | "community health", "welcoming contributors", "participation", "inclusive project" | `https://opensource.guide/building-community/` |
| `best-practices` | Best Practices for Maintainers | Maintainers need clearer process, healthier boundaries, or better ways to handle incoming work. | "too many issues", "too many PRs", "how do I say no", "maintainer process" | `https://opensource.guide/best-practices/` |
| `leadership-and-governance` | Leadership and Governance | The project needs shared decision-making, clearer authority, or formal governance norms. | "who decides", "governance", "maintainers vs contributors", "decision process" | `https://opensource.guide/leadership-and-governance/` |
| `getting-paid` | Getting Paid for Open Source Work | The user is exploring sustainability, sponsorship, grants, or business support for the project. | "funding", "sponsor", "how do we sustain this", "can maintainers get paid" | `https://opensource.guide/getting-paid/` |
| `code-of-conduct` | Your Code of Conduct | The project needs behavior expectations, enforcement norms, or healthier interaction standards. | "code of conduct", "moderation", "harassment", "community rules" | `https://opensource.guide/code-of-conduct/` |
| `metrics` | Open Source Metrics | The user wants to measure project health, impact, contributor flow, or growth without guessing. | "what should we measure", "metrics", "health indicators", "success" | `https://opensource.guide/metrics/` |
| `legal` | The Legal Side of Open Source | The user has licensing or legal-basics questions about operating an open source project. | "license", "legal", "can I use this", "what should we choose" | `https://opensource.guide/legal/` |
| `maintaining-balance-for-open-source-maintainers` | Maintaining Balance for Open Source Maintainers | A maintainer is overwhelmed, burned out, or struggling to protect time and energy. | "burned out", "too much maintenance", "need a break", "exhausted" | `https://opensource.guide/maintaining-balance-for-open-source-maintainers/` |
| `security-best-practices-for-your-project` | Security Best Practices for your Project | The user wants to improve project trust through maintainership-level security hygiene and disclosure practices. | "security posture", "responsible disclosure", "dependency safety", "trust" | `https://opensource.guide/security-best-practices-for-your-project/` |
## Quick Pairings
- New project with unclear launch readiness: `starting-a-project`
- New project plus growth concerns: `starting-a-project` + `finding-users`
- Better contributor funnel: `how-to-contribute` + `building-community`
- Maintainer overload: `best-practices`
- Maintainer overload plus burnout: `best-practices` + `maintaining-balance-for-open-source-maintainers`
- Decision bottlenecks or unclear authority: `leadership-and-governance`
- Governance plus interaction norms: `leadership-and-governance` + `code-of-conduct`
- Sustainability planning: `getting-paid`
- Measuring impact after launch: `metrics`
- Trust and project hygiene: `security-best-practices-for-your-project`
## Routing Notes
- Prefer the user's pain point over the broadest article.
- Avoid pairing `legal` unless the user is clearly asking about licensing or legal concerns.
- Avoid sending a first-time maintainer into formal governance too early unless the problem is really about decision-making.
- `best-practices` is often the anchor article for maintainers; add a second guide only when the pain point is clearly broader.
skills/opensource-guide-coach/references/persona-router.md
+27
View File
@@ -0,0 +1,27 @@
# Persona Router
Use this table to infer the closest audience persona from the official Open Source Guides personas.
## Quick Decision Table
| Persona | Best fit when | Likely goals | Common pain points | Good first guides |
| ---------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Individual developer (first-timer) | One person is thinking about open sourcing a project for the first time. | Launch well, get noticed, get early feedback. | Unsure whether to open source yet, unclear on readiness, no audience yet. | `starting-a-project`, `finding-users`, `how-to-contribute` |
| Individual developer (multiple projects) | An experienced solo maintainer runs one or more projects, usually on personal time. | Protect time, reduce overload, find help, keep the project sustainable. | Burnout, issue queue pressure, contributor management, unclear boundaries. | `best-practices`, `maintaining-balance-for-open-source-maintainers`, `getting-paid` |
| Community developer | The project is intentionally shared with the community and decisions are not purely personal. | Encourage participation, keep the community healthy, share ownership well. | Community friction, unclear norms, contribution quality, decision disputes. | `building-community`, `how-to-contribute`, `leadership-and-governance`, `code-of-conduct` |
| Corporate entity | A company or formal team is opening a project or maintaining it as part of paid work. | Grow usage, support brand and recruiting goals, balance company and community needs. | Balancing company constraints with community expectations, adoption, governance, security, legal concerns. | `starting-a-project`, `finding-users`, `leadership-and-governance`, `security-best-practices-for-your-project`, `legal` |
## Inference Rules
- If the user says "my side project", "my library", or "I built this on weekends", start with `Individual developer (first-timer)` unless they clearly describe prior maintainer experience.
- If the user sounds overloaded, mentions issue triage fatigue, or has multiple maintained projects, route toward `Individual developer (multiple projects)`.
- If the user emphasizes shared ownership, community voting, working groups, or consensus, route toward `Community developer`.
- If the user says "we" from a company context, mentions brand, compliance, security policy, or recruiting, route toward `Corporate entity`.
## Fallback Rule
If the persona is ambiguous, choose the smallest-scope persona that still matches the pain point and say the assumption in the `Situation` section.
Example:
`I am assuming this is an early-stage solo-maintainer question because you described a side project and did not mention an existing maintainer team.`
skills/running-claude-code-via-litellm-copilot/SKILL.md
+265
View File
@@ -0,0 +1,265 @@
---
name: running-claude-code-via-litellm-copilot
description: Use when routing Claude Code through a local LiteLLM proxy to GitHub Copilot, reducing direct Anthropic spend, configuring ANTHROPIC_BASE_URL or ANTHROPIC_MODEL overrides, or troubleshooting Copilot proxy setup failures such as model-not-found, no localhost traffic, or GitHub 401/403 auth errors.
---
# Running Claude Code via LiteLLM and GitHub Copilot
## Overview
Use this skill for the specific workaround where Claude Code keeps its Anthropic-shaped client behavior, but the actual backend traffic is sent to a local LiteLLM proxy and then forwarded to GitHub Copilot.
Treat this as an advanced workaround, not an officially guaranteed GitHub workflow. Help the user succeed technically, but do not promise GitHub support, policy approval, or long-term compatibility.
This skill is guidance-first but execution-aware:
- If the user wants explanation only, provide the smallest correct set of files, commands, and checks.
- If the user wants real setup work on the current machine, inspect first and adapt commands to the active shell and OS.
- Pause before persistent edits such as `~/.claude/settings.json` or shell profile files.
Read [references/doc-verified-notes.md](references/doc-verified-notes.md) before answering if you need to justify which parts come from the article and which parts were tightened against current LiteLLM docs.
## When To Use
Use this skill when the user wants any of the following:
- Claude Code to run against GitHub Copilot through LiteLLM
- lower direct Anthropic API spending while keeping the Claude Code workflow
- a local `config.yaml` for LiteLLM's GitHub Copilot provider
- `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`, or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` setup
- help understanding GitHub device authorization during LiteLLM startup
- help with model mismatch, 404-like errors, no requests reaching LiteLLM, or GitHub 401/403 failures
Do not use this skill for:
- deciding whether the workaround is allowed by GitHub terms
- general LiteLLM architecture unrelated to Claude Code plus Copilot
- direct Anthropic API setup with no Copilot or LiteLLM component
## Core Rules
1. Lead with a short compliance caveat.
Explain that this is a workaround based on a local proxy path, not a GitHub-promoted workflow, and the user must evaluate the latest Copilot terms and limits for themselves.
2. Prefer the minimum viable path first.
Start with temporary environment variables and a local `config.yaml` unless the user explicitly wants a persistent setup.
3. Keep `ANTHROPIC_MODEL` and LiteLLM `model_name` identical.
Exact string match matters more than clever explanation.
4. Treat `ANTHROPIC_AUTH_TOKEN` as a local placeholder.
Claude Code expects a non-empty value locally, but it is not the GitHub Copilot credential and should not be presented as a reusable secret.
5. Never overwrite `~/.claude/settings.json` wholesale.
Merge only the needed `env` keys and preserve unrelated settings.
## Workflow
### 1. Preflight
Check these first when the user wants real setup work:
- `claude --help` succeeds
- `uv --version` or `pip --version` succeeds
- the user has GitHub Copilot access
- the intended LiteLLM port is available, usually `4000`
If the user only wants instructions, state the prerequisites instead of running them.
### 2. Choose Temporary vs Persistent Setup
Use this rule:
- Temporary setup: preferred default for first-time setup, debugging, and low-risk trials
- Persistent setup: only when the user explicitly wants the proxy path to apply every time Claude Code starts
For persistent setup, confirm the target file and then merge keys into `~/.claude/settings.json`. Do not replace the file contents.
### 3. Create LiteLLM `config.yaml`
Start from the article's flow, but keep the provider naming aligned with LiteLLM docs:
```yaml
model_list:
- model_name: claude-opus-4.5
litellm_params:
model: github_copilot/claude-opus-4.5
drop_params: true
```
Explain the fields:
- `model_name`: the logical name Claude Code will request
- `model`: the LiteLLM provider route, using `github_copilot/<model>`
- `drop_params: true`: strips unsupported Anthropic-specific fields before forwarding to Copilot
If the user wants a different Copilot-backed model, keep the same pattern:
```yaml
model_list:
- model_name: <logical-name>
litellm_params:
model: github_copilot/<copilot-model>
drop_params: true
```
Do not hardcode extra headers into the default path unless the user already hit a rejection that suggests header overrides are needed.
### 4. Install and Start LiteLLM
Preferred install:
```bash
uv tool install "litellm[proxy]"
```
Fallback:
```bash
pip install "litellm[proxy]"
```
Start the proxy from the directory containing `config.yaml`:
```bash
litellm --config config.yaml --port 4000
```
Tell the user to keep that terminal open because the logs are the fastest truth source during verification.
### 5. Explain GitHub Device Authorization
On the first successful request to the GitHub Copilot provider, LiteLLM may open a device authorization flow:
1. LiteLLM prints a verification URL and device code
2. the user opens the URL and approves the request
3. LiteLLM stores the resulting credential locally for future use
Optional token-location overrides exist:
- `GITHUB_COPILOT_TOKEN_DIR`
- `GITHUB_COPILOT_ACCESS_TOKEN_FILE`
Only mention these when the user needs custom token storage, shared environments, or troubleshooting around expired or misplaced credentials.
### 6. Configure Claude Code
For a temporary PowerShell session:
```powershell
$env:ANTHROPIC_AUTH_TOKEN = "sk-any-string"
$env:ANTHROPIC_BASE_URL = "http://localhost:4000"
$env:ANTHROPIC_MODEL = "claude-opus-4.5"
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"
claude
```
For a temporary Bash or Zsh session:
```bash
export ANTHROPIC_AUTH_TOKEN="sk-any-string"
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_MODEL="claude-opus-4.5"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
claude
```
For persistent configuration, merge these keys into `~/.claude/settings.json`:
```json
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "sk-any-string",
"ANTHROPIC_BASE_URL": "http://localhost:4000",
"ANTHROPIC_MODEL": "claude-opus-4.5",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
}
}
```
Merge-safe behavior:
- if the file does not exist, create it
- if it exists, preserve all unrelated top-level keys
- preserve existing `env` entries that are unrelated to this workflow
- update only the four keys above
- if the JSON is malformed, stop and report the parse problem instead of overwriting the file
### 7. Verify The Request Chain
Use two terminals when possible:
- Terminal A runs LiteLLM
- Terminal B runs `claude`
Ask for one small prompt such as a short script or code review request, then verify:
- Claude Code starts normally
- LiteLLM logs show an inbound request
- LiteLLM logs indicate the GitHub Copilot model route, typically `github_copilot/<model>`
The healthy path is:
```text
Claude Code -> LiteLLM -> GitHub Copilot -> LiteLLM -> Claude Code
```
### 8. Troubleshooting
If Claude Code reports model-not-found, 404-like failures, or LiteLLM says the model does not exist:
- compare `ANTHROPIC_MODEL` to `model_name` exactly
- check case, punctuation, and hyphens
If LiteLLM never receives a request:
- confirm `ANTHROPIC_BASE_URL` points to `http://localhost:4000`
- confirm LiteLLM is still running on that port
- confirm the environment variables were set in the same shell session that launched `claude`
- check local firewall or port conflicts if the URL is correct but still silent
If LiteLLM reaches GitHub Copilot but gets 401 or 403 responses:
- repeat the device authorization flow by restarting LiteLLM and retrying
- confirm the GitHub account still has Copilot access
- if custom token-directory variables are set, verify they point to the intended files
## Advanced Fallback: Header Overrides
The article uses explicit Copilot-style headers. Current LiteLLM docs expose GitHub Copilot as a provider and also document header override support.
Only reach for explicit `extra_headers` when:
- the basic provider flow reaches Copilot but still needs client-shape overrides
- the user already has evidence that a specific environment behaves better with editor-style headers
Example fallback:
```yaml
model_list:
- model_name: claude-opus-4.5
litellm_params:
model: github_copilot/claude-opus-4.5
drop_params: true
extra_headers:
editor-version: "vscode/1.85.1"
editor-plugin-version: "copilot/1.155.0"
Copilot-Integration-Id: "vscode-chat"
user-agent: "GithubCopilot/1.155.0"
```
Present this as an advanced fallback, not the universal default.
## Output Checklist
When answering a real user request with this skill, include:
- the brief compliance caveat
- the exact `config.yaml` or the delta to apply
- shell-appropriate commands
- whether the setup is temporary or persistent
- the verification path
- the smallest relevant troubleshooting section if something failed
## Safety Reminders
- Do not state that GitHub officially supports this workaround.
- Do not imply that a dummy `ANTHROPIC_AUTH_TOKEN` is a real Copilot credential.
- Do not recommend replacing `~/.claude/settings.json` wholesale.
- Do not present stale model names as guaranteed current availability; if the user asks for a specific model, keep the `github_copilot/<model>` pattern and note that Copilot-exposed model availability may change.
skills/running-claude-code-via-litellm-copilot/references/doc-verified-notes.md
+66
View File
@@ -0,0 +1,66 @@
# Doc-Verified Notes
This skill is anchored to Xi Xu's article from December 2, 2025:
- [Run Claude Code Cheaply: A Complete Guide to Using LiteLLM with the GitHub Copilot Chat API](https://blog.xi-xu.me/en/2025/12/02/Run-Claude-Code-Cheaply-With-LiteLLM-And-GitHub-Copilot.html)
It is also tightened against current LiteLLM documentation retrieved during package creation:
- LiteLLM GitHub Copilot provider docs, version `v1.81.9-stable`
## Safe Carryovers From The Article
These parts of the article match the current provider model closely enough to keep as the skill's default narrative:
- Claude Code can be pointed at a local LiteLLM endpoint through `ANTHROPIC_BASE_URL`
- Claude Code still expects a non-empty local Anthropic auth token value even though LiteLLM forwards to Copilot instead
- LiteLLM acts as the middle layer between Claude Code and the GitHub Copilot API
- `drop_params: true` remains an important compatibility setting for Anthropic-shaped requests
- the first working request can trigger GitHub device authorization
- verification should be done by watching LiteLLM logs while sending a small Claude Code request
## Doc-Verified Deltas
### Provider naming
The current LiteLLM provider route uses this pattern:
```text
github_copilot/<model>
```
That is the stable rule the skill should teach. The article's example `github_copilot/claude-opus-4.5` still fits this pattern.
### Exact model-name matching
The `ANTHROPIC_MODEL` value in Claude Code must match LiteLLM `model_name` exactly. Treat this as a first-line troubleshooting rule, not a footnote.
### `drop_params: true`
Keep this in the default config examples. It strips Anthropic-specific request fields before forwarding to Copilot and helps avoid avoidable 4xx errors.
### Optional token storage overrides
LiteLLM currently documents these optional environment variables for GitHub Copilot token storage:
- `GITHUB_COPILOT_TOKEN_DIR`
- `GITHUB_COPILOT_ACCESS_TOKEN_FILE`
Only mention them when the user needs custom storage paths or auth troubleshooting. They are not part of the minimum happy path.
### Header overrides are advanced fallback, not default
The article explicitly adds editor-style headers. Current LiteLLM docs also document header override support, but the provider itself is now clearly modeled as `github_copilot/...`.
For this skill, treat explicit `extra_headers` as an advanced fallback when:
- the user already has evidence that header shape matters in their environment
- the basic provider route is reaching Copilot but still needs client emulation tweaks
Do not present custom headers as universally required for the first setup attempt.
## Guidance For Future Revisions
- Preserve the article's user-facing flow because it is clear and practical.
- Prefer current LiteLLM provider mechanics over historical assumptions when they conflict.
- If a user asks for a different Copilot-backed model, keep the `github_copilot/<model>` pattern and avoid claiming that a specific Copilot model is permanently available unless it was re-verified from current docs.
skills/secure-linux-web-hosting/SKILL.md
+164
View File
@@ -0,0 +1,164 @@
---
name: secure-linux-web-hosting
description: Use when setting up, hardening, or reviewing a Linux VPS or cloud server for self-hosting, including DNS, SSH, firewalls, Nginx, static-site hosting, reverse-proxying an app, HTTPS with Let's Encrypt or ACME clients, safe HTTP-to-HTTPS redirects, or optional post-launch network tuning such as BBR.
---
# Secure Linux Web Hosting
## Overview
Use this skill to turn a Linux cloud host into a safely reachable web host
without leaning on stale distro-specific memory or outdated Debian-10-era
tutorials.
This skill keeps the familiar teaching arc of a beginner-friendly server guide,
but turns it into a reusable operator workflow:
1. Intake and routing
2. Prerequisites
3. Secure access
4. Firewall and exposure
5. Web server setup
6. Static site or app proxy
7. HTTPS
8. Validation
9. Optional advanced tuning
Before giving actionable commands, identify the distro family and verify the
current package names, service units, config paths, and ACME-client guidance
against official documentation for the user's distro and chosen tools.
Open [references/workflow-map.md](references/workflow-map.md) first for the
phase sequence, then open the narrower reference file you need.
## When to Use
Use this skill when the user mentions any of the following:
- a Linux VPS, VM, droplet, or cloud server they want to use for hosting
- connecting a domain or DNS A/AAAA record to a server
- SSH login, SSH hardening, root login, keys, ports, or firewall setup
- installing or configuring Nginx for a website
- serving a simple static site from Linux
- putting a small app behind Nginx as a reverse proxy
- HTTPS, Let's Encrypt, Certbot, `acme.sh`, certificate renewal, or redirecting
HTTP to HTTPS
- optional post-setup performance or network tuning such as BBR
Do not use this skill for:
- Kubernetes, PaaS, or full container-orchestrator deployment design
- application-specific build or CI/CD questions where Linux hosting is not the
actual problem
- Windows or macOS host administration
- public multi-tenant production architecture reviews that need a broader SRE
or platform-design treatment
## Workflow
### 1. Intake and classify the current state
Start by identifying:
- distro family or image name
- whether the user has root access, an admin user, or only one live SSH session
- whether DNS already points at the host
- whether the goal is a static site or an app reverse proxy
- whether ports are already exposed
- whether HTTPS is already partially configured
If the distro is unknown, ask for it or have the user inspect `/etc/os-release`
before giving concrete package or service commands.
### 2. Verify current docs before actionable commands
Use bundled references for routing, then verify details against live official
docs before giving commands that depend on current distro behavior.
Always verify:
- package manager commands and package names
- firewall tooling and service names
- SSH service unit names and config include paths
- Nginx package and config layout
- the chosen ACME client's current instructions
If you cannot verify a detail, say so and give high-level guidance instead of
pretending the old Debian tutorial path is universal.
### 3. Keep the phases in order
Walk through the phases in this order unless the user is explicitly asking for
review or remediation of an existing setup:
1. prerequisites
2. secure access
3. firewall and exposure
4. web server
5. choose one hosting branch: static site or app proxy
6. HTTPS
7. validation
8. optional advanced tuning
Do not collapse the static-site branch and reverse-proxy branch into one
default answer. Pick the branch that matches the user's goal.
### 4. Enforce the safety gates
Treat these as hard stop checks:
- Do not recommend changing SSH port, disabling password auth, or disabling
root SSH login until key-based login works in a second SSH session.
- Do not recommend certificate issuance until DNS resolves to the intended host
and the HTTP site or proxy path works as expected.
- Do not force an HTTP-to-HTTPS redirect until HTTPS loads cleanly.
- Do not suggest BBR or similar tuning until secure hosting is already working.
Always distinguish:
- local-machine actions: SSH, DNS checks, browser tests
- server actions: package install, config edits, service reloads, firewall rules
## Output Expectations
For a fresh setup, provide:
- a brief diagnosis of the current state
- the current phase and why it comes next
- local-machine steps separate from server steps
- concrete commands or config snippets only after doc verification
- a verification step after each risky change
- a short "if this fails, check X" branch for the likely mistake at that phase
For a hardening or troubleshooting review, provide:
- the most likely risk or breakage first
- a prioritized remediation sequence
- the first safe verification step before the next config change
## Common Mistakes
- treating Debian-specific commands from an old article as Linux-universal
- hardening SSH in the only active session and locking the user out
- opening application ports directly instead of keeping the app on loopback
- mixing static-file hosting guidance and reverse-proxy guidance in one config
- attempting ACME issuance before DNS or HTTP is actually correct
- forcing redirects before HTTPS is proven
- treating BBR as part of the core setup instead of an optional later step
- ignoring SELinux or AppArmor differences when Nginx can read files on one
distro but not another
## Reference Usage
Use [references/workflow-map.md](references/workflow-map.md) for the phase map,
branching logic, and validation order.
Use [references/distro-routing.md](references/distro-routing.md) when distro
family, package manager, firewall tooling, or config layout matters.
Use [references/nginx-patterns.md](references/nginx-patterns.md) when the user
needs the static-site branch or the reverse-proxy branch.
Use [references/security-and-tls.md](references/security-and-tls.md) for SSH
hardening sequence, firewall posture, certificate issuance, renewal, and
redirect timing.
skills/secure-linux-web-hosting/references/distro-routing.md
+63
View File
@@ -0,0 +1,63 @@
# Distro Routing
Never assume Debian commands on an unknown Linux host.
This reference is for routing and modernization, not for blindly copied
commands. Before you give actionable steps, verify the current docs for the
user's distro family and chosen tools.
## First Questions
Ask these before giving package or service commands:
1. What distro or cloud image is the host using?
2. If the user is unsure, can they check `/etc/os-release`?
3. What firewall tooling is already present?
4. Is the host enforcing SELinux or AppArmor?
5. Is the hosting goal static files or a reverse proxy to an app?
## Family Matrix
| Family | Package manager | Likely firewall tooling | SSH service naming | Notes to verify live |
| --------------------------------- | --------------- | --------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------- |
| Debian / Ubuntu | `apt` | `ufw`, `nftables`, or provider firewalls | commonly `ssh` | package names, drop-in config paths, default sudo setup |
| Fedora / RHEL / Rocky / AlmaLinux | `dnf` | `firewalld` | commonly `sshd` | SELinux contexts, package splits, service enablement |
| Arch | `pacman` | user-chosen; often none by default, `ufw`, `nftables`, or `firewalld` | commonly `sshd` | rolling-package names, manual service enablement, wiki-first workflow |
| Other / unknown | varies | varies | varies | stop and verify instead of guessing |
## What Commonly Differs
These are the details most likely to drift across distros or over time:
- package names for Nginx, ACME clients, firewall helpers, and security updates
- SSH service unit names and include directories
- default web root paths
- firewall commands and persistence model
- SELinux or AppArmor behavior around Nginx file access or proxy connections
- renewal timers or hooks for the chosen ACME client
## Official Docs Entry Points
Use these as starting points when you need live verification:
- Debian docs: <https://www.debian.org/doc/>
- Ubuntu Server documentation: <https://documentation.ubuntu.com/server/>
- Red Hat documentation: <https://docs.redhat.com/>
- ArchWiki main page: <https://wiki.archlinux.org/>
- Nginx documentation: <https://nginx.org/en/docs/>
- Let's Encrypt challenge types: <https://letsencrypt.org/docs/challenge-types/>
- Certbot instructions: <https://certbot.eff.org/instructions>
- `acme.sh` wiki: <https://github.com/acmesh-official/acme.sh/wiki>
If the user is on a cloud-specific image with opinionated defaults, also verify
the provider's image docs before assuming stock distro behavior.
## Modernization Rules
- Treat Debian-10-era tutorials as conceptual background only.
- Do not frame Windows-first tooling such as PuTTY as the default path unless
the user explicitly needs it.
- Prefer the distro's current package-management and service-management docs to
blog posts or memory.
- If a family-specific hardening feature matters, say that it is distro-specific
instead of flattening it into "Linux" advice.
skills/secure-linux-web-hosting/references/nginx-patterns.md
+107
View File
@@ -0,0 +1,107 @@
# Nginx Patterns
This reference keeps the two hosting outcomes separate on purpose:
- static-site hosting
- reverse-proxy hosting
Choose the branch that matches the user's goal. Do not merge both into one
default answer unless the user clearly needs a hybrid setup.
## Shared Preconditions
Before either branch:
- verify the distro-specific Nginx package and config layout from official docs
- install and start Nginx
- validate the config with `nginx -t`
- confirm the service is healthy
- intentionally open ports `80` and `443` only when the web path is ready
## Static-Site Pattern
Use this branch when the user wants Nginx to serve files directly.
Typical ingredients:
- a chosen document root
- an `index.html` or equivalent entry file
- readable file permissions for the Nginx worker account or policy
- a simple `server` block with `root` and `index`
Minimal shape:
```nginx
server {
listen 80;
server_name example.com www.example.com;
root /srv/www/example;
index index.html;
location / {
try_files $uri $uri/ =404;
}
}
```
Verify in this order:
1. `nginx -t`
2. reload Nginx
3. `curl -I http://example.com`
4. open the site in a browser
Common failure branch:
- if the server block looks right but the site fails, check the `root` path,
file permissions, and any SELinux/AppArmor policy before assuming DNS is the
problem
## Reverse-Proxy Pattern
Use this branch when the actual app should stay bound to loopback and Nginx
fronts it.
Safe default:
- the app listens on `127.0.0.1:<port>`
- Nginx is the only public-facing process
Minimal shape:
```nginx
server {
listen 80;
server_name example.com www.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
Verify in this order:
1. confirm the app responds locally on the server first
2. `nginx -t`
3. reload Nginx
4. `curl -I http://example.com`
Common failure branch:
- if Nginx is healthy but the site is down, check whether the app is listening
on the expected loopback port, whether the service is running, and whether
policy controls such as SELinux are blocking the proxy connection
## Branch Boundary Rules
- For a static site, do not invent an upstream app port.
- For a reverse proxy, do not tell the user to expose the app port publicly.
- If the app needs websockets, streaming, or long-lived connections, verify the
extra Nginx directives from current official docs instead of assuming the
minimal proxy block is sufficient.
skills/secure-linux-web-hosting/references/security-and-tls.md
+112
View File
@@ -0,0 +1,112 @@
# Security and TLS
Use this reference for the safe sequencing around SSH hardening, firewall
changes, certificate issuance, renewal, and redirect timing.
## Safe Order of Operations
1. Confirm the user has a recovery path such as a second SSH session, console,
snapshot, or provider rescue option.
2. Confirm key-based SSH login works before tightening authentication.
3. Create or verify a non-root admin path if appropriate for the distro.
4. Validate SSH config changes before reload or restart.
5. Apply a deny-by-default inbound firewall posture.
6. Open only the ports needed for the current phase.
7. Get HTTP working before requesting certificates.
8. Install certificates and verify HTTPS.
9. Only then enable permanent HTTP-to-HTTPS redirect.
10. Treat BBR or kernel/network tuning as optional follow-up work.
## SSH Hardening Goals
The exact commands vary by distro. Verify the current docs before telling the
user to edit config.
The usual goals are:
- key-based authentication works
- password authentication is disabled when safe
- direct root SSH login is disabled when safe
- optional custom SSH port is used only if the user wants it
- only intended admin users can log in
Safety gate:
- never recommend the irreversible parts of SSH hardening from the only active
session
## Firewall Posture
The safe default is:
- deny-by-default inbound policy
- allow SSH intentionally
- add `80` and `443` when the web path is ready
- keep application backends private on loopback
Remember that provider firewalls and host firewalls can both matter.
## TLS Client Choice
Two common paths are reasonable:
| Client | Good fit | What to verify |
| --------- | --------------------------------------------------------------- | ------------------------------------------------------------------ |
| Certbot | users who want distro-packaged guidance and broad documentation | package source, plugin availability, renewal timer behavior |
| `acme.sh` | users who explicitly prefer a lightweight ACME client | current install method, renewal hooks, and Nginx integration steps |
Do not imply that either client is universal. Verify the chosen client against
its upstream docs before giving commands.
## Certificate Issuance Preconditions
Before any ACME issuance step, verify:
- DNS resolves to the intended server
- Nginx answers on HTTP for the expected domain
- firewall and provider rules allow inbound `80` and `443`
- the chosen challenge method matches the user's environment
Useful validation commands:
- `dig +short example.com`
- `curl -I http://example.com`
- `ss -tulpn`
- `nginx -t`
## Redirect Timing
Do not force this until HTTPS already works:
```nginx
return 301 https://$host$request_uri;
```
First confirm that:
- the certificate is installed correctly
- the `server_name` matches the intended domain
- `curl -I https://example.com` succeeds
- the browser does not show certificate warnings
## Common Failure Branches
- DNS points somewhere else, so ACME validation fails
- HTTP is redirected too early, so challenge or validation behavior breaks
- the wrong webroot or vhost handles the ACME challenge
- firewall rules were changed on the host but not at the provider edge
- Nginx can read the config but not the site files or certificate files
- optional tuning work starts before the secure hosting path is stable
## Optional Advanced Tuning
BBR and similar kernel/network changes belong after the secure web stack is
working.
Only recommend them when:
- the user wants the tuning on purpose
- the current kernel path is verified for the distro
- a rollback or rescue path exists
Never let optional tuning preempt basic access, firewall, Nginx, or HTTPS work.
skills/secure-linux-web-hosting/references/workflow-map.md
+84
View File
@@ -0,0 +1,84 @@
# Secure Linux Web Hosting Workflow Map
This reference supports the `secure-linux-web-hosting` skill.
It adapts the conceptual flow of Xi Xu's article, "Build, Configure, and Secure
Your Cloud Server from Scratch and Host a Simple Website," published on
August 25, 2024:
[Xi Xu's Blog](https://blog.xi-xu.me/en/2024/08/25/Launching-a-Cloud-Server-and-Building-a-Website-from-Scratch.html)
The source article is licensed under CC BY-SA 4.0. This bundle keeps the
high-level flow while modernizing the dated distro and tooling assumptions.
## Safe Default Posture
Aim for this end state unless the user explicitly needs something broader:
- Linux host updated and reachable over SSH
- non-root admin access available
- SSH reduced to key-based access after a second-session test
- inbound firewall deny-by-default
- only ports `80` and `443` intentionally exposed for web traffic
- Nginx serving either static files or proxying an app that stays on loopback
- HTTPS working before any permanent redirect
- optional tuning deferred until the secure web path is stable
## Phase Map
| Phase | Goal | Verify before continuing | Common failure if skipped |
| --------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Intake | Identify distro family, access model, DNS state, and hosting goal | The assistant knows whether the user needs static hosting or reverse proxying | Wrong commands, wrong branch, or unsafe assumptions |
| Prerequisites | Confirm server access, domain ownership, DNS plan, and package/doc source of truth | User can log in and knows what domain should resolve where | Chasing web-server issues that are really access or DNS issues |
| Secure access | Establish admin access and harden SSH carefully | Key login works in a second session; SSH config tests cleanly before reload | Lockout after port or auth changes |
| Firewall and exposure | Make the network surface intentional | Only the intended ports are reachable; loopback-only services stay private | App or SSH unexpectedly exposed or blocked |
| Web server base | Install and validate Nginx itself | `nginx -t` succeeds and the service is healthy | Debugging app logic when Nginx is not actually healthy |
| Static-site branch | Serve files directly from Nginx | The site root exists, file permissions are readable, and HTTP serves the expected page | Wrong `root` path or unreadable files |
| App-proxy branch | Put Nginx in front of an app on loopback | The app responds locally before Nginx fronts it | Proxying a dead app or exposing the app port publicly |
| HTTPS | Issue, install, and renew certificates safely | DNS resolves, HTTP works, certificate issuance succeeds, HTTPS loads cleanly | ACME failures, wrong webroot, redirect loops |
| Validation | Confirm the final public behavior and renewal posture | HTTP/HTTPS behavior matches intent and logs look healthy | Hidden breakage left in place |
| Optional tuning | Apply BBR or similar tuning only if useful | Snapshot/rescue path exists and the web stack is already stable | Breaking a working host during non-essential tuning |
## Branch Choice
Choose one application branch unless the user clearly needs both:
- **Static-site branch**: Nginx serves HTML, CSS, JS, and assets from disk.
- **App-proxy branch**: the app listens on `127.0.0.1:<port>` and Nginx fronts
it.
Do not mix the two branches into one default answer. The most common mistake is
giving a reverse-proxy config to a user who only needs file hosting, or a
static-root config to a user whose app must stay on a loopback port.
## Default Validation Sequence
Use a narrow validation loop at each phase:
1. syntax or config validation
2. service reload or restart only if validation passed
3. local check on the server
4. remote check from the user's machine
5. only then move to the next phase
Useful validation commands, depending on distro and tools:
- `nginx -t`
- `systemctl status nginx`
- `ss -tulpn`
- `curl -I http://127.0.0.1:<port>`
- `curl -I http://example.com`
- `curl -I https://example.com`
- `dig +short example.com`
- `openssl s_client -connect example.com:443 -servername example.com`
## Optional Tuning Boundary
BBR, queue discipline changes, and kernel tuning are explicitly optional.
Only suggest them when:
- the site is already securely reachable
- the user wants network tuning on purpose
- the host has a snapshot, rescue console, or other rollback path
Do not treat optional tuning as part of the minimum secure-hosting flow.
skills/skills-cli/SKILL.md
+283
View File
@@ -0,0 +1,283 @@
---
name: skills-cli
description: Use when users ask to discover, install, list, check, update, remove, back up, restore, sync, or initialize Agent Skills, mention `bunx skills`, `npx skills`, `skills.sh`, or `skills-lock.json`, ask "find a skill for X", or want help extending agent capabilities with installable skills.
---
# Skills CLI
Use this skill to help users work with the open Agent Skills ecosystem through the `skills` CLI.
## Overview
The `skills` CLI is the package manager for installable Agent Skills. Use it to discover skills, install them with the right flags, and manage them after installation.
Examples below use `bunx skills`, but `npx skills` is the same workflow if Bun is not available in the user's environment.
Always prefer the current CLI syntax:
```bash
bunx skills add <source> --skill <name>
```
Do not use older `owner/repo@skill-name` examples.
## When to Use
Use this skill when the user:
- asks "find a skill for X", "is there a skill for X", or "how do I do X" and X sounds like a reusable workflow
- asks "can you do X" and X sounds like a specialized capability that may already exist as a skill
- wants help with `bunx skills`, `npx skills`, `skills.sh`, skill package installation, or `skills-lock.json`
- wants to install a skill for a specific agent such as Codex or OpenCode
- wants to list, check, update, remove, restore, sync, back up, or initialize installed skills
- wants help searching for workflows, tools, templates, or domain-specific capabilities such as design, testing, deployment, documentation, or code review
Do not use this skill when the user already has a local skill and wants help writing or improving its contents. In that case, use a skill-authoring workflow instead.
## Discovery Workflow
When a user needs a skill, follow this sequence:
1. Identify the domain and task.
Examples: React performance, PR review, changelog generation, PDF extraction.
Also judge whether the task is common enough that a reusable skill is likely to exist.
2. Check [skills.sh](https://skills.sh/) first.
Prefer well-known, well-installed skills when the domain is already covered there.
3. If the leaderboard does not clearly answer the need, search with:
```bash
bunx skills find <query>
```
1. Verify quality before recommending anything:
- install count: prefer skills with 1K+ installs and be cautious with anything under 100
- source reputation: prefer official or well-established maintainers such as `openai`, `anthropics`, `microsoft`, or similarly trusted publishers
- repository quality: check the source repository and treat skills from repos with fewer than 100 stars skeptically
2. Present the options clearly.
Include the skill name, what it helps with, the install count and source, why it looks trustworthy, the install command, and a link to learn more on `skills.sh`.
3. Offer installation help if the user wants to proceed.
4. If nothing fits, say so directly, help with the task using your general capabilities, and mention that the user can create their own package with `bunx skills init`.
## Installation Quick Reference
### Common sources
```bash
# GitHub shorthand
bunx skills add xixu-me/skills
# Full GitHub URL
bunx skills add https://github.com/xixu-me/skills
# Direct path to one skill inside a repo
bunx skills add https://github.com/xixu-me/skills/tree/main/skills/skills-cli
# GitLab URL
bunx skills add https://gitlab.com/org/repo
# Any git URL
bunx skills add git@github.com:owner/repo.git
# Local package path
bunx skills add ./my-local-skills
```
### Common install patterns
```bash
# List skills in a package without installing
bunx skills add <source> --list
# Install one skill
bunx skills add <source> --skill skills-cli
# Install multiple skills
bunx skills add <source> --skill pr-review --skill commit
# Install globally
bunx skills add <source> --skill skills-cli -g -y
# Install to a specific agent
bunx skills add <source> --skill skills-cli -a codex -y
# Install all skills to all agents
bunx skills add <source> --all
# Install all skills to one agent
bunx skills add <source> --skill '*' -a codex -y
# Copy files instead of symlinking
bunx skills add <source> --skill skills-cli -a codex --copy -y
```
### Installation methods
When the user is choosing how to install:
- symlink is the default and usually the best choice because updates stay centralized
- `--copy` creates independent copies and is the fallback when symlinks are unsupported or inconvenient
If the user only asks to install a skill, prefer the default symlink workflow unless they mention CI packaging, portability, filesystem restrictions, or explicitly ask for copies.
### Important flags
| Flag | Use |
| --------------------- | ---------------------------------------------- |
| `--skill <name>` | install one or more named skills |
| `-a, --agent <agent>` | target specific agents such as `codex` |
| `-g, --global` | install at user scope instead of project scope |
| `-y, --yes` | skip prompts |
| `--list` | list available skills in a package |
| `--copy` | copy instead of symlink |
| `--all` | shorthand for all skills to all agents |
## Managing Installed Skills
Use these commands for ongoing maintenance:
```bash
# List installed skills
bunx skills ls
bunx skills ls -g
bunx skills ls -a codex
bunx skills ls --json
# Check for updates
bunx skills check
# Update installed skills
bunx skills update
# Remove installed skills
bunx skills remove my-skill
bunx skills remove my-skill -a codex
bunx skills remove -g my-skill
bunx skills remove --all
# Initialize a new skill package
bunx skills init
bunx skills init my-skill
# Restore from skills-lock.json
bunx skills experimental_install
# Sync node_modules skills into agent directories
bunx skills experimental_sync
bunx skills experimental_sync -a codex -y
```
When the user asks to initialize a skill, explain whether they want:
- `bunx skills init` to create `SKILL.md` in the current directory
- `bunx skills init <name>` to create a new subdirectory containing `SKILL.md`
## Related Tool: Skills Vault
If the user wants declarative backup and restore of installed skills across machines or teams, use [Skills Vault](https://github.com/xixu-me/skills-vault).
Skills Vault is a separate CLI companion for the `skills` ecosystem. It is not a `skills add` installable skill source. Use it when the user wants to snapshot installed skills into a manifest, preview restore commands, or reproduce the same setup elsewhere.
Common companion commands:
```bash
# Back up installed skills into skvlt.yaml
bunx skvlt backup
# Preview a restore
bunx skvlt restore --dry-run
# Restore everything from the manifest
bunx skvlt restore --all
# Diagnose the local environment
bunx skvlt doctor
```
Prefer this tool over `skills experimental_*` when the user explicitly wants a portable manifest workflow, cross-machine backup and restore, or team-sharing of installed skill setups.
## Recommendation Format
When recommending a skill, keep the answer concrete and installable.
Use a structure like this:
```text
I found a skill that should fit.
Skill: <skill-name>
Why it matches: <one sentence>
Source: <owner/repo or URL>
Quality check: <install count / source reputation / repository confidence note>
Install:
bunx skills add <source> --skill <skill-name> [optional flags]
Learn more: https://skills.sh/<publisher>/<package>/<skill-name>
If you want, I can install it for <agent-or-scope>.
```
If the user mentions a target agent or scope, include it in the command. Examples:
```bash
bunx skills add <source> --skill <skill-name> -a codex -y
bunx skills add <source> --skill <skill-name> -g -y
```
Example:
```text
I found a skill that might help.
Skill: screenshot
Why it matches: it focuses on OS-level desktop and window screenshot capture.
Source: openai/skills
Quality check: high install volume, trusted publisher, and a widely used source repository.
Install:
bunx skills add openai/skills --skill screenshot
Learn more: https://skills.sh/openai/skills/screenshot
```
## Common Skill Categories
When the user's wording is vague, map it to likely categories:
| Category | Example queries |
| --------------- | -------------------------------------------------- |
| Web Development | `react`, `nextjs`, `typescript`, `css`, `tailwind` |
| Testing | `testing`, `jest`, `playwright`, `e2e` |
| DevOps | `deploy`, `docker`, `kubernetes`, `ci-cd` |
| Documentation | `docs`, `readme`, `changelog`, `api-docs` |
| Code Quality | `review`, `lint`, `refactor`, `best-practices` |
| Design | `ui`, `ux`, `design-system`, `accessibility` |
| Productivity | `workflow`, `automation`, `git` |
## Search Tips
- Use specific keywords. `react testing` is better than just `testing`.
- Try alternative terms. If `deploy` fails, try `deployment` or `ci-cd`.
- Check popular sources first. Many strong skills come from established publishers.
- If the first search is too broad, narrow by domain plus task.
## Common Mistakes
- Recommending a skill from search results without checking whether it looks established.
- Forgetting to specify `-a <agent>` when the user asked for one particular agent.
- Treating `bunx skills find --help` like a real help command. Use `bunx skills --help` for command help instead.
- Assuming no skill exists after one weak search term. Try a more specific or adjacent query first.
## Troubleshooting
If the user hits an error or confusing result:
- "No skills found" - suggest a better query, check [skills.sh](https://skills.sh/), or help directly and mention `bunx skills init`
- interactive prompts in automation or CI - add `-y`
- wrong installation scope - switch between project install and `-g`
- symlink issues - retry with `--copy`
- uncertainty about available package contents - run `bunx skills add <source> --list`
- uncertainty about installed state - run `bunx skills ls` or `bunx skills ls --json`
- portable backup or restore across machines - mention [Skills Vault](https://github.com/xixu-me/skills-vault) and its `backup` / `restore --dry-run` workflow
When you are unsure about exact flags, use:
```bash
bunx skills --help
```