devlyn-cli 0.2.0 → 0.3.0

package/CLAUDE.md

@@ -6,6 +6,15 @@
 - Follow commit conventions in `.claude/commit-conventions.md`
 - Follow design system in `docs/design-system.md` for UI/UX work if exist
 
+## Error Handling Philosophy
+
+**No silent fallbacks.** Handle errors explicitly and show the user what happened.
+
+- **Default behavior**: When something fails, display a clear error state in the UI (error message, retry option, or actionable guidance). Do NOT silently fall back to default/placeholder data.
+- **Fallbacks are the exception, not the rule.** Only use fallbacks when it is a widely accepted best practice (e.g., fallback fonts in CSS, CDN failover, graceful image loading with placeholder). If unsure, handle the error explicitly instead.
+- **Never hide failures.** The user should always know when something went wrong. A visible error with a retry button is better UX than silently showing stale/default data.
+- **Pattern**: `try { doThing() } catch (error) { showErrorUI(error) }` — NOT `try { doThing() } catch { return fallbackValue }`
+
 ## Investigation Workflow
 
 When investigating bugs, analyzing features, or exploring code:
@@ -39,6 +48,19 @@ The full design-to-implementation pipeline:
 
 For complex features, use the Plan agent to design the approach before implementation.
 
+## Vibe Coding Workflow
+
+The recommended sequence after writing code:
+
+1. **Write code** (vibe coding)
+2. `/simplify` → Quick cleanup pass (reuse, quality, efficiency)
+3. `/devlyn.review` → Thorough solo review with security-first checklist
+4. `/devlyn.team-review` → Multi-perspective team review (for important PRs)
+5. `/devlyn.clean` → Periodic codebase-wide hygiene
+6. `/devlyn.update-docs` → Keep docs in sync
+
+Steps 4-6 are optional depending on the scope of changes. `/simplify` should always run before `/devlyn.review` to catch low-hanging fruit cheaply.
+
 ## Documentation Workflow
 
 - **Sync docs with codebase**: Use `/devlyn.update-docs` to clean up stale content, update outdated info, and generate missing docs
@@ -56,7 +78,7 @@ For complex features, use the Plan agent to design the approach before implement
 
 - **Codebase cleanup**: Use `/devlyn.clean` to detect and remove dead code, unused dependencies, complexity hotspots, and tech debt
 - **Focused cleanup**: Use `/devlyn.clean [category]` for targeted sweeps (dead code, deps, tests, complexity, hygiene)
-- **Periodic maintenance sequence**: `/devlyn.clean` → `/devlyn.update-docs` → `/devlyn.review`
+- **Periodic maintenance sequence**: `/devlyn.clean` → `/simplify` → `/devlyn.update-docs` → `/devlyn.review`
 
 ## Context Window Management
 

package/README.md

@@ -103,6 +103,7 @@ During installation, you can choose to add optional skills and third-party skill
 | Addon | Type | Description |
 |---|---|---|
 | `cloudflare-nextjs-setup` | skill | Cloudflare Workers + Next.js deployment with OpenNext |
+| `generate-skill` | skill | Create well-structured Claude Code skills following Anthropic best practices |
 | `prompt-engineering` | skill | Claude 4 prompt optimization using Anthropic best practices |
 | `pyx-scan` | skill | Check whether an AI agent skill is safe before installing |
 | `vercel-labs/agent-skills` | pack | React, Next.js, React Native best practices |

package/bin/devlyn.js

