@xingyu.wang/evoskills 1.1.0

package/.github/AI_CONSTITUTION.md

@@ -0,0 +1,66 @@
+# AI Evolution Constitution
+
+> This is the core principle guide for AI self-improvement and evolution.
+
+---
+
+## Core Principle: Continuous Evolution
+
+The AI continuously learns from experience, identifying improvement opportunities and crystallizing them into reusable practices.
+
+### What Triggers Evolution?
+
+Evolution is triggered when any of these situations occur:
+
+1. **Repeated Errors** - Same error type appears across multiple sessions
+2. **User Feedback** - User explicitly indicates behavior misalignment  
+3. **Complex Workflows** - Certain task types are consistently time-consuming/error-prone
+4. **Mechanism Failure** - A previously applied improvement/skill still fails
+
+### How Does Evolution Work?
+
+When a trigger is detected, the AI:
+
+1. **Identifies** the problem in one sentence
+2. **Analyzes** the root cause
+3. **Abstracts** it into reusable rules or processes
+4. **Crystallizes** it into one of:
+   - Constitution update (fundamental principles)
+   - Skill creation/improvement (`.agent/skills/*/SKILL.md`)
+   - Instruction update (guidance & checklists)
+5. **Registers** the new knowledge in skill registry (AGENTS.md)
+6. **Verifies** the improvement works in subsequent sessions
+
+### Why This Matters
+
+Without evolution, the AI repeats the same mistakes. With evolution, every error becomes a learning opportunity, every user feedback improves the system, every complex workflow becomes a reusable skill.
+
+---
+
+## Skill Modularity Principle
+
+**Key design decisions:**
+
+- **Skills are self-contained**: Each skill defines its own triggers, dependencies, and constraints internally
+- **Constitution doesn't maintain dependency tables**: This allows new skills to be added without modifying the constitution
+- **Dynamic extensibility**: New skills integrate automatically through internal declarations
+- **Skill autonomy**: Skills are independent and can be maintained separately
+
+When creating skill `_my-skill`, you only need to declare its tier and dependencies in the skill's metadata - no constitution modification needed.
+
+---
+
+## Glossary
+
+| Term | Definition |
+|------|-----------|
+| **Constitution** | Core evolution principles (this file) |
+| **Skill** | Reusable workflow with internal trigger conditions and dependencies |
+| **Tier** | How a skill activates: auto-enforced, conditional, or explicit-request |
+| **Trigger** | Condition that activates a skill |
+
+---
+
+> **Version**: 2.1  
+> **Focus**: Evolution mechanism only (lean and focused)  
+> **Related Files**: See `.github/EXECUTION_RULES.md` for mandatory rules, `AGENTS.md` for skill registry

package/.github/EXECUTION_RULES.md

