skill-creator

# Skill Creator Guidance for creating effective skills. ## About Skills Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools. Each skill is a directory containing a `SKILL.md` file and optional bundled resources. ### What Skills Provide 1. Specialized workflows - Multi-step procedures for specific domains 2. Tool integrations - Instructions for working with specific file formats or APIs 3. Domain expertise - Project-specific knowledge, schemas, business logic 4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks ### Skill Locations in OPC OPC uses a two-level skill system: | Level | Path | Scope | |-------|------|-------| | System | `.opc/skills/<skill-name>/` | Shared across all projects | | Project | `.opc/projects/<project_id>/skills/<skill-name>/` | Specific to one project | Project skills with the same name override system skills. When creating new skills from project experience, always use the **project** level. ### How Skills Are Created Skills enter the system through two paths: 1. **Agent-driven** (this skill): You identify a pattern, read this guide, and create the skill manually using `init_skill.py` or `file_write`. 2. **Auto-promoted**: The system automatically distills playbook skills from repeated project reflections (threshold: 2 reflections with recurring patterns). These are saved as `<employee>-<role>-<domain>-playbook` under the project skills directory. Both paths produce the same `<skill-name>/SKILL.md` format. This guide covers the agent-driven path; auto-promoted skills follow the same naming and format conventions. ## Core Principles ### Concise is Key The context window is shared. Only add context the agent doesn't already have. Prefer concise examples over verbose explanations. ### Anatomy of a Skill ``` skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter (name, description required) │ └── Markdown instructions └── Bundled Resources (optional) ├── scripts/ - Executable code ├── references/ - Documentation loaded as needed └── assets/ - Files used in output ``` ### Progressive Disclosure 1. **Metadata (name + description)** - Always in context (~100 words) 2. **SKILL.md body** - When agent reads the skill (<5k words) 3. **Bundled resources** - As needed (scripts can be executed without reading into context) ## Naming All skills — whether agent-created or auto-promoted — must follow these conventions: - Lowercase letters, digits, and hyphens only (e.g., `backend-api-playbook`) - Under 64 characters - Directory name must match the `name` field in frontmatter ## Skill Creation Process ### Step 1: Understand the skill with concrete examples Clarify use cases: what triggers this skill, what does it produce? ### Step 2: Plan reusable contents Identify what scripts, references, and assets would help. ### Step 3: Initialize the skill For project-specific skills, create under `.opc/projects/<project_id>/skills/`: ```bash python3 {baseDir}/scripts/init_skill.py <skill-name> --path .opc/projects/<project_id>/skills ``` Options: `--resources scripts,references,assets` and `--examples`. ### Step 4: Edit the skill Write SKILL.md with: - **Frontmatter**: `name` (hyphen-case, matches directory) and `description` (what it does + when to use it — this is the primary trigger for skill discovery) - **Body**: Instructions, examples, references to bundled resources ### Step 5: Package (optional) ```bash python3 {baseDir}/scripts/package_skill.py <path/to/skill-folder> ``` Validates the skill then creates a distributable `.skill` zip file. ### Step 6: Iterate Test, notice struggles, improve SKILL.md and resources.