Skip to content

docs: align skills repository with Firstsun branding #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ClaudiaFang wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

docs: align skills repository with Firstsun branding #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0100558
docs: align skills repository branding
ClaudiaFang Aug 14, 2026
457420c
docs: align skill catalog with project governance
ClaudiaFang Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 68 additions & 60 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,75 +1,83 @@
# Yao Skill Arsenal
# Firstsun Skills

> A cross-domain, modular AI Agent skill repository managed by npx skills.
**Reusable AI agent skills for engineering workflows.**

## 🚀 Overview
Firstsun Skills is the shared skill repository used across Firstsun Dev projects. It keeps Firstsun-maintained skills and reviewed third-party skills in one place so coding agents can reuse the same engineering practices without copying prompt fragments between repositories.

This repository serves as a centralized "Skill Arsenal" for various AI Agents (Gemini CLI, Claude Code, etc.). It organizes skills into **Custom** (internal) and **External** (community) domains to ensure clear ownership and maintainability.
The repository is intentionally provider-neutral. Skills may be used from Claude Code, Gemini CLI, Codex, or other compatible agent environments when the underlying skill format is supported.

## 📂 Directory Structure
## What lives here

- `custom/`: Your original or heavily modified skills.
- `external/`: Community skills downloaded for reference and inspection.
- `setup.sh`: Global registration script (links skills to `~/.agents/skills/`).
- `export.sh`: Project-level import script (links skills to current directory).
### Firstsun-maintained skills

## 🛠 Core Commands
`custom/` contains skills created or substantially adapted for Firstsun engineering workflows.

### 1. Global Registration (For all projects)
To register ALL skills for all AI agents on your machine:
```bash
./setup.sh
```
Examples include project initialization, agent harness design, project management, Cloudflare development conventions, reliability practices, and repository automation.

### External skills

`external/` contains third-party community skills retained with their source and version information for review, reuse, and controlled updates.

External skills remain attributable to their original authors. Their presence in this repository does not imply Firstsun authorship.

### Gem instruction sets

`gem/` contains composed instruction sets for workflows that benefit from a larger bundled context instead of individual agent skills.

## Catalog

See [SKILLS_LIST.md](./SKILLS_LIST.md) for the current catalog and repository taxonomy.

## Installation

### Install a single skill

Use `npx skills add` so the project records the source in its skill lockfile rather than copying files manually.

### 2. Project Import (For a specific project)
To import skills locally into a project without polluting the global environment:
```bash
cd <your-project>
~/skills/export.sh <domain>
npx skills add firstsun-dev/skills --skill=<skill-name>
```

### 3. Manual Installation (Single Skill or Directory)
For a checked-out local repository, the existing scripts can also register or export groups of skills:

```bash
# Install a single skill
npx skills add ~/skills/custom/obsidian/obsidian-bases -g
# Register repository skills globally for supported agents
./setup.sh

# Recursive Installation (For domains with nested categories, e.g., develop)
npx skills add ~/skills/external/develop -g --full-depth
# Export a domain into the current project
./export.sh <domain>
```

## 📥 How to Add External Skills (SOP)

Follow these steps to add a community skill while keeping the code locally for review:

1. **Download to Root**: Go to the arsenal root and download the skill (do NOT use -g):
```bash
cd ~/skills
npx skills add <owner/repo@skill> -y
```
2. **Categorize & Align**: Move the downloaded folder from `.agents/skills/` to your desired `external/` domain. **MUST** align with our local taxonomy:
```bash
# Example: moving a react skill to our nested 'frontend' category
mkdir -p external/develop/frontend/
mv .agents/skills/<skill-name> external/develop/frontend/
```
3. **Clean Cache**: Remove the temporary `.agents/` folder:
```bash
rm -rf .agents/
```
4. **Register**: Run the setup script to link it to your agents:
```bash
./setup.sh
```
5. **Update List**: Sync [SKILLS_LIST.md](./SKILLS_LIST.md) with the new path and description.
6. **Commit**: Save the changes to Git:
```bash
git add . && git commit -m "feat: add <skill-name> to external arsenal"
```

## 📜 Guiding Principles

- **English First**: All `SKILL.md` files must be in English for maximum LLM compatibility.
- **Flattened by Default**: Keep skills as direct children of domain folders unless the domain has >10 skills (Conditional Nesting).
- **Taxonomy Alignment**: Always prioritize our local folder structure over external repository layouts.
- **Separation of Concerns**: Keep original work in `custom/` and community work in `external/`.
- **Version Control**: Keep `skills-lock.json` in Git to track external sources and hashes.
## Adding external skills

When adding a community skill, preserve provenance and keep the local taxonomy stable:

