Skill System Foundry

Meta-skill for building AI-agnostic skill systems with a two-layer architecture of skills and roles, templates, validation tools, and cross-platform authoring guidance based on the Agent Skills specification.

What a Skill Looks Like

A skill is a Markdown file with YAML frontmatter. Here's a minimal standalone skill:

---
name: deploy-helper
description: >
  Manages deployment workflows — runs pre-deploy checks, executes deployments
  to staging and production, and handles rollbacks. Activates when the user
  mentions deploying, releasing, or rolling back.
---

# Deploy Helper

Run deployment workflows for staging and production environments.

## Pre-Deploy Checks

Before deploying, verify:
1. All tests pass: `npm test`
2. No uncommitted changes: `git status`
3. Branch is up to date: `git pull --dry-run`

## Deploy

```bash
./scripts/deploy.sh <environment>
```

That's it — a SKILL.md file with a name, a description, and instructions. AI tools discover it, inject its metadata into the system prompt, and load its full content when triggered.

When a domain grows beyond what one file can handle, a router skill dispatches to capabilities — self-contained sub-skills loaded on demand. Adding capabilities to a router doesn't increase its discovery cost — only adding new registered skills does.

Architecture

graph TD
    subgraph "Discovery Layer"
        D["System prompt<br/>(name + description per skill)"]
    end

    subgraph "Skills Layer — WHAT"
        S1["Standalone Skill"]
        S2["Router Skill"]
        C1["Capability A"]
        C2["Capability B"]
    end

    subgraph "Roles Layer — WHO"
        R1["Role<br/>(orchestration contract)"]
    end

    D -->|triggers| S1
    D -->|triggers| S2
    S2 -->|dispatches to| C1
    S2 -->|dispatches to| C2
    S1 -.->|loads| R1
    S2 -.->|loads| R1
    R1 -->|composes| S1
    R1 -->|composes| C1
    R1 -->|composes| C2

Loading

• Skills define what to do — canonical, AI-agnostic knowledge. Standalone for focused tasks, router for complex domains. A skill can load one or more roles for interactive workflow logic.
• Roles define who orchestrates — composing multiple skills/capabilities into workflows with responsibility, authority, and constraints. Roles never reference other roles; when orchestration spans multiple roles, a coordination skill sequences them.
• Dependencies flow downward in composition — roles compose skills and capabilities; capabilities never know they are being orchestrated. The only upward references are orchestration skills that load roles by contract.

For the full architecture (orchestration paths, dependency rules, manifest), see the Architecture wiki page.

Installation

npx skills

npx skills add milanhorvatovic/skill-system-foundry

Installs the skill to Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Kiro, GitHub Copilot, Cline, OpenCode, and many more agents. See skills.sh for the full list of supported agents.

Claude Code Plugin

/plugin marketplace add milanhorvatovic/skill-system-foundry
/plugin install skill-system-foundry@skill-system-foundry

Gemini CLI

gemini skills link milanhorvatovic/skill-system-foundry

Manual

Copy the skill-system-foundry/ directory into your project's .agents/skills/ path:

cp -r skill-system-foundry /path/to/project/.agents/skills/

GitHub Releases

Download the latest versioned zip from Releases and extract into your skills directory.

Getting Started

Prerequisites: Python 3.12+ and a local checkout of this repository (the scripts run from skill-system-foundry/).

1. Create your first skill — Use the scaffolding tool to generate a new skill from a template:

   cd skill-system-foundry
   python scripts/scaffold.py skill my-skill --root /path/to/project/.agents

   Expected output:

     Created: /path/to/project/.agents/skills/my-skill/SKILL.md
   
   ✓ Skill 'my-skill' scaffolded at /path/to/project/.agents/skills/my-skill
     Next: edit /path/to/project/.agents/skills/my-skill/SKILL.md and update manifest.yaml
   

   Optional directories (references/, scripts/, assets/) are not created by default. Add them when needed with --with-references, --with-scripts, or --with-assets.

2. Validate your work — Run validation to ensure spec compliance:

   python scripts/validate_skill.py /path/to/project/.agents/skills/my-skill

   Expected output:

   Validating: /path/to/project/.agents/skills/my-skill
   Type: registered skill
   ------------------------------------------------------------
   ✓ All checks passed
   

3. Deploy to tools — Tools that scan .agents/skills/ natively (Codex, Gemini CLI, Warp, OpenCode, Windsurf) need nothing else. For other tools, create thin deployment pointers. See the Project Integration wiki page for details.

4. Bundle for distribution (optional) — Package a skill as a self-contained zip for Claude.ai upload, Gemini CLI, or offline sharing:

   python scripts/bundle.py /path/to/project/.agents/skills/my-skill \
     --system-root /path/to/project/.agents --output my-skill.zip

Repository Structure

.
├── LICENSE                      ← MIT license
├── README.md                    ← this file (repository overview)
└── skill-system-foundry/         ← the meta-skill itself
    ├── README.md                ← skill-level documentation
    ├── SKILL.md                 ← router entry point (Agent Skills specification)
    ├── references/              ← guidance loaded into context
    ├── assets/                  ← templates for scaffolding components
    └── scripts/                 ← validation, scaffolding, and bundling tools

See skill-system-foundry/README.md for the skill's capabilities, file layout, and usage instructions.

Windows Setup

Claude Code support relies on symlinks (CLAUDE.md and .claude/skills/). On Windows 11, two one-time steps are recommended (ideally before cloning) to make symlinks work reliably:

1. Enable Developer Mode in Windows so non-admin processes can create symlinks. See Microsoft's docs for current instructions.
2. Enable symlink support in git — either once globally, for a single clone, or per repository:

   # One-shot when cloning (preferred for new clones)
   git clone -c core.symlinks=true <repo-url>
   
   # Global (applies to all repositories you clone later)
   git config --global core.symlinks true
   
   # Per repository (run inside an existing cloned directory)
   git config core.symlinks true
   # Then refresh the working tree so Git re-creates symlinks
   # WARNING: this discards local changes to tracked files; stash or commit first
   git restore -- .

For repositories cloned after enabling symlink support (via -c core.symlinks=true or global config), symlinks work transparently on clone and checkout. If you cloned before enabling symlinks, either re-clone with git clone -c core.symlinks=true <repo-url> or set core.symlinks=true and re-checkout the working tree as shown above.

To confirm that symlinks were materialized correctly (and not replaced by plain files):

• Run git ls-files -s CLAUDE.md and check that the mode is 120000 (indicating a symlink).
• On Unix-like systems, run ls -l CLAUDE.md or readlink CLAUDE.md to see the link target.
• On Windows:
  • In Command Prompt (cmd.exe), run dir CLAUDE.md and ensure it is listed as a <SYMLINK> entry.
  • In PowerShell, run Get-Item CLAUDE.md | Format-List Mode,LinkType,Target and check that LinkType is SymbolicLink.

Learn More

Topic	Link
Full architecture and orchestration paths	Architecture
Token economy, conciseness, degrees of freedom	Design Principles
Tool landscape and discovery paths	Supported Tools
Recommended layout and deployment pointers	Project Integration
Key terms defined	Glossary
Guided examples	Walkthroughs

Further Reading

Official tool documentation: Claude Code · Codex · Gemini CLI · Cursor · Windsurf · Kiro

Authoring guides: Anthropic · OpenAI · Google

Standards: Agent Skills specification · AGENTS.md convention · ROLES.md convention