@@ -0,0 +1,105 @@
+# Execution Rules
+
+> Optional rules that enforce safe and predictable AI behavior. Install with evoskills; can be deleted if not needed for your use case.
+
+---
+
+## Overview
+
+These 4 rules form the guardrails for reliable AI execution. They are **auto-enforced by the core system** when enabled, but can be selectively disabled or removed if your workflow doesn't require them.
+
+**Install Status**: These rules are auto-installed by `evoskills init`. To disable, remove this file's entry from `.github/copilot-instructions.md`.
+
+---
+
+## Rule 1: Instruction Guard (_instruction-guard)
+
+**Purpose**: Ensure project context is always loaded before responding.
+
+**When Active**: Before each response, if project instruction file (`.github/copilot-instructions.md`) is not in current context, read it immediately.
+
+**Why**: Prevents deviations due to missing project-specific requirements.
+
+---
+
+## Rule 2: Context Acknowledgment (_context-ack)
+
+**Purpose**: Enable users to quickly verify the AI is following correct rules.
+
+**When Active**: Each response must follow specified output format:
+- Fixed prefix at start
+- Polite address line
+- Main content
+- Reference list at end (showing which files/rules were consulted)
+
+**Why**: Makes compliance transparent and auditable.
+
+---
+
+## Rule 3: File Output Guard (_file-output-guard)
+
+**Purpose**: Prevent accidental file overwrites and unsafe operations.
+
+**When Active**:
+- **Forbidden**: Using HERE documents for file creation (`cat > file << 'EOF'`)
+- **Required**: Use `create_file` or `replace_string_in_file` tools only
+- **Large Files**: Files >5KB must be segmented to same file to avoid session limits
+
+**Why**: Ensures file operations are safe, traceable, and controllable.
+
+---
+
+## Rule 4: Session Safety (_session-safety)
+
+**Purpose**: Prevent session failure due to excessive output.
+
+**When Active**: When estimated output length exceeds 5KB:
+- Segment processing or write to file instead
+- Don't output overly long content in single response
+
+**Why**: Protects conversation session from breaking.
+
+---
+
+## How These Rules Work Together
+
+```
+Rule 1 (_instruction-guard)
+    ↓ [load context]
+Rule 2 (_context-ack)
+    ↓ [format response]
+Rule 3 (_file-output-guard)
+    ↓ [file operations safe]
+Rule 4 (_session-safety)
+    ↓ [output within limits]
+✅ Safe, predictable, auditable execution
+```
+
+---
+
+## When to Disable
+
+You can safely remove this file's reference from `.github/copilot-instructions.md` if:
+
+1. You're using the AI in personal projects with low risk tolerance
+2. Your workflow doesn't need output format enforcement
+3. You want maximum flexibility without guardrails
+
+However, we recommend keeping at least **Rule 1** (_instruction-guard) enabled for project-based work.
+
+---
+
+## Relationship to Evolution
+
+These rules are **separate from evolution**. Evolution (in AI_CONSTITUTION.md) happens automatically when triggers fire. These rules ensure safe execution during evolution and regular tasks.
+
+Think of it this way:
+- **Constitution** = "How the AI learns"
+- **Execution Rules** = "How the AI operates safely"
+- **Skills** = "What the AI does"
+
+---
+
+> **Version**: 1.0  
+> **Install Source**: evoskills (auto-installed with `evoskills init`)  
+> **Customization**: Can be extended in project-specific instruction files

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Xingyuwang & Contributors
+
+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.

package/README.md

