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](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.

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):

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:

1. Single responsibility — one skill = solve one problem
2. Follow conventions — use the project's naming, structure, and patterns
3. Minimal friction — trigger conditions should match natural language
4. 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:

1. Scaffold: run scripts/cli.cjs init with the --problem flag, or create the files manually using [skill.md.template](assets/skill.md.template)
2. Populate: inject the project-specific conventions from the L2 analysis into the SKILL.md sections
3. Reference files: only create references/, assets/, scripts/ if the skill needs them
4. Paths: use [path discovery](references/path-discovery.md) 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](agents/quality-validator.md) 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

Output contract

Always produce four parts:

1. Problem understanding: the problem identified
2. Solution design: the skill architecture
3. Deliverables: the files created
4. Usage guide: how to trigger and use the skill

Agents

• [Project scanner](agents/project-scanner.md): structure and pattern analysis
• [Tech-stack analyzer](agents/tech-stack-analyzer.md): language/framework detection
• [Convention detector](agents/convention-detector.md): code-style extraction
• [Quality validator](agents/quality-validator.md): post-generation validation

References

• [Path discovery](references/path-discovery.md): output-path determination (load after design is complete)
• [Advanced patterns](references/advanced-patterns.md): skill architecture patterns (workflow, domain, template, multi-variant)