diff --git a/README.md b/README.md index 8a7f7a4..b8773d3 100644 --- a/README.md +++ b/README.md @@ -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 -~/skills/export.sh +npx skills add firstsun-dev/skills --skill= ``` -### 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 ``` -## 📥 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 -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/ 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 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. diff --git a/SKILLS_LIST.md b/SKILLS_LIST.md index 945cfc3..cba3b4b 100644 --- a/SKILLS_LIST.md +++ b/SKILLS_LIST.md @@ -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 #`（跨 repo 用 `Closes org/repo#`）讓 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) |