/create-skill
Build a reusable skill from any topic.
Provide a topic or workflow description, and /create-skill explores the codebase, gathers relevant patterns, and builds a well-structured skill interactively with you. In a Pilot-prepared repository, it writes project skills once under .agents/skills/; Pilot's shared hook regenerates .claude/skills/ after supported edits from Claude Code or Codex and again at Stop as a Code Mode backstop. If no topic is given, it evaluates the current session for extractable knowledge.
# Claude Code
claude
> /create-skill
> /create-skill "Vue 3 test migration pattern"
> /create-skill "How we set up MFE local development"
# Codex CLI
codex
> $create-skill
> $create-skill "Vue 3 test migration pattern"
> $create-skill "How we set up MFE local development"
What /create-skill Does
8 phases:
| Phase | Action |
|---|---|
| 1 | Load reference — use case categories, complexity spectrum, file structure, template, frontmatter fields, description formula, security restrictions |
| 2 | Understand the topic — explore codebase for relevant patterns, or evaluate session for extractable knowledge |
| 3 | Check existing skills — avoid duplicates, identify update and migration opportunities |
| 4 | Create or edit the project skill under .agents/skills/ or .claude/skills/; global skills remain agent-local |
| 5 | Run structure, content, cross-agent portability, triggering, and synchronization quality gates |
| 6 | Test and iterate with realistic prompts, then optimize description triggering |
| 7 | Check anti-patterns and troubleshooting guidance |
| 8 | Compare the result with a complete example |
Project skill synchronization
Run /setup-rules once before creating repository skills. It installs scripts/sync-agent-assets.mjs and establishes the root AGENTS.md / CLAUDE.md contract.
For a tracked project skill, prefer the durable .agents/skills/ source:
.agents/skills/my-project-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/
Pilot's shared hook synchronizes the skill on SessionStart, after supported edits made through either agent, and at Stop when Code Mode emitted no edit event. Claude-side edits synchronize back when the other copy still matches the trusted baseline. Normally you only run the read-only verification:
node scripts/sync-agent-assets.mjs --check
If the check finds drift after a hook outage, node scripts/sync-agent-assets.mjs --write is the recovery command. It is not a normal authoring step.
The synchronized files in .claude/skills/my-project-skill/ are byte-identical. One-sided, untracked, and gitignored skills are also discovered and copied automatically. If both copies changed independently, Pilot preserves both and requires reconciliation instead of choosing a winner.
Use Case Categories
| Category | Used For | Key Techniques |
|---|---|---|
| Document & Asset Creation | Consistent output (reports, designs, code) | Embedded style guides, templates, quality checklists |
| Workflow Automation | Multi-step processes with consistent methodology | Step-by-step gates, validation, iterative refinement |
| MCP Enhancement | Workflow guidance on top of MCP tool access | Multi-MCP coordination, domain expertise, error handling |
How big should a skill be
Skills are designed with the simplest possible structure that does the job. Simpler = more reliable and cheaper to execute.
Keep the main SKILL.md below 500 lines and 5,000 words. Put detailed procedures, templates, and reference material in one-level-deep supporting files and link them from the exact point where they are needed. This keeps activation cheap while preserving the full workflow on demand.
| Level | Style | Best For |
|---|---|---|
| Passive | Context only | Background knowledge, coding standards |
| Instructional | Rules + guidelines | Code review, style guides |
| CLI Wrapper | Calls a binary/script | Automation, integrations |
| Workflow | Multi-step with validation | Deploy pipelines, migrations |
| Generative | Asks agent to write code | Scaffolding, code generation |
Skill File Structure
your-skill-name/
├── SKILL.md # Required (case-sensitive, exactly SKILL.md)
├── scripts/ # Optional — executable code
├── references/ # Optional — detailed docs loaded as needed
└── assets/ # Optional — templates, fonts, icons
When to Use
- You want to capture a repeatable workflow
- You completed a non-obvious debugging session
- You want to standardize a multi-step process across your team
- You discovered an undocumented tool or API integration pattern
Skills are plain markdown files using the same SKILL.md format on both agents. They're loaded on-demand when relevant and shareable across your team via the Extensions page. Claude Code uses .claude/skills/ and ~/.claude/skills/; Codex uses .agents/skills/ and ~/.agents/skills/.
For project scope, Pilot keeps those directories synchronized with a trusted baseline. Tracked skills use .agents/skills/ as their durable source, while untracked and gitignored skills can be edited from either agent. Global user skills remain agent-local unless promoted through Pilot's skill library.