commit 48681eec364a41735a5d4ed56303c6349eeb0cc0 Author: Xi Xu Date: Fri Mar 27 16:08:49 2026 +0800 chore: initialize skills repository diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..ecf5a81 --- /dev/null +++ b/.editorconfig @@ -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 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..dfe0770 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +# Auto detect text files and perform LF normalization +* text=auto diff --git a/.github/workflows/markdown-fix.yml b/.github/workflows/markdown-fix.yml new file mode 100644 index 0000000..b954a12 --- /dev/null +++ b/.github/workflows/markdown-fix.yml @@ -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." diff --git a/.github/workflows/markdown.yml b/.github/workflows/markdown.yml new file mode 100644 index 0000000..266e911 --- /dev/null +++ b/.github/workflows/markdown.yml @@ -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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c2658d7 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +node_modules/ diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..be0443a --- /dev/null +++ b/.prettierignore @@ -0,0 +1,2 @@ +node_modules/ +.git/ diff --git a/.prettierrc.json b/.prettierrc.json new file mode 100644 index 0000000..4cb4f4e --- /dev/null +++ b/.prettierrc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://json.schemastore.org/prettierrc", + "proseWrap": "preserve" +} diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..958b047 --- /dev/null +++ b/LICENSE @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..3056e83 --- /dev/null +++ b/README.md @@ -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.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). diff --git a/README.zh.md b/README.zh.md new file mode 100644 index 0000000..4d54472 --- /dev/null +++ b/README.zh.md @@ -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.md + references/ # 可选 + scripts/ # 可选 +``` + +这些 skills 采用渐进式披露设计：只有当任务真正需要时，智能体才会加载对应说明；而配套的 references 和 scripts 会跟随 skill 一起保留，以便重复执行。 + +## 说明 + +- 本存储库会随着新工作流的出现持续演进。 +- `xixu-me/skvlt` 是恢复一套经过审阅的常用基线最简单的方式。 +- 如果你只想使用某个特定 source repository，直接通过 `bunx` 或 `npx` 安装会更合适。 + +## 许可证 + +基于 MIT License 发布。详见 [`LICENSE`](./LICENSE)。 diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..6f80665 --- /dev/null +++ b/package-lock.json @@ -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" + } + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..b778883 --- /dev/null +++ b/package.json @@ -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" + } +} diff --git a/skills/github-actions-docs/SKILL.md b/skills/github-actions-docs/SKILL.md new file mode 100644 index 0000000..e6ac095 --- /dev/null +++ b/skills/github-actions-docs/SKILL.md @@ -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. diff --git a/skills/github-actions-docs/references/topic-map.md b/skills/github-actions-docs/references/topic-map.md new file mode 100644 index 0000000..9e5afc7 --- /dev/null +++ b/skills/github-actions-docs/references/topic-map.md @@ -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) diff --git a/skills/openclaw-secure-linux-cloud/SKILL.md b/skills/openclaw-secure-linux-cloud/SKILL.md new file mode 100644 index 0000000..835158b --- /dev/null +++ b/skills/openclaw-secure-linux-cloud/SKILL.md @@ -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 diff --git a/skills/openclaw-secure-linux-cloud/references/REFERENCE.md b/skills/openclaw-secure-linux-cloud/references/REFERENCE.md new file mode 100644 index 0000000..46e6a5c --- /dev/null +++ b/skills/openclaw-secure-linux-cloud/references/REFERENCE.md @@ -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 + +openclaw pairing list signal +openclaw pairing approve signal +``` + +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. diff --git a/skills/opensource-guide-coach/SKILL.md b/skills/opensource-guide-coach/SKILL.md new file mode 100644 index 0000000..a02df06 --- /dev/null +++ b/skills/opensource-guide-coach/SKILL.md @@ -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. diff --git a/skills/opensource-guide-coach/references/attribution.md b/skills/opensource-guide-coach/references/attribution.md new file mode 100644 index 0000000..ca26b19 --- /dev/null +++ b/skills/opensource-guide-coach/references/attribution.md @@ -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. diff --git a/skills/opensource-guide-coach/references/guide-map.md b/skills/opensource-guide-coach/references/guide-map.md new file mode 100644 index 0000000..be0252b --- /dev/null +++ b/skills/opensource-guide-coach/references/guide-map.md @@ -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. diff --git a/skills/opensource-guide-coach/references/persona-router.md b/skills/opensource-guide-coach/references/persona-router.md new file mode 100644 index 0000000..0ed333f --- /dev/null +++ b/skills/opensource-guide-coach/references/persona-router.md @@ -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.` diff --git a/skills/running-claude-code-via-litellm-copilot/SKILL.md b/skills/running-claude-code-via-litellm-copilot/SKILL.md new file mode 100644 index 0000000..21faacb --- /dev/null +++ b/skills/running-claude-code-via-litellm-copilot/SKILL.md @@ -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/` +- `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: + litellm_params: + model: github_copilot/ + 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/` + +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/` pattern and note that Copilot-exposed model availability may change. diff --git a/skills/running-claude-code-via-litellm-copilot/references/doc-verified-notes.md b/skills/running-claude-code-via-litellm-copilot/references/doc-verified-notes.md new file mode 100644 index 0000000..82ac8c3 --- /dev/null +++ b/skills/running-claude-code-via-litellm-copilot/references/doc-verified-notes.md @@ -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/ +``` + +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/` pattern and avoid claiming that a specific Copilot model is permanently available unless it was re-verified from current docs. diff --git a/skills/secure-linux-web-hosting/SKILL.md b/skills/secure-linux-web-hosting/SKILL.md new file mode 100644 index 0000000..d2135ad --- /dev/null +++ b/skills/secure-linux-web-hosting/SKILL.md @@ -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. diff --git a/skills/secure-linux-web-hosting/references/distro-routing.md b/skills/secure-linux-web-hosting/references/distro-routing.md new file mode 100644 index 0000000..f80de73 --- /dev/null +++ b/skills/secure-linux-web-hosting/references/distro-routing.md @@ -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: +- Ubuntu Server documentation: +- Red Hat documentation: +- ArchWiki main page: +- Nginx documentation: +- Let's Encrypt challenge types: +- Certbot instructions: +- `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. diff --git a/skills/secure-linux-web-hosting/references/nginx-patterns.md b/skills/secure-linux-web-hosting/references/nginx-patterns.md new file mode 100644 index 0000000..60546f3 --- /dev/null +++ b/skills/secure-linux-web-hosting/references/nginx-patterns.md @@ -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:` +- 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. diff --git a/skills/secure-linux-web-hosting/references/security-and-tls.md b/skills/secure-linux-web-hosting/references/security-and-tls.md new file mode 100644 index 0000000..ce92910 --- /dev/null +++ b/skills/secure-linux-web-hosting/references/security-and-tls.md @@ -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. diff --git a/skills/secure-linux-web-hosting/references/workflow-map.md b/skills/secure-linux-web-hosting/references/workflow-map.md new file mode 100644 index 0000000..3ddb379 --- /dev/null +++ b/skills/secure-linux-web-hosting/references/workflow-map.md @@ -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:` 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:` +- `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. diff --git a/skills/skills-cli/SKILL.md b/skills/skills-cli/SKILL.md new file mode 100644 index 0000000..1a6baef --- /dev/null +++ b/skills/skills-cli/SKILL.md @@ -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 --skill +``` + +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 +``` + +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 --list + +# Install one skill +bunx skills add --skill skills-cli + +# Install multiple skills +bunx skills add --skill pr-review --skill commit + +# Install globally +bunx skills add --skill skills-cli -g -y + +# Install to a specific agent +bunx skills add --skill skills-cli -a codex -y + +# Install all skills to all agents +bunx skills add --all + +# Install all skills to one agent +bunx skills add --skill '*' -a codex -y + +# Copy files instead of symlinking +bunx skills add --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 ` | install one or more named skills | +| `-a, --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 ` 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: +Why it matches: +Source: +Quality check: +Install: +bunx skills add --skill [optional flags] +Learn more: https://skills.sh/// + +If you want, I can install it for . +``` + +If the user mentions a target agent or scope, include it in the command. Examples: + +```bash +bunx skills add --skill -a codex -y +bunx skills add --skill -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 ` 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 --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 +```