chore: initialize skills repository

Add initial repo files, docs, workflows, scripts, and random-image-placeholder skill.

Made-with: Cursor

Author: hicoldcat

.github/workflows/validate.yml

@@ -0,0 +1,24 @@
+name: Validate Skills
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          # scripts use Python 3.10+ syntax (e.g. `int | None`)
+          python-version: '3.11'
+
+      - name: Validate skills
+        run: python scripts/validate_skill.py skills

.gitignore

@@ -0,0 +1,19 @@
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+.idea/
+.vscode/
+
+# Python
+__pycache__/
+*.pyc
+
+# Node
+node_modules/
+
+# Build output
+dist/
+coverage/
+tmp/

CODE_OF_CONDUCT.md

@@ -0,0 +1,26 @@
+# Code of Conduct
+
+This project follows the Contributor Covenant.
+
+## Our Pledge
+
+We pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Being respectful and considerate
+- Gracefully accepting constructive feedback
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior include:
+
+- Harassment, discrimination, or hate speech
+- Personal attacks or trolling
+- Publishing others' private information without permission
+
+## Enforcement
+
+Project maintainers are responsible for clarifying standards and taking appropriate action in response to any behavior deemed inappropriate.
+

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Thanks for contributing!
+
+## What belongs in this repo
+
+- New skills under `skills/<skill-name>/` (must include `SKILL.md`)
+- Improvements to templates in `skills/_template/`
+- Documentation in `docs/`
+- Utilities in `scripts/` that improve scaffolding/validation/packaging
+
+## Skill requirements
+
+- `skills/<skill-name>/SKILL.md` must have YAML frontmatter with only:
+  - `name`
+  - `description`
+- `name` must match the folder name and be lowercase kebab-case
+- Keep `SKILL.md` concise and procedural
+
+## Local checks
+
+Validate all skills:
+
+```bash
+python scripts/validate_skill.py skills
+```
+
+Validate a single skill:
+
+```bash
+python scripts/validate_skill.py skills/<skill-name>
+```
+
+Package a skill:
+
+```bash
+python scripts/package_skill.py skills/<skill-name>
+```
+
+## Pull requests
+
+- Keep changes focused (one skill / one improvement per PR when possible)
+- Update docs when behavior changes
+- If you add scripts, prefer standard library only (or document dependencies clearly)
+

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -0,0 +1,62 @@
+# Agent Skills 🧰
+
+English | [中文](README.zh-CN.md)
+
+A collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities.
+
+## Available Skills ✨
+
+### random-image-placeholder
+
+Generate stable or random image placeholder URLs (and optionally download them) using [Lorem Picsum](https://picsum.photos/).
+
+**Use when:**
+
+- Building UI mockups / docs / demos that need images without hosting assets
+- You need reproducible images for tests/snapshots (use `seed`)
+- The user mentions picsum, placeholder images, grayscale, blur, seed, id
+
+**Examples:**
+
+```bash
+python skills/random-image-placeholder/scripts/picsum.py url --seed avatar-42 --width 400 --height 400 --grayscale --blur 2
+```
+
+```bash
+python skills/random-image-placeholder/scripts/picsum.py download --seed avatar-42 --width 120 --height 80 --out ./tmp/picsum_test.jpg
+```
+
+Docs:
+
+- `skills/random-image-placeholder/README.md`
+- `skills/random-image-placeholder/SKILL.md`
+
+## Installation
+
+This repo supports two common installation paths:
+
+1. **Use directly from source**: clone the repo and use the skill files/scripts under `skills/`
+2. **Use packaged `.skill` artifacts**: import a `.skill` file produced under `dist/` (or from your GitHub Releases, if you publish them)
+
+Package a skill locally:
+
+```bash
+python scripts/package_skill.py skills/random-image-placeholder
+```
+
+## Usage
+
+Skills are automatically available once installed/imported (depending on your editor/agent). If a skill includes helper scripts, run them directly when a deterministic result is needed.
+
+## Skill Structure
+
+Each skill contains:
+
+- `SKILL.md` - Instructions for the agent
+- `scripts/` - Helper scripts for automation (optional)
+- `references/` - Supporting documentation (optional)
+- `assets/` - Bundled assets (optional)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

README.zh-CN.md

@@ -0,0 +1,63 @@
+# Agent Skills 🧰
+
+[English](README.md) | 中文
+
+一个面向 AI 编程代理的 skill 合集。Skill 本质是可打包的说明与脚本，用来扩展代理能力。
+
+## 当前可用的 Skills ✨
+
+### random-image-placeholder
+
+基于 [Lorem Picsum](https://picsum.photos/) 生成随机/可复现的占位图 URL（可选下载到本地）。
+
+**适用场景：**
+
+- 做 UI mock / 文档 / demo，需要图片但不想托管静态资源
+- 测试/快照需要可复现图片（使用 `seed`）
+- 用户提到 picsum / 占位图 / grayscale / blur / seed / id
+
+**示例：**
+
+```bash
+python skills/random-image-placeholder/scripts/picsum.py url --seed avatar-42 --width 400 --height 400 --grayscale --blur 2
+```
+
+```bash
+python skills/random-image-placeholder/scripts/picsum.py download --seed avatar-42 --width 120 --height 80 --out ./tmp/picsum_test.jpg
+```
+
+相关文档：
+
+- `skills/random-image-placeholder/README.md`
+- `skills/random-image-placeholder/SKILL.md`
+
+## 安装
+
+本仓库支持两种常见使用方式：
+
+1. **直接用源码**：clone 仓库后直接使用 `skills/` 下的 skill 文件与脚本
+2. **使用打包产物 `.skill`**：导入 `dist/` 下生成的 `.skill` 文件（如果你发布了 GitHub Releases，也可以从 Release 下载）
+
+本地打包：
+
+```bash
+python scripts/package_skill.py skills/random-image-placeholder
+```
+
+## 使用
+
+安装/导入后，skill 会根据你的编辑器/代理规则自动可用。若 skill 自带脚本，建议在需要“确定性输出”时直接运行脚本获得稳定结果。
+
+## Skill 结构
+
+每个 skill 通常包含：
+
+- `SKILL.md`：给代理的使用说明
+- `scripts/`：可选的辅助脚本（更稳定、可复用）
+- `references/`：可选的参考资料
+- `assets/`：可选的资源文件
+
+## 许可
+
+MIT，见 [LICENSE](LICENSE)。
+

SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Supported Versions
+
+This repository provides scripts and documentation. Security updates are provided on a best-effort basis for the latest version of the default branch.
+
+## Reporting a Vulnerability
+
+Please do **not** open a public issue for security-sensitive reports.
+
+Instead, contact the maintainer with:
+
+- A clear description of the issue and impact
+- Reproduction steps (or a minimal PoC)
+- Any relevant logs or screenshots
+
+If you're unsure who to contact, open a draft issue with minimal detail and request a private channel.
+

docs/skill-authoring-guide.md

@@ -0,0 +1,49 @@
+# Skill Authoring Guide
+
+## Minimum files
+
+Each skill should include:
+
+- `SKILL.md`: the required Claude Code skill file
+
+## Required `SKILL.md` format
+
+Use YAML frontmatter at the top of the file:
+
+```md
+---
+name: my-skill
+description: Explain what the skill does and when to use it.
+---
+```
+
+Only use `name` and `description` in frontmatter.
+
+## Recommended body sections
+
+1. `## Triggers`
+2. `## Workflow`
+3. `## Rules`
+4. `## References`
+5. `## Examples`
+6. `## Output`
+
+## Naming guidance
+
+- Use lowercase kebab-case for folder names
+- Keep names specific to the job the skill performs
+- Prefer verbs or clear job titles, such as `release-helper` or `security-auditor`
+
+## Versioning
+
+Skills do not need a separate metadata version file in this repository format.
+
+Track revisions with git history, release tags, or packaged `.skill` artifacts.
+
+## Validation and packaging
+
+- Validate all skills: `python scripts/validate_skill.py skills`
+- Validate one skill: `python scripts/validate_skill.py skills/<skill-name>`
+- Package one skill: `python scripts/package_skill.py skills/<skill-name>`
+
+The packager validates before creating a distributable `.skill` file.

scripts/new-skill.ps1

@@ -0,0 +1,24 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Name
+)
+
+$repoRoot = Split-Path -Parent $PSScriptRoot
+$templateDir = Join-Path $repoRoot "skills\_template"
+$targetDir = Join-Path $repoRoot "skills\$Name"
+
+if (Test-Path $targetDir) {
+    Write-Error "Skill '$Name' already exists."
+    exit 1
+}
+
+Copy-Item $templateDir $targetDir -Recurse
+
+$skillPath = Join-Path $targetDir "SKILL.md"
+$content = Get-Content $skillPath -Raw
+$description = "Describe what this skill does and when to use it. Mention concrete triggers, repositories, file types, or workflows so Claude can activate it correctly."
+$content = $content.Replace("{{SKILL_NAME}}", $Name)
+$content = $content.Replace("{{SKILL_DESCRIPTION}}", $description)
+Set-Content -Path $skillPath -Value $content
+
+Write-Host "Created skill scaffold at $targetDir"