| name | skill-evolution |
| description | Playbook instructing agents how to dynamically formulate, design, bootstrap, and register new workspace skills when facing skill gaps. |
Skill Evolution & Dynamic Bootstrapping Playbook
This playbook defines the standardized operational protocol for autonomous agents to dynamically extend their capabilities by creating, scaffolding, and registering new skills within the workspace when encountering domain-specific tasks that are not covered by existing playbooks.
1. When to Create a New Skill
An agent must proactively bootstrap a new skill under .agents/skills/ if ANY of the following conditions are met:
- Tooling Integration: A new test framework, linter, database migration tool, or external CLI is introduced and needs standard operational playbooks.
- Domain Specialization: A task requires domain-specific instructions (e.g., frontend styling systems, security hardening guidelines, custom script execution flows) not detailed in the 14 baseline skills.
- Task Repetition: An implementation workflow requires multi-step procedures that will be reused by future agents or in subtasks.
- Architectural Divergence: The codebase adopts new frameworks or API contracts requiring specialized validation rules.
2. Bootstrapping Protocol (Step-by-Step)
When a skill gap is identified, the agent must perform the following atomic steps:
Step 1: Design the Skill Scope & Architecture
Before creating any files, perform a Pre-Implementation Impact Analysis comparing the new skill structure with existing skills to avoid duplicate guidelines. Keep the name lowercase and kebab-cased (e.g., frontend-standards).
Step 2: Scaffold Directory & Playbook File
Create the subdirectory under .agents/skills/<skill-name>/ and create the SKILL.md file. The file MUST include standard YAML frontmatter:
---
name: <skill-name>
description: <Short, precise 1-2 sentence description of when to use this skill.>
---
Step 3: Write Detailed Playbooks & References
Write structured markdown guidelines including:
- Context & Core Principles: Core standards and reasoning rules for the domain.
- Commands Reference: Code snippets and console commands to execute the work.
- Best Practices & Gaps: Common pitfalls, safety warnings, and how to verify correctness.
- Optionally: Add helper scripts under a
scripts/ folder or examples under an examples/ folder if the playbook requires automated actions.
Step 4: Register & Synchronize the Workspace Skill
Always run the sync CLI command to index the new skill inside AGENTS.md and rebuild context manifests:
./helper.sh sync
3. Playbook Scaffolding Template
Use the following markdown template when creating SKILL.md:
---
name: skill-name-here
description: Concise description of the skill and when it matches.
---
# Skill Title Here
Background context on this skill domain and why it is active.
## 1. Core Principles
* Rule 1
* Rule 2
## 2. Operational CLI Commands
```bash
# Provide exact command lines
./helper.sh command-here
3. Implementation Checklist & Verification