@@ -65,6 +65,7 @@ ${g}                v${PKG.version} ${COLORS.dim}· ${k}🍩 by Donut Studio${r}
 const OPTIONAL_ADDONS = [
   // Local optional skills (copied to .claude/skills/)
   { name: 'cloudflare-nextjs-setup', desc: 'Cloudflare Workers + Next.js deployment with OpenNext', type: 'local' },
+  { name: 'generate-skill', desc: 'Create well-structured Claude Code skills following Anthropic best practices', type: 'local' },
   { name: 'prompt-engineering', desc: 'Claude 4 prompt optimization using Anthropic best practices', type: 'local' },
   { name: 'pyx-scan', desc: 'Check whether an AI agent skill is safe before installing', type: 'local' },
   // External skill packs (installed via npx skills add)

package/optional-skills/generate-skill/CHECKLIST.md

@@ -0,0 +1,60 @@
+# Skill Quality Checklist
+
+Verify the generated skill against every item below before finalizing.
+
+---
+
+## Frontmatter
+
+- [ ] `name` is lowercase, hyphens and digits only, max 64 chars
+- [ ] `name` does not contain "anthropic", "claude", or "official"
+- [ ] `description` is third-person, max 1024 chars
+- [ ] `description` includes specific trigger phrases ("Use when user says...")
+- [ ] `description` first sentence states what the skill does
+- [ ] `allowed-tools` uses the minimal set needed (not all tools)
+- [ ] `argument-hint` shows expected input format if skill takes arguments
+- [ ] No XML tags in any frontmatter field values
+
+## Body Structure
+
+- [ ] Starts with a title (`#`) and one-line purpose statement
+- [ ] Lists reference files with descriptions (if multi-file)
+- [ ] Workflow uses numbered steps with `###` headings
+- [ ] Each step starts with an action verb (Parse, Read, Generate, Validate)
+- [ ] Each step has clear entry and exit criteria
+- [ ] Output format is explicitly defined
+
+## Content Quality
+
+- [ ] Instructions are explicit, not vague ("Review for X, Y, Z" not "Review the code")
+- [ ] Includes WHY context for non-obvious rules
+- [ ] Uses XML tags for complex structure (`<example>`, `<rules>`, `<output-format>`)
+- [ ] Uses "consider"/"evaluate" instead of "think"
+- [ ] Contains at least one concrete `<example>` block
+- [ ] Scope is bounded (file limits, directory limits, or explicit boundaries)
+- [ ] No conflicting instructions
+
+## Error Handling
+
+- [ ] Handles empty `$ARGUMENTS` (asks user or uses sensible detection)
+- [ ] Handles missing files (clear error message, not silent fallback)
+- [ ] Handles unexpected input (validation with actionable error)
+- [ ] No silent fallbacks to defaults (project convention)
+
+## Prompt Engineering
+
+- [ ] No over-triggering (description is specific, not generic)
+- [ ] No aggressive language ("MUST", "NEVER EVER", "ABSOLUTELY")
+- [ ] No wall of text without headings or structure
+- [ ] No unbounded scope ("analyze everything")
+- [ ] Anti-hallucination patterns applied (grounded in file content)
+- [ ] Degree of freedom matches skill type (guardrails for high, specs for low)
+
+## Completeness
+
+- [ ] All reference files mentioned in SKILL.md exist
+- [ ] Reference files have table of contents if over 100 lines
+- [ ] Reference files are one level deep (no nested references)
+- [ ] Total SKILL.md is under 500 lines (split if over)
+- [ ] Skill is self-contained (works without external dependencies)
+- [ ] Installation path is correct (`.claude/skills/<skill-name>/`)

package/optional-skills/generate-skill/PROMPT-PATTERNS.md

@@ -0,0 +1,370 @@
+# Prompt Patterns for Claude 4.6 Skills
+
+Patterns and anti-patterns for writing effective skill body content that works well with Claude 4.6 models.
+
+## Table of Contents
+
+- [Core Principles](#core-principles)
+- [Structural Patterns](#structural-patterns)
+- [Anti-Patterns](#anti-patterns)
+- [Anti-Hallucination Patterns](#anti-hallucination-patterns)
+- [Degree of Freedom Guide](#degree-of-freedom-guide)
+
+---
+
+## Core Principles
+
+### 1. Be Explicit
+
+Claude 4.6 follows instructions precisely. Vague prompts get literal interpretations.
+
+```markdown
+# Bad — vague
+Review the code and fix issues.
+
+# Good — explicit
+Review the code for:
+1. Security vulnerabilities (SQL injection, XSS, command injection)
+2. Performance anti-patterns (N+1 queries, unnecessary re-renders)
+3. Missing error handling
+
+For each issue found, output:
+- File and line number
+- Severity (critical/warning/info)
+- Description of the issue
+- Suggested fix with code snippet
+```
+
+### 2. Provide WHY Context
+
+Claude generalizes better when it understands the reasoning behind instructions.
+
+```markdown
+# Bad — no context
+Always use `const` instead of `let`.
+
+# Good — with WHY
+Use `const` by default because it signals immutability to other developers
+and prevents accidental reassignment. Only use `let` when the variable
+must be reassigned within its scope.
+```
+
+### 3. Use XML Tags for Structure
+
+XML tags create clear semantic boundaries. Use them for complex sections.
+
+```markdown
+<rules>
+- Never modify files outside the project directory
+- Always create a backup before destructive operations
+- Ask for confirmation before deleting more than 3 files
+</rules>
+
+<output-format>
+## Review Report
+- **File**: {path}
+- **Issues**: {count}
+- **Severity**: {critical|warning|info}
+</output-format>
+
+<example>
+Input: `/review src/auth.ts`
+Output: Review report with 3 issues found...
+</example>
+```
+
+### 4. Avoid "Think"
+
+When extended thinking is disabled, "think" can cause confusion. Use alternatives:
+
+| Instead of | Use |
+|---|---|
+| "Think about..." | "Consider..." |
+| "Think through..." | "Evaluate..." |
+| "Think step by step" | "Work through each step" |
+| "Let me think" | "Let me analyze" |
+
+---
+
+## Structural Patterns
+
+### Pattern 1: Workflow (Most Common)
+
+Sequential steps with clear entry/exit criteria. Best for medium-freedom skills.
+
+```markdown
+## Workflow
+
+### Step 1: Parse Input
+Extract the target from `$ARGUMENTS`.
+If empty, ask the user for the target.
+
+### Step 2: Analyze
+Read the target file(s) and identify {specific things}.
+
+### Step 3: Generate Output
+Produce {specific output format}.
+
+### Step 4: Validate
+Verify the output meets {specific criteria}.
+```
+
+**When to use**: Most skills. Provides clear structure while allowing flexibility within steps.
+
+### Pattern 2: Template (Fill-in-the-Blanks)
+
+Fixed output structure with variable content. Best for low-freedom skills.
+
+```markdown
+## Output Template
+
+Generate the following file:
+
+\```yaml
+name: {extracted-name}
+version: {detected-version}
+dependencies:
+  {for each dependency}
+  - name: {dep-name}
+    version: {dep-version}
+  {end for}
+\```
+
+Rules:
+- `name` must be lowercase with hyphens
+- `version` must follow semver (x.y.z)
+- Dependencies sorted alphabetically
+```
+
+**When to use**: Config generation, scaffolding, report generation.
+
+### Pattern 3: Decision Tree
+
+Branching logic based on input analysis. Best for skills that adapt behavior.
+
+```markdown
+## Decision Logic
+
+Analyze the input and follow the appropriate path:
+
+### Path A: Single File
+If `$ARGUMENTS` points to a single file:
+1. Read the file
+2. Analyze for {criteria}
+3. Output inline suggestions
+
+### Path B: Directory
+If `$ARGUMENTS` points to a directory:
+1. Glob for relevant files (`**/*.{ts,tsx}`)
+2. Analyze each file
+3. Output a summary report
+
+### Path C: No Input
+If `$ARGUMENTS` is empty:
+1. Detect the project type from package.json / pyproject.toml
+2. Find the most relevant files
+3. Follow Path A or Path B based on results
+```
+
+**When to use**: Skills that handle multiple input types or contexts.
+
+### Pattern 4: Conditional Workflow
+
+Workflow with conditional steps based on context. Combines workflow + decision tree.
+
+```markdown
+## Workflow
+
+### Step 1: Detect Context
+Read the project structure and determine:
+- Language (TypeScript, Python, Go, etc.)
+- Framework (Next.js, FastAPI, etc.)
+- Test runner (Jest, Pytest, etc.)
+
+### Step 2: Analyze (language-specific)
+
+**If TypeScript/JavaScript:**
+- Check for type errors with LSP
+- Scan for common JS anti-patterns
+
+**If Python:**
+- Check for type hints
+- Scan for common Python anti-patterns
+
+### Step 3: Report
+Output findings in a unified format regardless of language.
+```
+
+**When to use**: Skills that work across different project types.
+
+### Pattern 5: Examples-Driven
+
+Heavy use of examples to specify behavior. Best for high-freedom skills.
+
+```markdown
+## Behavior
+
+Generate code following these examples exactly:
+
+<example>
+Input: "a function that fetches user data"
+Output:
+\```typescript
+async function fetchUserData(userId: string): Promise<User> {
+  const response = await fetch(`/api/users/${userId}`);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch user ${userId}: ${response.statusText}`);
+  }
+  return response.json();
+}
+\```
+</example>
+
+<example>
+Input: "a React hook for local storage"
+Output:
+\```typescript
+function useLocalStorage<T>(key: string, initialValue: T) {
+  const [value, setValue] = useState<T>(() => {
+    const stored = localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initialValue;
+  });
+  // ...
+}
+\```
+</example>
+
+Key patterns shown in examples:
+- Always include error handling
+- Use TypeScript generics where appropriate
+- Async functions return typed Promises
+```
+
+**When to use**: Code generation, formatting, transformation skills.
+
+---
+
+## Anti-Patterns
+
+Common mistakes when writing Claude 4.6 skills:
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Over-triggering | Description matches too many scenarios | Add specific trigger phrases: `"Use when user says X, Y, Z"` |
+| Aggressive language | "You MUST", "NEVER EVER", "ABSOLUTELY" | Use calm, clear directives: "Always X", "Do not Y" |
+| Vague triggers | "Use when helpful" | Specific: "Use when reviewing TypeScript code for security" |
+| Wall of text | No structure, no headings | Break into steps with `###` headings |
+| Conflicting rules | "Be concise" + "Include all details" | Prioritize: "Be concise. Include details only for critical issues." |
+| No examples | Claude guesses at desired output | Add 1-2 concrete `<example>` blocks |
+| Unbounded scope | "Analyze everything" | Limit: "Analyze files in `src/` matching `*.ts`" |
+| Silent failures | No error handling instructions | Add: "When X fails, display the error and suggest next steps" |
+
+### Over-Triggering Fix
+
+```markdown
+# Bad — triggers on any code question
+description: Helps with code. Use for any coding task.
+
+# Good — specific triggers
+description: >
+  Generate unit tests for TypeScript functions using Jest.
+  Use when user says "generate tests", "add tests", "write tests for",
+  or when reviewing untested code.
+```
+
+### Scope Bounding
+
+```markdown
+# Bad — unbounded
+Analyze the entire codebase for issues.
+
+# Good — bounded
+Analyze files matching `$ARGUMENTS` (default: `src/**/*.ts`).
+Limit to 50 files maximum. If more files match, ask the user to narrow the scope.
+```
+
+---
+
+## Anti-Hallucination Patterns
+
+Prevent Claude from inventing information in skills:
+
+### 1. Ground in File Content
+
+```markdown
+# Bad
+Describe the project architecture.
+
+# Good
+Read `README.md`, `package.json`, and the `src/` directory structure.
+Describe the architecture based ONLY on what these files contain.
+Do not infer or assume features not present in the code.
+```
+
+### 2. Explicit Unknowns
+
+```markdown
+If you cannot determine {X} from the available files:
+- State "Unable to determine {X} from the codebase"
+- List what files you checked
+- Suggest what the user could provide to resolve this
+```
+
+### 3. Verify Before Acting
+
+```markdown
+Before generating code:
+1. Read the existing implementation in `$1`
+2. Identify the patterns already used (naming, error handling, imports)
+3. Generate code that matches these existing patterns
+Do not introduce new patterns or dependencies without explicit instruction.
+```
+
+---
+
+## Degree of Freedom Guide
+
+How much latitude to give Claude based on skill type:
+
+### High Freedom
+The skill makes autonomous decisions. Requires strong guardrails.
+
+```markdown
+## Guardrails
+- Do NOT modify files outside `$ARGUMENTS` path
+- Do NOT add new dependencies without asking
+- Do NOT delete existing code without replacement
+- Maximum 200 lines of generated code per invocation
+- Always show a diff preview before applying changes
+```
+
+**Examples**: code generation, refactoring, migration skills
+
+### Medium Freedom
+The skill follows a workflow but adapts to context. Requires clear decision criteria.
+
+```markdown
+## Decision Criteria
+- If the file has fewer than 50 lines: inline review
+- If the file has 50-500 lines: section-by-section review
+- If the file has more than 500 lines: focus on public API and entry points only
+```
+
+**Examples**: review, analysis, documentation skills
+
+### Low Freedom
+The skill executes a fixed procedure. Requires exact input/output specs.
+
+```markdown
+## Input
+- `$1`: PR number (required, integer)
+- `$2`: Template name (optional, default: "standard")
+
+## Output
+A markdown report with exactly these sections:
+1. Summary (1-2 sentences)
+2. Checklist (pass/fail for each template requirement)
+3. Missing Items (list of unfulfilled requirements)
+```
+
+**Examples**: validation, scanning, formatting skills

package/optional-skills/generate-skill/REFERENCE.md

@@ -0,0 +1,195 @@
+# Frontmatter Field Reference
+
+Complete catalog of YAML frontmatter fields for Claude Code skill files (`SKILL.md`).
+
+## Table of Contents
+
+- [Required Fields](#required-fields)
+- [Optional Fields](#optional-fields)
+- [String Substitutions](#string-substitutions)
+- [Tool Presets](#tool-presets)
+- [Naming Rules](#naming-rules)
+
+---
+
+## Required Fields
+
+| Field | Type | Max Length | Description |
+|---|---|---|---|
+| `name` | string | 64 chars | Unique skill identifier. Lowercase, hyphens, digits only. |
+| `description` | string | 1024 chars | What the skill does and when to trigger it. Third-person voice. |
+
+### `name` Validation
+
+- Lowercase letters, hyphens, and digits only: `[a-z0-9-]+`
+- Max 64 characters
+- Must NOT contain: `anthropic`, `claude`, `official`
+- Must NOT start or end with a hyphen
+- Must be unique within the project's skill directory
+
+### `description` Best Practices
+
+- Write in **third-person**: "Validates PR descriptions..." not "I validate..."
+- Include **trigger phrases** so Claude knows when to activate:
+  - Good: `Use when user says "check PR", "validate PR", "review description".`
+  - Bad: `A helpful skill for PRs.`
+- No XML tags in the description (they break YAML parsing)
+- First sentence = what it does. Second sentence = when to use it.
+
+---
+
+## Optional Fields
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `allowed-tools` | string (CSV) | all tools | Comma-separated list of tools the skill can use |
+| `argument-hint` | string | none | Placeholder shown to user (e.g., `"[file path]"`) |
+| `user-invocable` | boolean | `true` | Whether users can trigger via `/skill-name` |
+| `disable-model-invocation` | boolean | `false` | If `true`, Claude cannot proactively trigger the skill |
+| `context` | list | none | Files to inject into context when skill activates |
+| `agent` | object | none | Run skill as a subagent with its own context |
+| `model` | string | inherited | Override model (`opus`, `sonnet`, `haiku`) |
+| `hooks` | object | none | Shell commands to run on skill lifecycle events |
+
+### `allowed-tools` Details
+
+Specify the minimal set of tools needed. Format: comma-separated tool names.
+
+For Bash, use glob patterns to restrict commands:
+```yaml
+allowed-tools: Read, Bash(npm test *), Bash(npx *)
+```
+
+Wildcard `*` matches any arguments. Without a glob, Bash runs any command.
+
+### `context` Field
+
+Inject files into the skill's context automatically:
+
+```yaml
+context:
+  - type: file
+    path: ${CLAUDE_SKILL_DIR}/PATTERNS.md
+  - type: file
+    path: ./CLAUDE.md
+```
+
+Use `${CLAUDE_SKILL_DIR}` for paths relative to the skill directory.
+
+### `agent` Field
+
+Run the skill as an isolated subagent:
+
+```yaml
+agent:
+  type: general-purpose
+  model: sonnet
+```
+
+Agent types: `general-purpose`, `Explore`, `Plan`, `haiku`.
+
+### `hooks` Field
+
+Run shell commands on skill events:
+
+```yaml
+hooks:
+  pre-invoke: "echo 'Starting skill...'"
+  post-invoke: "echo 'Skill complete.'"
+```
+
+---
+
+## String Substitutions
+
+These placeholders are replaced at runtime:
+
+| Placeholder | Replaced With |
+|---|---|
+| `$ARGUMENTS` | Full argument string passed to the skill |
+| `$1`, `$2`, ... `$N` | Positional arguments (space-separated) |
+| `${CLAUDE_SESSION_ID}` | Current session identifier |
+| `${CLAUDE_SKILL_DIR}` | Absolute path to the skill's directory |
+
+### Usage Examples
+
+```markdown
+Parse `$ARGUMENTS` for the file path.
+If `$1` is empty, ask the user for a target file.
+Read the config from `${CLAUDE_SKILL_DIR}/config.yaml`.
+```
+
+---
+
+## Tool Presets
+
+Common tool combinations by skill type:
+
+### Read-Only (analysis, scanning, review)
+```yaml
+allowed-tools: Read, Grep, Glob
+```
+
+### Read-Only + LSP (code intelligence)
+```yaml
+allowed-tools: Read, Grep, Glob, LSP
+```
+
+### Code Modification (generation, refactoring)
+```yaml
+allowed-tools: Read, Grep, Glob, Edit, Write
+```
+
+### Full Access (build, test, deploy)
+```yaml
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash
+```
+
+### Web Access (API calls, fetching docs)
+```yaml
+allowed-tools: Read, Grep, Glob, WebFetch, WebSearch
+```
+
+### Restricted Bash (specific commands only)
+```yaml
+allowed-tools: Read, Grep, Glob, Bash(npm test *), Bash(npx prettier *)
+```
+
+### Agent-Spawning (team coordination)
+```yaml
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash, Agent
+```
+
+---
+
+## Naming Rules
+
+### Skill Name (`name` field)
+
+| Rule | Good | Bad |
+|---|---|---|
+| Lowercase + hyphens | `validate-pr` | `ValidatePR`, `validate_pr` |
+| Descriptive action | `generate-tests` | `tests`, `t` |
+| No reserved words | `code-review` | `claude-review`, `anthropic-scan` |
+| Max 64 chars | `validate-pr-description` | (anything over 64 chars) |
+
+### File Naming
+
+| File | Convention |
+|---|---|
+| Main skill file | Always `SKILL.md` |
+| Reference files | `UPPERCASE-WORDS.md` (e.g., `PATTERNS.md`, `REFERENCE.md`) |
+| Skill directory | Same as `name` field (e.g., `validate-pr/`) |
+
+### Description Formatting
+
+```yaml
+# Good — third person, trigger phrases, clear purpose
+description: >
+  Validate pull request descriptions against a project template.
+  Checks for required sections and formatting completeness.
+  Use when reviewing PRs or when user says "check PR", "validate PR".
+
+# Bad — first person, no triggers, vague
+description: "I help with PRs"
+```

package/optional-skills/generate-skill/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: generate-skill
+description: >
+  Create well-structured Claude Code skills following Anthropic best practices.
+  Generates SKILL.md files with proper frontmatter, workflow structure, and
+  prompt engineering patterns for Claude 4.6. Use when building new skills,
+  refactoring existing ones, or when user says "create a skill", "new skill",
+  "generate skill", "make a command".
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash
+argument-hint: "[skill description or name]"
+---
+
+# Generate Skill — Claude Code Skill Authoring
+
+Create production-quality Claude Code skills with correct frontmatter, structured workflows, and Claude 4.6 prompt patterns.
+
+Reference files in this skill directory:
+- `REFERENCE.md` — Complete frontmatter field catalog and validation rules
+- `PROMPT-PATTERNS.md` — Claude 4.6 prompt engineering patterns for skill bodies
+- `CHECKLIST.md` — Quality verification checklist
+
+## Workflow
+
+### Step 1: Gather Requirements
+
+Parse `$ARGUMENTS` for the skill description or name.
+
+If `$ARGUMENTS` is empty or vague, ask the user:
+
+> What skill do you want to create? Describe:
+> 1. **What problem** does it solve?
+> 2. **When** should it trigger? (user command, proactive, or both)
+> 3. **What tools** does it need? (read-only, code modification, web access, etc.)
+
+Determine the **degree of freedom**:
+- **High** — Skill makes decisions autonomously (e.g., code generation, refactoring)
+- **Medium** — Skill follows a workflow but adapts to context (e.g., review, analysis)
+- **Low** — Skill executes a fixed procedure (e.g., scan, validate, format)
+
+### Step 2: Choose Structure
+
+Estimate the total line count for the skill content:
+
+| Estimated Lines | Structure |
+|---|---|
+| Under 200 | Single `SKILL.md` file |
+| 200–500 | `SKILL.md` + reference files (e.g., `REFERENCE.md`, `PATTERNS.md`) |
+| Over 500 | Split into multiple separate skills |
+
+Rules for reference files:
+- One level deep only (no nested references)
+- Add a table of contents if a reference file exceeds 100 lines
+- Reference files use `${CLAUDE_SKILL_DIR}/FILENAME.md` for paths
+
+### Step 3: Write Frontmatter
+
+Read `${CLAUDE_SKILL_DIR}/REFERENCE.md` for the complete field catalog.
+
+Apply these rules:
+- `name`: lowercase, hyphens only, max 64 chars, no "anthropic" or "claude"
+- `description`: third-person, max 1024 chars, include trigger phrases, no XML tags
+- `allowed-tools`: minimal set needed — see tool presets in REFERENCE.md
+- `argument-hint`: brief placeholder showing expected input format
+
+### Step 4: Write Skill Body
+
+Read `${CLAUDE_SKILL_DIR}/PROMPT-PATTERNS.md` for Claude 4.6 patterns.
+
+Structure the body in this order:
+1. **Title and purpose** — One-line summary of what the skill does and why
+2. **Reference file links** — If multi-file, list reference files with descriptions
+3. **Workflow** — Numbered steps with clear entry/exit criteria per step
+4. **Output format** — What the skill produces (files, messages, reports)
+
+Writing rules:
+- Lead each step with an **action verb** (Parse, Read, Generate, Validate)
+- Use `$ARGUMENTS` and `$N` for user input substitution
+- Use XML tags (`<example>`, `<rules>`, `<output-format>`) for complex structure
+- Include concrete examples — Claude treats examples as specifications
+- Write "consider" or "evaluate" instead of "think" (for when thinking is disabled)
+
+### Step 5: Add Behavioral Rules
+
+Every skill needs explicit behavioral boundaries:
+
+**Error handling** (mandatory — project convention):
+```
+When an error occurs, display the error clearly to the user with actionable guidance.
+Do NOT silently fall back to defaults or placeholder data.
+```
+
+**Guardrails** based on degree of freedom:
+- **High freedom**: Add constraints on what the skill should NOT do. Be specific.
+- **Medium freedom**: Define decision criteria for branching logic.
+- **Low freedom**: Specify exact expected inputs/outputs and validation.
+
+**Common rules to consider**:
+- What happens when `$ARGUMENTS` is empty?
+- What happens when required files don't exist?
+- What are the skill's boundaries? (what it explicitly does NOT do)
+- Should it ask for confirmation before destructive actions?
+
+### Step 6: Write Reference Files (if needed)
+
+For multi-file skills, create reference files:
+
+- Each file covers one topic (patterns, field catalog, examples, etc.)
+- Start with a heading and brief description of the file's purpose
+- Add a table of contents if the file exceeds 100 lines
+- Use consistent formatting (tables for catalogs, code blocks for examples)
+
+### Step 7: Validate
+
+Read `${CLAUDE_SKILL_DIR}/CHECKLIST.md` and verify the generated skill against every item.
+
+Fix any issues before presenting the final output.
+
+## Output
+
+After generating the skill, present:
+
+1. **File listing** — All files created with line counts
+2. **Installation path** — `.claude/skills/<skill-name>/`
+3. **Test invocation** — Example command to test the skill
+
+Offer to:
+- Run `/devlyn.review` on the generated skill for quality assurance
+- Run `pyx-scan` if the skill will be published
+
+---
+
+## Examples
+
+<example>
+**Input**: `/generate-skill A skill that validates PR descriptions against a template`
+
+**Output structure** (single file):
+```
+.claude/skills/validate-pr/
+└── SKILL.md          (~120 lines)
+```
+
+Frontmatter:
+```yaml
+name: validate-pr
+description: >
+  Validate pull request descriptions against a project template.
+  Checks for required sections, formatting, and completeness.
+  Use when reviewing PRs or when user says "check PR", "validate PR description".
+allowed-tools: Read, Grep, Glob, Bash(gh pr view *)
+argument-hint: "[PR number or URL]"
+```
+</example>
+
+<example>
+**Input**: `/generate-skill A comprehensive code review skill with security, performance, and accessibility checks`
+
+**Output structure** (multi-file):
+```
+.claude/skills/code-review/
+├── SKILL.md           (~200 lines) Main workflow
+├── SECURITY.md        (~150 lines) Security check patterns
+├── PERFORMANCE.md     (~120 lines) Performance anti-patterns
+└── ACCESSIBILITY.md   (~100 lines) A11y checklist
+```
+
+Frontmatter:
+```yaml
+name: code-review
+description: >
+  Comprehensive code review covering security vulnerabilities, performance
+  anti-patterns, and accessibility compliance. Produces a structured report
+  with severity ratings. Use when reviewing code, PRs, or when user says
+  "review code", "security check", "audit this".
+allowed-tools: Read, Grep, Glob, LSP
+argument-hint: "[file path, directory, or PR number]"
+```
+</example>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Claude Code configuration toolkit for teams",
   "bin": {
     "devlyn": "bin/devlyn.js"
@@ -24,4 +24,4 @@
     "type": "git",
     "url": "git+https://github.com/fysoul17/devlyn-cli.git"
   }
-}
+}