git-commit-scope-constitution by arisng/github-copilot-fc
npx skills add https://github.com/arisng/github-copilot-fc --skill git-commit-scope-constitution此技能用于构建和维护一个动态章程,该章程定义了在约定式提交中使用的提交范围清单和规则。该章程作为以下内容的权威来源:
仓库特定设计: 每个仓库维护其自己的范围清单和章程,存储在仓库内部。这确保了范围与该仓库的特定项目结构、领域和模块保持一致。
提交消息遵循 type(scope): subject 模式,受三层层次结构管理:
| 层级 | 管理内容 | 定义者 | 稳定性 |
|---|---|---|---|
| 1. 通用 | 标准约定式提交类型 (feat, fix, docs 等) | 行业惯例 |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 在所有仓库中固定 |
| 2. 作者偏好 | 扩展类型 (agent, copilot, devtool, codex) + 默认文件路径映射 | 技能作者(有主见的,可移植的) | 在作者的所有仓库中共享;用户可以覆盖 |
| 3. 工作区特定 | 范围、附加类型、文件路径覆盖 | 每个仓库的 .github/git-scope-constitution.md | 每个仓库唯一 |
此技能的主要工作是为特定仓库定义第 3 层范围,并将它们映射到适当的类型。
范围清单: .github/git-scope-inventory.md
extract_scopes.py 自动更新章程文档: .github/git-scope-constitution.md
关键区别:清单显示已使用的内容(历史事实),而章程定义应使用的内容(治理策略)。清单为章程更新提供输入,但章程管理未来的提交。
模板参考: skills/git-commit-scope-constitution/references/scope-constitution.md
提交范围章程管理约定式提交消息中使用的范围:
<commit_type>(<scope>): <executive_summary>
<optional_multi-line_description>
强制要求:仅限单一范围
每个提交必须恰好有一个范围。切勿使用多个范围(例如,<type>(<scope1>)(<scope2>))。如果一个变更影响多个区域,请选择最重要的一个作为主要 <scope>,并在 <subject> 部分明确提及任何次要区域(例如,<type>(primary-scope): [secondary-area] actual message)。
章程本身存储在 .github/git-scope-constitution.md 中,并遵循以下结构:
# 提交范围章程
最后更新:YYYY-MM-DD
## 目的
本章程定义了原子提交的已批准范围,确保提交历史的一致性和清晰度。
## 范围命名约定
[创建范围名称的规则]
## 按提交类型划分的已批准范围
### `commit_type`
- `scope-name`:此范围涵盖内容的简要描述
- `another-scope`:简要描述
[根据需要添加其他部分]
## 范围选择指南
[选择适当范围的指导原则]
## 修订流程
[如何提议和批准新范围]
首先从两个角度理解仓库:
分析 git 提交历史以查看已使用的范围:
# 提取所有历史范围
python skills/git-commit-scope-constitution/scripts/extract_scopes.py --format markdown --output .github/git-scope-inventory.md
# 或仅提取最近的范围(过去 3 个月)
python skills/git-commit-scope-constitution/scripts/extract_scopes.py --since "3 months ago" --format markdown
这将生成仓库 git 历史中当前使用的所有范围的清单,按提交类型组织。
注意:范围清单显示历史使用情况(已完成的),而章程定义已批准的使用情况(应完成的)。使用清单作为章程更新的输入,但始终参考章程进行治理决策。
关键: 范围应与实际项目结构保持一致,而不仅仅是历史提交。分析仓库以理解:
文件夹结构分析:
services/、components/、tools/)auth/、billing/、dashboard/).docs/、docs/、README.md)项目架构:
scripts/、tests/、config/)agents/、skills/、prompts/)关键问题:
示例分析:
Repository: github-copilot-fc
Top-level structure:
- agents/ → 自定义代理定义
- instructions/ → Copilot 指令
- prompts/ → 提示模板
- skills/ → Claude 技能
- scripts/ → 自动化脚本
- toolsets/ → 工具配置
- .docs/ → 文档
Derived scope patterns:
- Artifact-based: agent, instruction, prompt, skill, toolset
- Function-based: script (for automation)
- Domain-based: issue, changelog (from .docs/ subfolders)
结合 git 历史和仓库结构的洞察:
合并历史和结构范围:
识别模式:
检查章程是否已存在:
.github/git-scope-constitution.md评估当前范围概况:
质量检查:
模式识别:
基于分析,创建或更新章程:
对于新章程:
对于章程更新:
关键原则:
验证更新后的章程:
完整性检查:
一致性检查:
记录章程修订:
修订日志格式:
## 修订历史
### YYYY-MM-DD - 修订 #N
**变更:**
- 将范围 `new-scope` 添加到 `commit_type`
- 将 `old-scope-1` 和 `old-scope-2` 合并为 `unified-scope`
- 澄清了 `ambiguous-scope` 的定义
**理由:**
[进行这些更改的原因]
**迁移说明:**
[如何处理使用旧范围的现有提交]
保存最终确定的章程和清单:
.github/git-scope-constitution.md.github/git-scope-inventory.md推荐的提交消息:
docs(constitution): update scope inventory with Q1 2026 scopes
- Added 5 new scopes for `agent` type commits
- Consolidated instruction scopes into 3 clear categories
- Clarified boundaries between codex and copilot scopes
每周运行此工作流程以保持章程最新:
在提交之前,根据章程验证范围选择:
当不确定范围命名时:
extract_scopes.py --since "1 month ago" 查看历史使用情况scripts/extract_scopes.py分析 git 历史以提取约定式提交消息中使用的所有范围。
用法:
# 提取所有范围
python scripts/extract_scopes.py
# 按时间段过滤
python scripts/extract_scopes.py --since "1 week ago"
# 输出为 JSON
python scripts/extract_scopes.py --format json
# 保存到文件
python scripts/extract_scopes.py --output inventory.md
输出格式:
markdown:带有汇总统计信息和组织范围列表的结构化清单json:用于工具化的机器可读结构清单结构:
# 范围清单
**仓库:** [name]
**最后更新:** [date]
**来源:** Git 提交历史分析
## 摘要
- 总提交类型:N
- 总唯一范围:N
- 分析时段:[timeframe]
## 按提交类型划分的范围
### `type`
- scope-1
- scope-2
## 备注
[附加上下文]
references/scope-constitution.md
.github/git-scope-constitution.mdreferences/scope-inventory-template.md
.github/git-scope-constitution.md(在目标仓库中)
.github/git-scope-inventory.md(在目标仓库中)
extract_scopes.py 脚本自动生成类别级别原则(第 2 层扩展类型):
对于扩展类型(agent、copilot、devtool、codex),范围必须是工件类别,而不是特定实例。当扫描 git log --oneline 时,type(category) 立即传达哪种类型的事物发生了变更;主题行说明是哪一个。
| 模式 | 示例 | 判定 |
|---|---|---|
| 类别范围 | agent(skill): add table extraction to pdf | ✅ |
| 实例范围 | agent(pdf): add table extraction | ❌ |
| 类别范围 | copilot(instruction): tighten powershell linting rules | ✅ |
| 实例范围 | copilot(powershell): tighten linting rules | ❌ |
| 类别范围 | devtool(script): fix publish path resolution | ✅ |
| 实例范围 | devtool(publish): fix path resolution | ❌ |
通用粒度(所有类型):
过于宽泛:
feat(code): add feature → 代码的哪一部分?fix(app): fix bug → 哪个组件?过于狭窄:
feat(src/components/forms/UserForm.tsx): add validation → 文件特定fix(line-42-in-utils): fix typo → 过于细化恰到好处:
feat(user-form): add email validationfix(auth): correct token expiration logic推荐模式:
user-profile、api-clientskill、agent、instructionauth、billing、dashboardapi-client 而非 calling-api反模式:
userProfileuser_profileuser profilemisc、other、stuff添加范围的良好理由:
添加范围的不良理由:
创建: 通过章程修订添加新范围 活跃使用: 范围定期出现在提交中 合并: 相似范围合并为一个 弃用: 范围不再相关,标记为已弃用 退役: 已弃用的范围从章程中移除(但保留在历史中)
维护计划:
--since "1 week ago")每月:
每季度:
此技能补充了 git-atomic-commit 技能:
correct_type(approved_scope): clear message工作流程集成:
File Changed → git-atomic-commit → Commit Type Assigned
↓
git-commit-scope-constitution → Scope Selected
↓
Final Commit Message
在章程中未找到范围:
extract_scopes.py 搜索历史使用情况章程冲突:
范围命名违规:
# 步骤 1:提取历史范围
python skills/git-commit-scope-constitution/scripts/extract_scopes.py \
--output .github/git-scope-inventory.md
# 步骤 2:分析仓库结构
# 列出顶级目录
Repository: my-web-app/
src/
components/ → UI 组件
services/ → 业务逻辑服务
utils/ → 实用函数
tests/ → 测试文件
scripts/ → 构建/自动化脚本
docs/ → 文档
.github/ → GitHub 工作流程
# 步骤 3:将结构映射到范围
From structure analysis:
- components/ → scope: "components" or specific component names
- services/auth/ → scope: "auth"
- services/billing/ → scope: "billing"
- scripts/ → scope: "script" or "build"
- docs/ → scope: "docs"
From git history (.github/git-scope-inventory.md):
- feat(components): Used 15 times
- feat(auth): Used 8 times
- feat(billing): Used 12 times
- fix(api): Used 6 times
- chore(deps): Used 20 times
# 步骤 4:创建章程
# 合并基于结构的和基于历史的范围
# 在 .github/git-scope-constitution.md 中记录清晰的定义
# 提取上周的范围
python skills/git-commit-scope-constitution/scripts/extract_scopes.py \
--since "1 week ago" --format markdown
# 检查新文件夹/模块
# 发现:新文件夹 src/services/notifications/
# 对照章程审查
# 发现新范围:feat(notifications) 使用了 3 次
# 发现文件夹:services/notifications/(新模块)
# 更新章程
# 添加到适当部分:
# - `notifications`:通知服务和交付系统
Scenario: Modifying skills/git-atomic-commit/SKILL.md
Step 1: Check commit type mapping
→ File pattern: skills/* → Type: agent
Step 2: Consult constitution under Type: agent
→ Available scopes: skill, instruction
Step 3: Select appropriate scope
→ Change affects a skill → Use scope: `skill`
→ Specific skill name goes in the subject
Result: agent(skill): improve pre-commit validation checklist for git-atomic-commit
Scenario: Adding new authentication feature
Step 1: Analyze repository structure
→ services/auth/ exists (authentication module)
→ New files: services/auth/oauth.ts, services/auth/jwt.ts
Step 2: Check commit type
→ File pattern: services/* → feat (no project-specific type)
Step 3: Check constitution for feat scopes
→ .github/git-scope-constitution.md shows:
- auth: Authentication and authorization
- billing: Payment processing
- dashboard: Dashboard features
Step 4: Select scope based on structure
→ Files in services/auth/ → Use scope: auth
→ Aligns with both structure and constitution
Result: feat(auth): implement OAuth 2.0 authentication flow
## 修订历史
### 2026-02-04 - 修订 #12
**变更:**
- Deprecated `ai` extended type in favor of `agent`
- Consolidated instance-level scopes (e.g., `pdf`, `diataxis`) into
category-level scope `skill` under `agent` type
- Adopted "category-level scope" principle: scopes represent artifact
categories, not specific instances
**理由:**
`agent(skill)` immediately tells the reader an agent skill was changed.
The subject line provides the specific skill name, enabling efficient
git log scanning without opening the diff.
**迁移说明:**
Existing commits with old `ai(*)` scopes remain in history.
Use `agent(skill)` for all future skill-related commits.
每周安装
1
仓库
GitHub Stars
2
首次出现
1 天前
安全审计
安装于
zencoder1
amp1
cline1
openclaw1
opencode1
cursor1
This skill enables building and maintaining a living constitution that defines the inventory and rules for commit scopes used in conventional commits. The constitution serves as the authoritative source for:
Repository-Specific Design: Each repository maintains its own scopes inventory and constitution, stored within the repository itself. This ensures scopes align with the specific project structure, domains, and modules of that repository.
Commit messages follow the pattern type(scope): subject, governed by a three-tier hierarchy:
| Tier | What it governs | Defined by | Stability |
|---|---|---|---|
| 1. Universal | Standard Conventional Commits types (feat, fix, docs, etc.) | Industry convention | Fixed across all repos |
| 2. Author Preferences | Extended types (agent, copilot, devtool, codex) + default file-path mappings | Skill author (opinionated, portable) | Shared across author's repos; users may override |
| 3. Workspace-Specific | Scopes, additional types, file-path overrides | .github/git-scope-constitution.md per repo | Unique per repository |
This skill's primary job is to define the Tier 3 Scopes for a specific repository and map them to the appropriate Types.
Scopes Inventory: .github/git-scope-inventory.md
extract_scopes.pyConstitution Document: .github/git-scope-constitution.md
Key Distinction : The inventory shows what has been used (historical fact), while the constitution defines what should be used (governance policy). The inventory feeds into constitution updates, but the constitution governs future commits.
Template Reference: skills/git-commit-scope-constitution/references/scope-constitution.md
The commit scope constitution governs the scopes used in conventional commit messages:
<commit_type>(<scope>): <executive summary>
<optional_multi-line_description>
MANDATORY: Single Scope Only
Each commit MUST have exactly one scope. Never use multiple scopes (e.g., <type>(<scope1>)(<scope2>)). If a change affects multiple areas, choose the most significant one as the primary <scope> and explicitly mention any secondary area in the <subject> part (e.g., <type>(primary-scope): [secondary-area] actual message).
The constitution itself is stored in .github/git-scope-constitution.md and follows this structure:
# Commit Scope Constitution
Last Updated: YYYY-MM-DD
## Purpose
This constitution defines the approved scopes for atomic commits, ensuring consistency and clarity in commit history.
## Scope Naming Conventions
[Rules for creating scope names]
## Approved Scopes by Commit Type
### `commit_type`
- `scope-name`: Brief description of what this scope covers
- `another-scope`: Brief description
[Additional sections as needed]
## Scope Selection Guidelines
[Guidance for choosing appropriate scopes]
## Amendment Process
[How to propose and approve new scopes]
Start by understanding the repository from two perspectives:
Analyze git commit history to see what scopes have been used:
# Extract all historical scopes
python skills/git-commit-scope-constitution/scripts/extract_scopes.py --format markdown --output .github/git-scope-inventory.md
# Or just recent scopes (last 3 months)
python skills/git-commit-scope-constitution/scripts/extract_scopes.py --since "3 months ago" --format markdown
This generates an inventory of all scopes currently used in the repository's git history, organized by commit type.
Note : The scopes inventory shows historical usage (what has been done), while the constitution defines approved usage (what should be done). Use the inventory as input for constitution updates, but always reference the constitution for governance decisions.
CRITICAL: Scopes should align with the actual project structure, not just historical commits. Analyze the repository to understand:
Folder Structure Analysis:
services/, components/, tools/)auth/, billing/, dashboard/).docs/, docs/, README.md)Project Architecture:
scripts/, tests/, config/)agents/, skills/, prompts/)Key Questions:
Example Analysis:
Repository: github-copilot-fc
Top-level structure:
- agents/ → Custom agent definitions
- instructions/ → Copilot instructions
- prompts/ → Prompt templates
- skills/ → Claude skills
- scripts/ → Automation scripts
- toolsets/ → Tool configurations
- .docs/ → Documentation
Derived scope patterns:
- Artifact-based: agent, instruction, prompt, skill, toolset
- Function-based: script (for automation)
- Domain-based: issue, changelog (from .docs/ subfolders)
Combine insights from git history and repository structure:
Merge Historical and Structural Scopes:
Identify Patterns:
Check if a constitution already exists:
.github/git-scope-constitution.md if presentEvaluate the current scope landscape:
Quality Checks:
Pattern Recognition:
Based on analysis, create or update the constitution:
For New Constitutions:
For Constitution Updates:
Key Principles:
Validate the updated constitution:
Completeness Checks:
Consistency Checks:
Record constitutional amendments:
Amendment Log Format:
## Amendment History
### YYYY-MM-DD - Amendment #N
**Changes:**
- Added scope `new-scope` to `commit_type`
- Consolidated `old-scope-1` and `old-scope-2` into `unified-scope`
- Clarified definition of `ambiguous-scope`
**Rationale:**
[Why these changes were made]
**Migration Notes:**
[How to handle existing commits with old scopes]
Save the finalized constitution and inventory:
.github/git-scope-constitution.md.github/git-scope-inventory.mdRecommended Commit Message:
docs(constitution): update scope inventory with Q1 2026 scopes
- Added 5 new scopes for `agent` type commits
- Consolidated instruction scopes into 3 clear categories
- Clarified boundaries between codex and copilot scopes
Run this workflow weekly to keep the constitution current:
Before committing, validate scope choice against constitution:
When uncertain about scope naming:
extract_scopes.py --since "1 month ago"scripts/extract_scopes.pyAnalyzes git history to extract all scopes used in conventional commit messages.
Usage:
# Extract all scopes
python scripts/extract_scopes.py
# Filter by time period
python scripts/extract_scopes.py --since "1 week ago"
# Output as JSON
python scripts/extract_scopes.py --format json
# Save to file
python scripts/extract_scopes.py --output inventory.md
Output Formats:
markdown: Structured inventory with summary statistics and organized scope listsjson: Machine-readable structure for toolingInventory Structure:
# Scopes Inventory
**Repository:** [name]
**Last Updated:** [date]
**Source:** Git commit history analysis
## Summary
- Total Commit Types: N
- Total Unique Scopes: N
- Analysis Period: [timeframe]
## Scopes by Commit Type
### `type`
- scope-1
- scope-2
## Notes
[Additional context]
references/scope-constitution.md
.github/git-scope-constitution.md in target repositoryreferences/scope-inventory-template.md
.github/git-scope-constitution.md (in target repository)
.github/git-scope-inventory.md (in target repository)
extract_scopes.py scriptCategory-Level Principle (Tier 2 Extended Types):
For extended types (agent, copilot, devtool, codex), scopes must be artifact categories , not specific instances. When scanning git log --oneline, type(category) instantly conveys what kind of thing changed; the subject line says which one.
| Pattern | Example | Verdict |
|---|---|---|
| Category scope | agent(skill): add table extraction to pdf | ✅ |
| Instance scope | agent(pdf): add table extraction | ❌ |
| Category scope | copilot(instruction): tighten powershell linting rules | ✅ |
| Instance scope | copilot(powershell): tighten linting rules | ❌ |
| Category scope | devtool(script): fix publish path resolution |
General Granularity (All Types):
Too Broad:
feat(code): add feature → What part of the code?fix(app): fix bug → Which component?Too Narrow:
feat(src/components/forms/UserForm.tsx): add validation → File-specificfix(line-42-in-utils): fix typo → Too granularJust Right:
feat(user-form): add email validationfix(auth): correct token expiration logicRecommended Patterns:
user-profile, api-clientskill, agent, instructionauth, billing, dashboardapi-client not calling-apiAnti-Patterns:
userProfileuser_profileuser profilemisc, other, stuffGood Reasons to Add Scope:
Bad Reasons to Add Scope:
Creation: New scope added via constitutional amendment Active Use: Scope appears regularly in commits Consolidation: Similar scopes merged into one Deprecation: Scope no longer relevant, marked deprecated Retirement: Deprecated scope removed from constitution (but remains in history)
Maintenance Schedule:
--since "1 week ago")Monthly:
Quarterly:
This skill complements the git-atomic-commit skill:
correct_type(approved_scope): clear messageWorkflow Integration:
File Changed → git-atomic-commit → Commit Type Assigned
↓
git-commit-scope-constitution → Scope Selected
↓
Final Commit Message
Scope Not Found in Constitution:
extract_scopes.pyConstitution Conflicts:
Scope Naming Violations:
# Step 1: Extract historical scopes
python skills/git-commit-scope-constitution/scripts/extract_scopes.py \
--output .github/git-scope-inventory.md
# Step 2: Analyze repository structure
# List top-level directories
Repository: my-web-app/
src/
components/ → UI components
services/ → Business logic services
utils/ → Utility functions
tests/ → Test files
scripts/ → Build/automation scripts
docs/ → Documentation
.github/ → GitHub workflows
# Step 3: Map structure to scopes
From structure analysis:
- components/ → scope: "components" or specific component names
- services/auth/ → scope: "auth"
- services/billing/ → scope: "billing"
- scripts/ → scope: "script" or "build"
- docs/ → scope: "docs"
From git history (.github/git-scope-inventory.md):
- feat(components): Used 15 times
- feat(auth): Used 8 times
- feat(billing): Used 12 times
- fix(api): Used 6 times
- chore(deps): Used 20 times
# Step 4: Create constitution
# Combine structure-based and history-based scopes
# Document in .github/git-scope-constitution.md with clear definitions
# Extract last week's scopes
python skills/git-commit-scope-constitution/scripts/extract_scopes.py \
--since "1 week ago" --format markdown
# Check for new folders/modules
# Found: New folder src/services/notifications/
# Review against constitution
# Found new scope: feat(notifications) used 3 times
# Found folder: services/notifications/ (new module)
# Update constitution
# Add to appropriate section:
# - `notifications`: Notification service and delivery system
Scenario: Modifying skills/git-atomic-commit/SKILL.md
Step 1: Check commit type mapping
→ File pattern: skills/* → Type: agent
Step 2: Consult constitution under Type: agent
→ Available scopes: skill, instruction
Step 3: Select appropriate scope
→ Change affects a skill → Use scope: `skill`
→ Specific skill name goes in the subject
Result: agent(skill): improve pre-commit validation checklist for git-atomic-commit
Scenario: Adding new authentication feature
Step 1: Analyze repository structure
→ services/auth/ exists (authentication module)
→ New files: services/auth/oauth.ts, services/auth/jwt.ts
Step 2: Check commit type
→ File pattern: services/* → feat (no project-specific type)
Step 3: Check constitution for feat scopes
→ .github/git-scope-constitution.md shows:
- auth: Authentication and authorization
- billing: Payment processing
- dashboard: Dashboard features
Step 4: Select scope based on structure
→ Files in services/auth/ → Use scope: auth
→ Aligns with both structure and constitution
Result: feat(auth): implement OAuth 2.0 authentication flow
## Amendment History
### 2026-02-04 - Amendment #12
**Changes:**
- Deprecated `ai` extended type in favor of `agent`
- Consolidated instance-level scopes (e.g., `pdf`, `diataxis`) into
category-level scope `skill` under `agent` type
- Adopted "category-level scope" principle: scopes represent artifact
categories, not specific instances
**Rationale:**
`agent(skill)` immediately tells the reader an agent skill was changed.
The subject line provides the specific skill name, enabling efficient
git log scanning without opening the diff.
**Migration Notes:**
Existing commits with old `ai(*)` scopes remain in history.
Use `agent(skill)` for all future skill-related commits.
Weekly Installs
1
Repository
GitHub Stars
2
First Seen
1 day ago
Security Audits
Gen Agent Trust HubPassSocketFailSnykPass
Installed on
zencoder1
amp1
cline1
openclaw1
opencode1
cursor1
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
147,400 周安装
OpenAI API 完整文档技能 - 官方文档集成与智能问答助手
1 周安装
Next.js 官方文档中文指南 - 从入门到精通,掌握App Router、数据获取与性能优化
1 周安装
Hono 框架中文文档 | 轻量级 Web 框架,支持 Bun、Deno、Cloudflare Workers
1 周安装
Express.js 全面中文文档与 API 参考 | 涵盖安全漏洞、性能优化与迁移指南
1 周安装
Drizzle ORM 完整文档 | 无头 ORM 与类 SQL 查询指南
1 周安装
Cortex 文档大全 | 集成指南与 API 参考 | 涵盖 FireHydrant、ServiceNow、Datadog 等
1 周安装
| ✅ |
| Instance scope | devtool(publish): fix path resolution | ❌ |