Skills

Skills: The Foundation of Your Software Factory

Skills are structured packages of instructions, scripts, and resources that teach your AI-assisted IDE how to complete specific tasks in a repeatable, consistent way. They form the foundation of your software factory by encoding domain knowledge, best practices, and team standards directly into your repository—where they evolve alongside your code.

---

Why Project-Scoped Skills Matter for Factory Engineering

In a software factory, skills must evolve with your codebase and be shared across your entire team. This means storing skills at the project level rather than globally on individual machines.

When you keep skills in your project repository, they are:

• Versioned with your code — every change is tracked in Git
• Reviewed in pull requests — the same quality gates that govern your code govern your factory
• Automatically available to every team member — no setup required after cloning
• Auditable — you can trace when a skill was introduced or changed and why

This alignment between skills and code is fundamental to factory engineering.

---

The Agent Skills Open Standard

The IDEs covered here all implement the Agent Skills open standard, originally pioneered by Anthropic and Claude Code and now adopted across every major AI IDE vendor—Claude Code, GitHub Copilot, Cursor, Windsurf, Kilo Code, Google Antigravity, and OpenAI Codex. Agent Skills has effectively become a platform-level convention rather than an IDE-specific feature, with enterprise adoption visible through projects like Elastic’s agent-skills repository. The standard is published and maintained at agentskills.io.

A skill is a directory containing:

my-skill/
├── SKILL.md          # Required: skill definition with YAML frontmatter
├── scripts/          # Optional: scripts the skill can execute
├── examples/         # Optional: examples to guide the agent
└── resources/        # Optional: templates and reference files

The SKILL.md file uses YAML frontmatter to declare the skill’s name and description. The description is critical—it is what the agent reads to determine whether to load and apply the skill. The standard also defines optional invocation controls such as user-invocable (whether a user can call the skill explicitly by name) and disable-model-invocation (prevent the model from auto-loading the skill, reserving it for explicit invocation):

---
name: api-design
description: Use when designing or reviewing REST APIs, defining endpoints, request/response schemas, or OpenAPI specifications for this project.
---

# API Design Standards

## Standards
...

## Resources
- **OpenAPI reference**: See [references/openapi-patterns.md](references/openapi-patterns.md) for request/response patterns and examples.
- **Templates**: Use [assets/endpoint-template.yaml](assets/endpoint-template.yaml) when adding new endpoints.

## Scripts
- **Validate spec**: Run `scripts/validate-openapi.sh` to check the OpenAPI file before commit.

The agent loads only the skills relevant to the current task, keeping context lean and responses accurate. This is called progressive disclosure—skills sit dormant until needed.

A skill that should only be invoked explicitly by name—never auto-loaded by the model—declares both optional properties in its frontmatter:

---
name: release-notes
description: Generate release notes from the current milestone. Run only when explicitly requested.
user-invocable: true
disable-model-invocation: true
---

---

Installing skill-creator and skill-optimizer

To support authoring and optimizing skills, install these published skills:

• skill-creator — Install with npx openskills install anthropics/skills. Use when creating or updating a skill; it provides authoring guidance, best practices, and the full skill-creation workflow.
• skill-optimizer — Install with npx openskills install factoryengineering/skills. Use to apply authoring best practices to an existing skill or to verify a skill after creation. If the target skill does not exist yet, use skill-creator first, then skill-optimizer.

---

Creating Skills Iteratively

1. Do the task once with the agent. Pick a concrete task (e.g. “Write a LINQ query to fetch this data” or “Refactor this unit test”). Work through the result. Fix gaps, adjust structure, clarify wording until the output is what you want. Do not compromise on quality.

2. Capture the process as a skill. Ask the agent to use the skill-creator skill to create a skill that captures your standards and opinions. Give it the name of the skill. Then instruct the agent to use skill-optimizer to align it with best practices and refine the content.

3. Run the skill against a task. In a new session, give the agent a new instance of the same kind of task (e.g. another user story or PR). Carefully observe whether the LLM uses the skill you created. Do not hand-hold; let the skill stand on its own. Note where the output is wrong, vague, or inconsistent with how you refined it in step 1.