1. Add the upstream skill with `npx skills add` into a temporary local agent directory.
2. Review the skill before moving it into `external/`.
3. Place it in the appropriate local domain rather than mirroring an arbitrary upstream directory layout.
4. Keep the source/version information in `skills-lock.json` where applicable.
5. Update [SKILLS_LIST.md](./SKILLS_LIST.md).
6. Commit the skill and attribution changes together.

A third-party skill should not be silently rewritten into a Firstsun-maintained skill. If Firstsun substantially changes its behavior or policy, move the maintained variant into `custom/` and keep the lineage clear.

## Repository principles

- **English-first skills** — canonical `SKILL.md` instructions are written in English for agent interoperability.
- **Provider-neutral by default** — do not couple a reusable skill to one agent unless the task itself is provider-specific.
- **Precision over volume** — a small set of relevant installed skills is better than loading every available skill into every project.
- **Clear provenance** — distinguish Firstsun-maintained work from third-party community work.
- **Taxonomy alignment** — organize skills around how they are used in Firstsun engineering workflows.
- **Versioned sources** — retain lock/source information so external updates can be reviewed instead of drifting silently.

## Project initialization

[`firstsun-project-init`](./custom/basic/firstsun-project-init/SKILL.md) applies the Firstsun Dev repository baseline to new projects.

New repositories default to **Workshop** status. Initialization prepares the engineering baseline; it does not automatically grant organization-profile placement, a pinned slot, or a case study. Promotion to Supporting or Flagship status is based on evidence and deliberate curation.

## Firstsun Dev

Firstsun Skills is maintained as part of [Firstsun Dev](https://github.com/firstsun-dev), the engineering arm of Firstsun / 首陽問路.

> Build useful things. Operate them well. Share what we learn.
6 changes: 3 additions & 3 deletions SKILLS_LIST.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Firstsun Skill Arsenal - 技能清單 (Skill List)
# Firstsun Skills - 技能清單 (Skill List)

本文件列出了當前在庫存（Arsenal）中的所有 AI Agent 技能，包含中文說明與檔案連結。
本文件列出 Firstsun Skills 目前收錄的 AI Agent 技能，包含中文說明與檔案連結。

## 🛠️ 基礎工具 (Basic Tools)
| 技能名稱 | 中文說明 | 檔案連結 |
| :--- | :--- | :--- |
| **skill-manager** | 管理 `custom/` 與 `external/` 領域的維護指南，並支持匯出為 Gemini Gem 指令集。 | [SKILL.md](./custom/basic/skill-manager/SKILL.md) |
| **permission-cleanup** | 稽核並清理 Claude Code 權限規則（`.claude/settings.json` / `settings.local.json` 的 `permissions.allow`）：找出規則字串中洩漏的憑證、綁定已過期 job ID/PID/日期的一次性規則、以及已被更廣泛萬用字元涵蓋的多餘規則。 | [SKILL.md](./custom/basic/permission-cleanup/SKILL.md) |
| **firstsun-project-init** | 新專案一站式初始化流程：挑選並安裝相關技能、透過 firstsun-harness 建立代理 harness、建立 firstsun-dev org 下的 GitHub repo 並設定描述/tags、更新組織 profile README。 | [SKILL.md](./custom/basic/firstsun-project-init/SKILL.md) |
| **firstsun-project-init** | Firstsun Dev 專案初始化流程：挑選並安裝相關技能、透過 firstsun-harness 建立 agent harness、建立或對齊 GitHub repo metadata/README，並套用 `Workshop → Supporting → Flagship` governance；新專案預設為 Workshop，不因初始化自動加入 org profile、pins 或 case study。 | [SKILL.md](./custom/basic/firstsun-project-init/SKILL.md) |
| **firstsun-pm** | firstsun-dev 組織的專案管理技能：跨 repo 統一 issue 建立規範，依 repo 路由至對應 Project Board（多數 repo → #6，heaven-monorepo/heaven-www → #9（copyProjectV2 複製自 #6，欄位與六個內建 workflow 皆一致））、強制命名慣例，並協助設定 Estimate/Priority 欄位。也涵蓋 issue → PR 的出貨流程：lint/build/test 過關才 commit、PR 內容自動帶 `Closes #<issue>`（跨 repo 用 `Closes org/repo#<issue>`）讓 GitHub 自動連結並在合併時關閉 issue，並同步更新 board 狀態。 | [SKILL.md](./custom/basic/firstsun-pm/SKILL.md) |
| **skill-creator** | 創建有效技能的指南，包含工作流與工具整合. | [SKILL.md](./external/basic/skill-creator/SKILL.md) |
| **validate-skills** | 驗證技能是否符合 agentskills.io 規範與最佳實踐。 | [SKILL.md](./external/basic/validate-skills/SKILL.md) |
Expand Down