learnwy Project Skill Writer
Design philosophy: Users do not know what a "skill" is or how to describe one. They only know their problem. This skill turns a problem description into a runnable skill.
Shared principle: This skill shares the 5 common writer disciplines (understand → analyze → confirm → project-relative paths → verify) with
project-agent-writer/project-skill-installer/project-rules-writer. See references/writer-discipline.md for details.
When to Use
Good fit:
- The user describes a recurring annoyance or manual task
- The user says "create a skill", "I have to do X manually every time", "I wish the AI could automatically..."
- The user provides a workflow that can be standardized
Not a fit:
- The user wants an agent (hand off to
project-agent-writer) - The user wants to install an existing skill (hand off to
project-skill-installer) - The user wants a rule rather than a skill (hand off to
project-rules-writer) - A one-off request with no reuse potential
Prerequisites
- Node.js >= 18
- The target project must have a writable directory (defaults to
.agents/skills/)
Workflow
[L1: Problem understanding]
↓
[L2: Project analysis] ← parallel subagents
↓
[L3: Skill design]
↓
[L4: User confirmation] ← wait for confirmation
↓
[L5: Generation]
↓
[L6: Quality validation]
L1: Problem understanding
Extract the problem, classify it, and infer skill metadata — do not make the user define these.
| Problem pattern | Skill type | Example |
|---|---|---|
| "I write the same code every time" | Generator | Component generator, API client |
| "I run the same checks every time" | Validator | Code checks, security scan |
| "I explain the same things every time" | Informer | Architecture docs, API docs |
| "I follow the same steps every time" | Workflow | Deployment, release process |
| "I find and fix the same issues every time" | Remediation | Bug fix, refactoring |
Only ask questions when multiple valid approaches exist and the user's preference matters. Never ask "what do you want the skill to do?" — infer it from the problem.
L2: Project analysis pipeline
Launch these agents in parallel via the Task tool (they are independent of one another):
| Agent | Purpose | Tool call |
|---|---|---|
| Project scanner | Structure, existing assets, patterns | Task(subagent_type="search", query="...") |
| Tech-stack analyzer | Languages, frameworks, build tools | Task(subagent_type="search", query="...") |
| Convention detector | Naming, imports, code style | Task(subagent_type="search", query="...") |
Merge their outputs into a unified project profile before entering the design stage.
L3: Skill design
Based on the problem + project analysis, generate a design spec:
## Skill: {name}
### Problem solved
{One sentence describing the problem this skill solves}
### Trigger conditions
- {trigger 1}
- {trigger 2}
### Architecture
- Input: {what the skill accepts}
- Output: {what the skill produces}
- Processing: {how the skill works}
### Project integration
- Output path: {project-relative path}
- Conventions: {from project analysis}
### Quality criteria
- {measurable success criteria}
### Hooks (optional)
- Scope: {global|project}
- Events: {IDE lifecycle events to mount}
- Purpose: {deterministic automation the hooks provide}
Design principles:
- Single responsibility — one skill = solve one problem
- Follow conventions — use the project's naming, structure, and patterns
- Minimal friction — trigger conditions should match natural language
- Verifiable output — clear success/failure criteria
L4: Confirmation
Before generating, show the user:
I will create a skill:
Problem: {the problem in the user's own words}
Solution: {what the skill will do}
Triggers: {when it activates}
Output: {files that will be created}
Is this correct? Anything to adjust?
Wait for the user's confirmation before generating.
L5: Generation
After the user confirms:
- Scaffold: run
scripts/cli.cjs initwith the--problemflag, or create the files manually using skill.md.template - Populate: inject the project-specific conventions from the L2 analysis into the SKILL.md sections
- Reference files: only create
references/,assets/,scripts/if the skill needs them - Paths: use path discovery to determine the output path — always use project-relative paths
Fallback: if cli.cjs init fails or the template does not fit, write SKILL.md directly following the template structure.
L6: Quality validation
Run the quality validator over the generated skill.
Minimum checks before delivery:
- The skill has meaningful trigger conditions (not just a filename)
- The output path is project-relative, not a global path
- The frontmatter contains
nameanddescription - The workflow is executable (not just abstract steps)
- Dependencies are declared
- Examples show real usage
- If the skill has an automatic mode → hooks.json exists with the correct scope (global vs project)
- Hook scripts use the shared library (
src/shared/hooks-lib.ts) rather than custom stdin parsing
Error handling
| Issue | Solution |
|---|---|
| Cannot detect the tech stack | Ask the user for the language/framework, or scan file extensions |
| Project too large (>500 top-level entries) | Use the focus_folders parameter in the project scanner |
| Found a conflicting existing skill | Show a comparison and ask the user: extend the existing one or create a new one? |
| The user's problem maps to multiple skill types | Show the top 2 candidates with trade-offs and let the user choose |
| Path discovery found no markers | Default to .agents/skills/ at the project root |
| The generated skill fails quality validation | Show the failures, auto-fix what can be fixed, and flag the rest |
Output contract
Always produce four parts:
- Problem understanding: the problem identified
- Solution design: the skill architecture
- Deliverables: the files created
- Usage guide: how to trigger and use the skill
Agents
- Project scanner: structure and pattern analysis
- Tech-stack analyzer: language/framework detection
- Convention detector: code-style extraction
- Quality validator: post-generation validation
References
- Path discovery: output-path determination (load after design is complete)
- Advanced patterns: skill architecture patterns (workflow, domain, template, multi-variant)