4. Refine the skill. If the skill was not applied, ask: How can the description be improved? For each shortcoming, ask: Which part of the skill allowed this? Update the skill—add triggers, tighten the description, add constraints or examples, or clarify steps. Use skill-optimizer to re-check best practices, or edit the SKILL.md and skill files directly. Commit the change.

5. Repeat steps 3 and 4. Re-run the skill on the same or a different task. Keep tightening instructions until the skill produces the desired result without extra guidance. When it does, that skill is ready for the team.

6. Add more skills the same way. For each new repeatable task (e.g. writing release notes, generating test cases), do the task once, capture it with skill-creator, optimize it with skill-optimizer, then iterate by running and refining until the skill is reliable.

From here, every team member can invoke the skill by describing the task or by naming the skill in their prompt; the agent loads skills when relevant.

---

Managing Skills Across IDEs

Different IDEs look for skills in different folders. Managing multiple copies of the same skill across multiple folders is not viable for a team—it creates drift, duplication, and maintenance burden. Establish one canonical skills location in your repository and use one of the strategies below to keep every IDE in sync.

Canonical location:

.claude/skills/

This folder is the most widely recognized across the ecosystem. Use it as your source of truth.

Strategy 1 — Sync with rsync (recommended for most teams)

Keep canonical skills in .claude/skills/ and use a two-step rsync to keep every IDE folder in sync. This approach works on every OS (rsync is pre-installed on macOS and Linux, and available on Windows via Git Bash/MSYS2), avoids symlink pitfalls, and produces real files that every IDE’s file watcher can detect reliably.

The two-step pattern handles the case where a developer edits a skill in a non-canonical location (e.g., .kilocode/skills/) rather than in .claude/skills/. Step 1 gathers those changes back to canonical before step 2 mirrors canonical everywhere, so no work is lost.

#!/usr/bin/env bash
# sync-skills.sh — run from repo root

IDE_SKILLS=(.windsurf/skills .kilocode/skills .agent/skills .agents/skills)

# Ensure canonical directory exists (first-time setup)
mkdir -p .claude/skills

# Step 1: reverse-sync — gather changes from any IDE location back to canonical
for src in "${IDE_SKILLS[@]}"; do
  [ -d "$src" ] && rsync -a "$src/" .claude/skills/
done

# Step 2: forward-sync — mirror canonical to all IDE locations
for dest in "${IDE_SKILLS[@]}"; do
  mkdir -p "$dest"
  rsync -a --delete .claude/skills/ "$dest"/
done

Step 1 is additive (no --delete): new or modified files in any IDE folder are copied back to .claude/skills/ without removing anything. Step 2 uses --delete so each destination becomes an exact mirror of canonical — stale files that were removed from .claude/skills/ are cleaned up.

Automate this with a post-commit or post-merge Git hook, a file-watcher script, or a CI step so copies never drift. Commit the synced folders so every team member gets them on clone.

Strategy 2 — IDE-Native Locations Only

Store skills directly in each IDE’s folder (.windsurf/skills/, .kilocode/skills/, etc.) and skip the canonical location for IDEs that do not read .claude/skills/. This is the simplest option for teams that use only one or two IDEs, but it increases maintenance burden as the number of IDEs grows.

Strategy 3 — Symlinks (macOS/Linux only, with caveats)

Symlinks point each IDE’s expected folder to .claude/skills/. This avoids file duplication but comes with significant caveats:

• Windows: Symlinks require Developer Mode or administrator privileges. Developer Mode is often restricted in corporate environments, and core.symlinks must be enabled in Git. Symlinks created on macOS/Linux may not resolve correctly when cloned on Windows even with Developer Mode enabled.
• Cursor: Cursor’s file watcher does not properly follow directory symlinks. If you use Cursor, prefer copy-on-change or place skills directly in .cursor/skills/ (Cursor also reads .claude/skills/ directly, so a symlink is unnecessary for skills).
• IDE inconsistencies: Some IDEs watch the symlink target correctly; others watch the symlink itself or skip watching entirely. Test with your specific IDE versions.
• Cross-platform Git: Symlinks committed on macOS/Linux may appear as plain text files containing the target path when cloned on Windows, depending on the user’s Git configuration.

