Agent Skills Project Configuration

Central configuration for managing project-specific AI agent skills across different tools (Claude Code, GitHub Copilot, OpenCode, pi, etc.).

Purpose

This directory contains a single source of truth (projects.toml) that maps git repositories and directory paths to required skills. When you work in a project, the appropriate skills are automatically activated based on this configuration.

Configuration File

projects.toml: Maps projects to required skills using git remote URLs or path patterns.

Example:

[project."github.com/vdemeester/home"]
name = "home"
description = "Personal NixOS infrastructure"
required_skills = ["Homelab", "Nix", "Git", "CORE"]

How It Works

For Claude Code

1. Global skills: ~/.config/claude/skills/ (always loaded)
2. Project skills: .claude/skills/ (project-specific, gitignored)
3. Tool: agent-skill-manager syncs skills from global to project based on projects.toml

When you work in a project:

• Git hooks automatically sync the required skills to .claude/skills/
• Both global and project skills are available
• Project .gitignore prevents committing skill content
• Configuration is centralized in this directory

For Future Tools

The same projects.toml can be used by other AI coding tools:

• GitHub Copilot: Could load project-specific instructions
• OpenCode: Could activate project-specific plugins
• pi: Could enable project-specific extensions

File Structure

~/.config/agent-skills/
├── projects.toml       # Central configuration (THIS FILE)
└── README.md           # This documentation

~/src/home/
├── .claude/
│   └── skills/         # Auto-synced based on projects.toml
│       ├── Homelab/    # (gitignored, copied from global)
│       └── Nix/        # (gitignored, copied from global)
└── .gitignore          # Contains: .claude/skills/

~/.config/claude/skills/  # Global skills library
├── CORE/
├── Git/
├── Homelab/
├── Nix/
└── ...

Usage

agent-skill-manager

# Detect what project you're in
agent-skill-manager detect

# Initialize skills for current project
agent-skill-manager init

# Sync skills (after config changes or git operations)
agent-skill-manager sync

# Check skill status
agent-skill-manager status

# Remove all project skills
agent-skill-manager clean

Adding a New Project

1. Edit ~/.config/agent-skills/projects.toml
2. Add a [project."pattern"] section
3. List required skills in required_skills = [...]
4. Run agent-skill-manager sync in the project

Example:

[project."github.com/myorg/myrepo"]
name = "myrepo"
description = "My awesome project"
required_skills = ["Python", "Git", "CORE"]

Git Hook Integration

Add to .git/hooks/post-checkout:

#!/bin/bash
agent-skill-manager sync 2>/dev/null || true

Or use the provided hook templates in ~/src/home/dots/.config/agent-skills/hooks/.

Pattern Matching

Projects are matched by:

1. Git remote URL (exact or wildcard): github.com/user/repo or github.com/tektoncd/*
2. Directory path (wildcard): */nixpkgs or */emacs.d

Wildcards (*) match any characters in that segment.

Benefits

• Single source of truth: One config for all projects
• Tool-agnostic: Works with Claude, Copilot, OpenCode, pi, etc.
• No committed skills: Skills are gitignored, only config is versioned
• Automatic sync: Git hooks keep skills up to date
• Context-aware: Different skills for different projects
• Centrally managed: Update once in dotfiles, applies everywhere

Related Files

• ~/src/home/dots/Makefile: Manages dotfile installation
• ~/.config/copilot-hooks/: Similar pattern for Copilot-specific hooks
• ~/.config/claude/: Claude-specific configuration
• ~/.config/opencode/: OpenCode-specific configuration