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 init with the --problem flag, 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 name and description
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)

lwy-project-skill-writer