@@ -0,0 +1,176 @@
+# evoskills
+
+> Evolution Skills CLI - A modular, evolvable AI skills framework for GitHub Copilot
+
+[![npm version](https://img.shields.io/npm/v/@xingyu.wang/evoskills.svg)](https://www.npmjs.com/package/@xingyu.wang/evoskills)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**evoskills** is a CLI tool and skill framework that enhances AI assistants (like GitHub Copilot) with modular, reusable capabilities. It provides a self-improving system through constitutional AI guidelines and pluggable skills.
+
+## ✨ Features
+
+- 🧩 **Modular Skills**: Install only the skills you need
+- 🔄 **Self-Improving**: Built-in evolution mechanism learns from mistakes
+- 🛡️ **Safe by Default**: Content protection prevents overwriting user customizations  
+- 📦 **openskills Compatible**: Works with standard openskills format
+- 🌐 **Extensible**: Create your own skill repositories
+- 🚀 **Zero Config**: Sensible defaults, auto-saves configuration
+
+## 📦 Installation
+
+### Option 1: Global Install (Recommended for regular use)
+
+```bash
+npm install -g @xingyu.wang/evoskills
+```
+
+Then use anywhere:
+
+```bash
+evoskills --help
+```
+
+### Option 2: Use with npx (No installation required)
+
+```bash
+npx @xingyu.wang/evoskills init
+```
+
+## 🚀 Quick Start
+
+Initialize evoskills in your project:
+
+```bash
+cd /path/to/your/project
+evoskills init
+```
+
+This will:
+- ✅ Create `.agent/skills/` directory (skills installed from GitHub)
+- ✅ Generate `AGENTS.md` at project root (openskills-compatible skill registry)
+- ✅ Download `.github/AI_CONSTITUTION.md` (core evolution mechanism)
+- ✅ Download `.github/EXECUTION_RULES.md` (optional safety guardrails)
+- ✅ Create `.github/copilot-instructions.md` (entry point for the system)
+- ✅ Save configuration to `.evoskills-config.json`
+
+**Three-layer architecture:**
+1. **AI Constitution** - Evolution principles (always active, cannot be disabled)
+2. **Execution Rules** - 4 optional safety guardrails (can be removed if not needed)
+3. **Skills** - Reusable capabilities (5 core required, 9 optional)
+
+## 📚 Usage
+
+### List Available Skills
+
+```bash
+evoskills list                   # Show all available skills
+evoskills list --installed       # Show installed skills only
+```
+
+### Install/Remove Skills
+
+```bash
+evoskills install _git-commit    # Install a skill
+evoskills remove _git-commit     # Remove a skill
+```
+
+### Update Skills and CLI
+
+```bash
+evoskills update                 # Update CLI (via npm) and refresh all installed skills
+evoskills update _git-commit     # Update specific skill only
+```
+
+### Use Custom Skill Repository
+
+```bash
+evoskills init --repo https://github.com/your-username/your-skills-repo
+evoskills update --repo <url>    # Switch repository and update all skills
+```
+
+The repository URL is auto-saved to `.evoskills-config.json`.
+
+## 🎯 Available Skills
+
+The default repository provides 14 skills across 5 categories:
+
+### Core Skills (Required - Auto-installed)
+- `_instruction-guard` - Ensures project instructions are always read before responses
+- `_context-ack` - Formats responses with headers and reference lists
+- `_file-output-guard` - Prevents accidental file overwrites
+- `_execution-precheck` - Validates dependencies before executing commands
+- `_evolution-core` - Identifies improvement opportunities and proposes enhancements
+
+### Git & Version Control
+- `_git-commit` - Conventional commits workflow
+- `_pr-creator` - Automate PR generation
+
+### Release Management
+- `_release-process` - Complete release workflow
+
+### Code Quality
+- `_code-health-check` - Quality checks before commit
+- `_typescript-type-safety` - TypeScript type safety guidelines
+
+### Workflow & Automation
+- `_change-summary` - Summarize work sessions
+- `_traceability-check` - Ensure decisions are documented
+- `_session-safety` - Prevent state violations
+- `_skills-manager` - Manage skills lifecycle
+
+## 🛡️ User Content Protection
+
+evoskills intelligently preserves your customizations during updates:
+
+### AGENTS.md Protection
+- Managed region marked with `<!-- EVOSKILLS_START -->` and `<!-- EVOSKILLS_END -->`
+- Content outside markers is preserved (your custom skills, notes, etc.)
+- Updates only replace content between markers
+- If no markers exist, content is appended (never overwritten)
+
+### copilot-instructions.md Protection
+- New file: Creates standard template with required references
+- Existing file: Checks for `AI_CONSTITUTION.md` and `AGENTS.md` references
+- Only appends missing references, never overwrites existing content
+
+**Example**: You can safely add your own skill groups to `AGENTS.md` - evoskills updates won't touch them.
+
+## 📂 Project Structure
+
+This repository uses the same `.agent/skills/` structure it creates for users (dogfooding):
+
+```
+.agent/skills/          # Skill source definitions (14 skills)
+evoskills               # CLI entry point (npm bin)
+.github/
+  AI_CONSTITUTION.md    # Constitutional template
+AGENTS.md               # Skill registry (openskills format)
+package.json            # npm package metadata
+```
+
+When users install skills from GitHub, evoskills downloads from the `.agent/skills/` path.
+
+## 🤝 Contributing
+
+Contributions are welcome! See our [contribution guidelines](SKILL_DEFINITION_SPECIFICATION.md) for details.
+
+Quick contribution workflow:
+
+```bash
+git checkout -b feat/your-feature
+# Make your changes in .agent/skills/
+git commit -m "feat: add new skill"
+git push -u origin feat/your-feature
+# Create PR (with GitHub CLI)
+gh pr create --fill
+```
+
+## 📄 License
+
+MIT © [xingyu.wang](https://github.com/xingyu.wang)
+
+## 🔗 Links
+
+- [npm Package](https://www.npmjs.com/package/@xingyu.wang/evoskills)
+- [GitHub Repository](https://github.com/xingyu.wang/copilot-evolution-skills)
+- [Skill Definition Specification](SKILL_DEFINITION_SPECIFICATION.md)

package/evoskills

@@ -0,0 +1,591 @@
+#!/bin/bash
+
+set -e
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+CLI_VERSION="1.1.0"
+
+# Project config file (in current directory)
+PROJECT_CONFIG_FILE=".evoskills-config.json"
+
+AGENTS_DIR=".agent"
+SKILLS_DIR="$AGENTS_DIR/skills"
+
+# Default skill repository
+DEFAULT_SKILLS_REPO="https://github.com/xingyu.wang/copilot-evolution-skills"
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+CORE_SKILLS=(
+  "_instruction-guard"
+  "_context-ack"
+  "_file-output-guard"
+  "_execution-precheck"
+  "_evolution-core"
+)
+
+OPTIONAL_SKILLS=(
+  "_git-commit"
+  "_pr-creator"
+  "_release-process"
+  "_code-health-check"
+  "_typescript-type-safety"
+  "_change-summary"
+  "_traceability-check"
+  "_session-safety"
+  "_skills-manager"
+)
+
+print_success() { echo -e "${GREEN}✅ $*${NC}"; }
+print_info() { echo -e "${BLUE}ℹ️  $*${NC}"; }
+print_warn() { echo -e "${YELLOW}⚠️  $*${NC}"; }
+print_error() { echo -e "${RED}❌ $*${NC}"; }
+
+show_help() {
+  cat << 'EOF'
+evoskills - Evolution Skills CLI
+
+Usage:
+  evoskills <command> [options]
+
+Commands:
+  init [OPTIONS]              Initialize project skills
+    --core-only               Install core required skills only
+    --skills <list>           Install selected skills (comma-separated)
+    --all                     Install all skills (default)
+    --repo <url>              Use custom skill repository (saved to .evoskills-config.json)
+
+  list [--installed]          List available or installed skills
+  install <skill>             Install a skill from configured repository
+  add <skill>                 Alias of install
+  remove <skill>              Remove a skill
+  update [OPTIONS]            Update CLI and refresh skills/constitution
+    --repo <url>              Switch to a different skill repository
+    [skill]                   Update specific skill only (omit to update all)
+  contribute <skill>          Start contribution flow for a skill
+  --version, -v               Print CLI version
+  --help, -h                  Print this help
+
+Default repository: https://github.com/xingyu.wang/copilot-evolution-skills
+
+Notes:
+  - Skills are installed to .agent/skills/
+  - Repository URL is auto-saved in .evoskills-config.json when using --repo
+  - 'update' without args refreshes CLI (via npm) and all skills from saved repo
+  - AGENTS.md is auto-generated for openskills compatibility
+EOF
+}
+
+ensure_layout() {
+  mkdir -p "$SKILLS_DIR"
+  mkdir -p ".github"
+}
+
+get_config_value() {
+  local key="$1"
+
+  # Return default if no config file exists
+  if [ ! -f "$PROJECT_CONFIG_FILE" ]; then
+    case "$key" in
+      skillsRepo) echo "$DEFAULT_SKILLS_REPO" ;;
+      *) echo "" ;;
+    esac
+    return
+  fi
+
+  # Try to read from config file
+  if command -v jq &> /dev/null; then
+    jq -r ".\"$key\" // empty" "$PROJECT_CONFIG_FILE" 2>/dev/null || echo ""
+  else
+    grep "\"$key\"" "$PROJECT_CONFIG_FILE" | sed 's/.*": "\(.*\)".*/\1/' || echo ""
+  fi
+}
+
+set_config_value() {
+  local key="$1"
+  local value="$2"
+
+  # Create empty config if it doesn't exist
+  if [ ! -f "$PROJECT_CONFIG_FILE" ]; then
+    echo "{}" > "$PROJECT_CONFIG_FILE"
+  fi
+
+  # Update config file
+  if command -v jq &> /dev/null; then
+    jq ".\"$key\" = \"$value\"" "$PROJECT_CONFIG_FILE" > "${PROJECT_CONFIG_FILE}.tmp" && mv "${PROJECT_CONFIG_FILE}.tmp" "$PROJECT_CONFIG_FILE"
+  else
+    # Fallback: simple sed replacement or append
+    if grep -q "\"$key\"" "$PROJECT_CONFIG_FILE"; then
+      sed -i '' "s/\"$key\": \"[^\"]*\"/\"$key\": \"$value\"/" "$PROJECT_CONFIG_FILE"
+    else
+      sed -i '' '$ s/}/,"'$key'": "'$value'"}/' "$PROJECT_CONFIG_FILE"
+    fi
+  fi
+
+  print_success "Config saved: $key = $value"
+}
+
+create_constitution_if_missing() {
+  if [ ! -f ".github/AI_CONSTITUTION.md" ]; then
+    local skills_repo
+    skills_repo=$(get_config_value "skillsRepo")
+
+    if curl -sf "$skills_repo/raw/main/.github/AI_CONSTITUTION.md" > ".github/AI_CONSTITUTION.md" 2>/dev/null; then
+      print_success "Downloaded .github/AI_CONSTITUTION.md"
+    else
+      cat > ".github/AI_CONSTITUTION.md" << 'EOF'
+# AI Constitution
+
+Please add your project constitution here or configure the skills repository URL.
+EOF
+      print_warn "Could not download constitution; created minimal .github/AI_CONSTITUTION.md"
+    fi
+  fi
+}
+
+create_execution_rules_if_missing() {
+  if [ ! -f ".github/EXECUTION_RULES.md" ]; then
+    local skills_repo
+    skills_repo=$(get_config_value "skillsRepo")
+
+    if curl -sf "$skills_repo/raw/main/.github/EXECUTION_RULES.md" > ".github/EXECUTION_RULES.md" 2>/dev/null; then
+      print_success "Downloaded .github/EXECUTION_RULES.md"
+    else
+      print_warn "Could not download execution rules (optional)"
+    fi
+  fi
+}
+
+create_copilot_instructions_if_missing() {
+  if [ ! -f ".github/copilot-instructions.md" ]; then
+    cat > ".github/copilot-instructions.md" << 'EOF'
+---
+applyTo: "**"
+---
+
+## Core Documents (Required)
+
+Please read and follow the AI evolution principle:
+- `.github/AI_CONSTITUTION.md` - Core evolution mechanism (always active, cannot be disabled)
+
+## Optional Execution Rules
+
+For additional safety guardrails, see:
+- `.github/EXECUTION_RULES.md` - 4 optional rules (can be disabled if not needed for your use case)
+
+## Skills Registry
+
+For available skills and how they work:
+- `AGENTS.md` - Skill registry with `_evolution-core` as the core skill
+
+---
+
+**Note**: The AI will continuously evolve by learning from errors, user feedback, and complex workflows. This is built into the core system and cannot be disabled.
+EOF
+    print_success "Created .github/copilot-instructions.md"
+  else
+    # Check if file already contains required references
+    local has_constitution=false
+    local has_execution=false
+    local has_agents=false
+    
+    if grep -q "AI_CONSTITUTION.md" ".github/copilot-instructions.md"; then
+      has_constitution=true
+    fi
+    
+    if grep -q "EXECUTION_RULES.md" ".github/copilot-instructions.md"; then
+      has_execution=true
+    fi
+    
+    if grep -q "AGENTS.md" ".github/copilot-instructions.md"; then
+      has_agents=true
+    fi
+    
+    # Append missing references
+    if [ "$has_constitution" = false ] || [ "$has_execution" = false ] || [ "$has_agents" = false ]; then
+      echo "" >> ".github/copilot-instructions.md"
+      echo "<!-- evoskills: auto-generated references -->" >> ".github/copilot-instructions.md"
+      
+      if [ "$has_constitution" = false ]; then
+        echo "- Please read and follow AI_CONSTITUTION.md (core evolution mechanism)" >> ".github/copilot-instructions.md"
+      fi
+      
+      if [ "$has_execution" = false ]; then
+        echo "- See EXECUTION_RULES.md for optional safety guardrails" >> ".github/copilot-instructions.md"
+      fi
+      
+      if [ "$has_agents" = false ]; then
+        echo "- Refer to AGENTS.md for skills registry" >> ".github/copilot-instructions.md"
+      fi
+      
+      print_success "Updated .github/copilot-instructions.md with evoskills references"
+    fi
+  fi
+}
+
+write_agents_registry() {
+  local installed_list
+  installed_list=$(find "$SKILLS_DIR" -mindepth 1 -maxdepth 1 -type d -exec basename {} \; 2>/dev/null | sort)
+
+  # Generate our skills section in a temp file
+  local temp_content=".evoskills-section.tmp"
+  cat > "$temp_content" << 'MARKER_EOF'
+<!-- EVOSKILLS_START -->
+<skills_system priority="1">
+
+## Available Skills (evoskills)
+
+<!--
+SKILLS_TABLE_START -->
+<usage>
+When users ask you to perform tasks, check if any of the
+available skills below can help complete the task more effectively. Skills provide
+specialized capabilities and domain knowledge.
+
+How to use skills:
+- Invoke: Bash("npx openskills read <skill-name>")
+- The skill content will load with detailed instructions on how to complete the task
+- Base directory provided in output for resolving bundled resources (references/, scripts/, assets/)
+
+Usage notes:
+- Only use skills listed in <available_skills> below
+- Do not invoke a skill that is already loaded in your context
+- Each skill invocation is stateless
+</usage>
+
+<available_skills>
+
+MARKER_EOF
+
+  # Add installed skills
+  if [ -n "$installed_list" ]; then
+    while IFS= read -r skill; do
+      cat >> "$temp_content" << EOF
+<skill>
+<name>$skill</name>
+<description>Skill: $skill</description>
+<location>project</location>
+</skill>
+
+EOF
+    done <<< "$installed_list"
+  fi
+
+  cat >> "$temp_content" << 'MARKER_EOF'
+
+</available_skills>
+<!--
+SKILLS_TABLE_END -->
+
+</skills_system>
+<!-- EVOSKILLS_END -->
+MARKER_EOF
+
+  # Update or create AGENTS.md
+  if [ ! -f "AGENTS.md" ]; then
+    # Create new file
+    cat > "AGENTS.md" << 'EOF'
+# AGENTS
+
+EOF
+    cat "$temp_content" >> "AGENTS.md"
+    print_success "Created AGENTS.md"
+  else
+    # Check if our markers exist
+    if grep -q "<!-- EVOSKILLS_START -->" "AGENTS.md" && grep -q "<!-- EVOSKILLS_END -->" "AGENTS.md"; then
+      # Replace content between markers using sed
+      local agents_tmp="AGENTS.md.tmp"
+      
+      # Extract content before EVOSKILLS_START
+      sed -n '1,/<!-- EVOSKILLS_START -->/p' "AGENTS.md" | sed '$d' > "$agents_tmp"
+      
+      # Add our new content
+      cat "$temp_content" >> "$agents_tmp"
+      
+      # Extract content after EVOSKILLS_END
+      sed -n '/<!-- EVOSKILLS_END -->/,$p' "AGENTS.md" | tail -n +2 >> "$agents_tmp"
+      
+      mv "$agents_tmp" "AGENTS.md"
+      print_success "Updated evoskills section in AGENTS.md"
+    else
+      # Append our section to existing file
+      echo "" >> "AGENTS.md"
+      cat "$temp_content" >> "AGENTS.md"
+      print_success "Appended evoskills section to AGENTS.md"
+    fi
+  fi
+  
+  # Cleanup
+  rm -f "$temp_content"
+}
+
+install_skill_github() {
+  local skill="$1"
+  local skills_repo
+  skills_repo=$(get_config_value "skillsRepo")
+
+  if [ -d "$SKILLS_DIR/$skill" ]; then
+    print_warn "Skill already installed: $skill"
+    return 0
+  fi
+
+  mkdir -p "$SKILLS_DIR/$skill"
+
+  # Try to download SKILL.md and references from GitHub
+  if curl -sf "$skills_repo/raw/main/.agent/skills/$skill/SKILL.md" > "$SKILLS_DIR/$skill/SKILL.md" 2>/dev/null; then
+    print_success "Installed skill: $skill"
+
+    # Try to download references/ if present
+    if curl -sf "$skills_repo/raw/main/.agent/skills/$skill/references/" &>/dev/null; then
+      print_info "Downloading skill references..."
+      mkdir -p "$SKILLS_DIR/$skill/references"
+      # Download common reference files
+      for ref_file in "*.md"; do
+        curl -sf "$skills_repo/raw/main/.agent/skills/$skill/references/$ref_file" > "$SKILLS_DIR/$skill/references/$ref_file" 2>/dev/null || true
+      done
+    fi
+
+    # Try to download scripts/ if present
+    if curl -sf "$skills_repo/raw/main/.agent/skills/$skill/scripts/" &>/dev/null; then
+      print_info "Downloading skill scripts..."
+      mkdir -p "$SKILLS_DIR/$skill/scripts"
+      for script_file in "*.sh"; do
+        curl -sf "$skills_repo/raw/main/.agent/skills/$skill/scripts/$script_file" > "$SKILLS_DIR/$skill/scripts/$script_file" 2>/dev/null || true
+      done
+    fi
+  else
+    print_error "Failed to download skill: $skill from $skills_repo"
+    rm -rf "$SKILLS_DIR/$skill"
+    return 1
+  fi
+}
+
+cmd_init() {
+  local core_only=false
+  local skills=""
+  local install_all=true
+  local custom_repo=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --core-only)
+        core_only=true
+        install_all=false
+        shift
+        ;;
+      --skills)
+        skills="$2"
+        install_all=false
+        shift 2
+        ;;
+      --all)
+        install_all=true
+        shift
+        ;;
+      --repo)
+        custom_repo="$2"
+        set_config_value "skillsRepo" "$custom_repo"
+        shift 2
+        ;;
+      *)
+        print_error "Unknown option: $1"
+        exit 1
+        ;;
+    esac
+  done
+
+  ensure_layout
+
+  cat > "$PROJECT_CONFIG_FILE" << EOF
+{
+  "version": "1.1.0",
+  "installedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "skillsDir": ".agent/skills",
+  "openskillsCompatible": true,
+  "skillsRepo": "$(get_config_value 'skillsRepo')"
+}
+EOF
+
+  create_constitution_if_missing
+  create_execution_rules_if_missing
+  create_copilot_instructions_if_missing
+
+  print_info "Installing core skills..."
+  for skill in "${CORE_SKILLS[@]}"; do
+    install_skill_github "$skill"
+  done
+
+  if [ "$core_only" = false ]; then
+    if [ -n "$skills" ]; then
+      print_info "Installing selected skills..."
+      for skill in ${skills//,/ }; do
+        install_skill_github "$skill"
+      done
+    elif [ "$install_all" = true ]; then
+      print_info "Installing all optional skills..."
+      for skill in "${OPTIONAL_SKILLS[@]}"; do
+        install_skill_github "$skill"
+      done
+    fi
+  fi
+
+  write_agents_registry
+  print_success "Initialization complete (.agent/skills + AGENTS.md + AI_CONSTITUTION.md)"
+}
+
+cmd_list() {
+  local show_installed=false
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --installed) show_installed=true ;;
+    esac
+    shift
+  done
+
+  if [ "$show_installed" = true ]; then
+    if [ -d "$SKILLS_DIR" ]; then
+      find "$SKILLS_DIR" -mindepth 1 -maxdepth 1 -type d -exec basename {} \; | sort
+    else
+      print_warn ".agent/skills not found. Run: evoskills init"
+    fi
+    return
+  fi
+
+  echo "Core skills:"
+  for skill in "${CORE_SKILLS[@]}"; do
+    echo "  - $skill"
+  done
+
+  echo "Optional skills:"
+  for skill in "${OPTIONAL_SKILLS[@]}"; do
+    echo "  - $skill"
+  done
+}
+
+cmd_install() {
+  local skill="$1"
+  [ -z "$skill" ] && { print_error "Usage: evoskills install <skill>"; exit 1; }
+
+  ensure_layout
+  install_skill_github "$skill"
+  write_agents_registry
+}
+
+cmd_remove() {
+  local skill="$1"
+  [ -z "$skill" ] && { print_error "Usage: evoskills remove <skill>"; exit 1; }
+
+  case "$skill" in
+    _instruction-guard|_context-ack|_file-output-guard|_execution-precheck|_evolution-core)
+      print_error "Cannot remove core skill: $skill"
+      exit 1
+      ;;
+  esac
+
+  if [ -d "$SKILLS_DIR/$skill" ]; then
+    rm -rf "$SKILLS_DIR/$skill"
+    print_success "Removed skill: $skill"
+    write_agents_registry
+  else
+    print_warn "Skill is not installed: $skill"
+  fi
+}
+
+cmd_update() {
+  local skill=""
+  local custom_repo=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --repo)
+        custom_repo="$2"
+        set_config_value "skillsRepo" "$custom_repo"
+        shift 2
+        ;;
+      *)
+        if [[ ! "$1" =~ ^-- ]]; then
+          skill="$1"
+        fi
+        shift
+        ;;
+    esac
+  done
+
+  # Update CLI itself if no specific skill requested
+  if [ -z "$skill" ]; then
+    if command -v npm &> /dev/null; then
+      print_info "Updating evoskills CLI..."
+      npm install -g @xingyu.wang/evoskills@latest 2>/dev/null || print_warn "CLI update failed (may need sudo or already latest)"
+    else
+      print_warn "npm not found; skipping CLI update"
+    fi
+  fi
+
+  ensure_layout
+  create_constitution_if_missing
+  create_execution_rules_if_missing
+  create_copilot_instructions_if_missing
+
+  if [ -n "$skill" ]; then
+    print_info "Refreshing skill: $skill"
+    rm -rf "$SKILLS_DIR/$skill"
+    install_skill_github "$skill"
+  else
+    print_info "Refreshing all skills from $(get_config_value 'skillsRepo')..."
+    # Refresh all installed skills
+    if [ -d "$SKILLS_DIR" ]; then
+      for installed_skill in "$SKILLS_DIR"/*; do
+        if [ -d "$installed_skill" ]; then
+          skill_name=$(basename "$installed_skill")
+          print_info "Updating $skill_name..."
+          rm -rf "$installed_skill"
+          install_skill_github "$skill_name"
+        fi
+      done
+    fi
+  fi
+
+  write_agents_registry
+  print_success "Update complete"
+}
+
+cmd_contribute() {
+  local skill="$1"
+  [ -z "$skill" ] && { print_error "Usage: evoskills contribute <skill>"; exit 1; }
+
+  if [ ! -d "$SKILLS_DIR/$skill" ]; then
+    print_error "Skill not found: $skill (expected in .agent/skills/)"
+    exit 1
+  fi
+
+  print_info "Contribution flow:"
+  print_info "1. Fork the repository"
+  print_info "2. Create a feature branch: git checkout -b feature/update-$skill"
+  print_info "3. Update skill in .agent/skills/$skill/"
+  print_info "4. Commit: git commit -m 'feat: update $skill'"
+  print_info "5. Push and open a pull request"
+}
+
+main() {
+  local command="$1"
+  shift || true
+
+  case "$command" in
+    init) cmd_init "$@" ;;
+    list) cmd_list "$@" ;;
+    install|add) cmd_install "$@" ;;
+    remove) cmd_remove "$@" ;;
+    update) cmd_update "$@" ;;
+    contribute) cmd_contribute "$@" ;;
+    --version|-v) echo "evoskills version $CLI_VERSION" ;;
+    --help|-h|help|"") show_help ;;
+    *) print_error "Unknown command: $command"; show_help; exit 1 ;;
+  esac
+}
+
+main "$@"

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@xingyu.wang/evoskills",
+  "version": "1.1.0",
+  "description": "Evolution Skills CLI for installing and managing openskills-compatible AI skills.",
+  "license": "MIT",
+  "bin": {
+    "evoskills": "./evoskills"
+  },
+  "files": [
+    "evoskills",
+    "README.md",
+    "LICENSE",
+    ".github/AI_CONSTITUTION.md",
+    ".github/EXECUTION_RULES.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xingyu.wang/copilot-evolution-skills.git"
+  }
+}