If your team is macOS/Linux-only and does not use Cursor, symlinks remain a viable option:

Option A — Use the factory-engineering skill: Install with npx openskills install factoryengineering/skills, then ask your agent to create symlinks. The skill sets up symlinks for commands/workflows (.claude/commands/) and, for IDEs that need them, skills (.claude/skills/ → Windsurf, Kilo Code, Antigravity, OpenAI Codex; Cursor and Copilot read .claude/skills/ directly). Use --type all (default) for both, or --type commands / --type skills. The agent can detect which IDEs you have, confirm with you, and offer to copy existing contents into the canonical folder if a target already exists. On Windows, use the skill’s PowerShell script. See the Commands page for more details and the skill’s SKILL.md (and symlinks.md) for script options.

Option B — Create symlinks manually for each IDE:

# Windsurf
ln -s ../.claude/skills .windsurf/skills

# Kilo Code
ln -s ../.claude/skills .kilocode/skills

# Antigravity (uses .agent/skills at project level)
ln -s ../.claude/skills .agent/skills

# OpenAI Codex
ln -s ../.claude/skills .agents/skills

# Cursor and GitHub Copilot read .claude/skills directly — no symlink needed

Commit the symlinks to your repository. Every team member on macOS/Linux gets the correct folder structure automatically on clone.

---

IDE-by-IDE Reference

Every major AI IDE supports the Agent Skills standard. The table below summarizes folder locations and sharing requirements. Use copy-on-change, IDE-native locations, or symlinks (see Managing Skills Across IDEs) depending on your team’s OS and IDE mix.

IDE	Project Folder	Sharing Required?	Details
Claude Code	.claude/skills/	No (canonical location)	Full setup →
GitHub Copilot	.github/skills/ + .claude/skills/	No (reads .claude/skills/ directly)	Full setup →
Cursor	.cursor/skills/ + .claude/skills/	No (reads .claude/skills/ directly)	Full setup →
Windsurf	.windsurf/skills/	✅ Yes (copy or symlink)	Full setup →
Kilo Code	.kilocode/skills/	✅ Yes (copy or symlink)	Full setup →
Google Antigravity	.agent/skills/	✅ Yes (copy or symlink)	Full setup →
OpenAI Codex	.agents/skills/	✅ Yes (copy or symlink)	Full setup →

---

Ecosystem: Agent Skills as a Platform Standard

Agent Skills is no longer an IDE-specific feature — it is a platform-level standard adopted by every major AI IDE vendor. Claude Code pioneered the format; GitHub Copilot, Cursor, Windsurf, Kilo Code, Google Antigravity, and OpenAI Codex have all implemented it natively. Enterprise organizations publish shared skill libraries (for example, Elastic’s agent-skills repository) and the specification is maintained openly at agentskills.io.

For factory engineering, this ecosystem-wide support is a defining strength. A skill authored in your repository today works across whichever IDE your teammates choose, and continues to work as the market evolves. You are investing in an open, portable standard — not a single vendor’s proprietary format.

---

Complete Setup: Step-by-Step

Here is the full setup for a team using multiple IDEs with one canonical skills location.

1. Create your canonical skills directory:

mkdir -p .claude/skills

2. Create your first skill: Use the skill-creator skill (see Installing skill-creator and skill-optimizer). Ask your agent to create a new skill in .claude/skills; it will guide you through the workflow and produce a proper SKILL.md and directory structure.

3. Share skills with each IDE your team uses: Choose the strategy that fits your team (see Managing Skills Across IDEs). For most teams, copy-on-change is the safest default — it works on every OS and avoids symlink pitfalls. If your team is macOS/Linux-only and does not use Cursor, symlinks are also viable. You can use the factory-engineering skill to automate either approach, or set up sharing manually.

4. Commit everything:

git add .claude/skills .cursor .windsurf .kilocode .agent .agents
git commit -m "Initialize software factory skills"

From this point forward, every team member has the full skills library available in their preferred IDE immediately after cloning the repository.