anvil-dev-framework 0.1.6

package/docs/FIRST-SKILL-TUTORIAL.md

@@ -0,0 +1,408 @@
+# Creating Your First Skill
+
+> A step-by-step guide to creating domain skills for Anvil.
+
+---
+
+## When to Create a Skill vs Sub-Agent
+
+Before creating anything, understand the distinction:
+
+### Create a SKILL when:
+- Domain knowledge needs to be referenced repeatedly
+- Information is relatively static (conventions, patterns, references)
+- Multiple contexts might need this knowledge
+- You want on-demand loading (not always in context)
+
+**Examples**: Testing patterns, API design conventions, security checklists, component standards
+
+### Create a SUB-AGENT when:
+- Task requires multi-step execution
+- Work involves tool calls and decisions
+- Task is self-contained with clear completion criteria
+- You need focused, autonomous work
+
+**Examples**: Code reviewer, PR description writer, test generator, documentation updater
+
+### Decision Framework
+
+```
+Is it knowledge/reference material?
+├── Yes → SKILL
+└── No → Is it a multi-step workflow?
+    ├── Yes → SUB-AGENT
+    └── No → Probably just inline instructions
+```
+
+---
+
+## Skill Structure
+
+Every skill follows this structure:
+
+```
+.claude/skills/
+└── [skill-name]/
+    ├── SKILL.md          # Required: Overview, triggers, when to use
+    ├── conventions.md    # Optional: Patterns and standards
+    ├── references/       # Optional: Reference documentation
+    │   └── *.md
+    └── examples/         # Optional: Code examples
+        └── *.ts|*.tsx
+```
+
+### SKILL.md Format
+
+```markdown
+---
+name: [Human-readable name]
+description: [One-line description]
+triggers:
+  - [keyword1]
+  - [keyword2]
+  - [phrase that should load this skill]
+version: 1.0.0
+---
+
+# [Skill Name]
+
+## When to Use
+[Clear criteria for when Claude should load this skill]
+
+## Key Concepts
+[Core domain knowledge]
+
+## Patterns
+[Specific patterns to follow]
+
+## Anti-Patterns
+[What to avoid]
+
+## Checklist
+[Verification steps]
+```
+
+---
+
+## Tutorial: Creating a "Testing Patterns" Skill
+
+Let's create a real skill step-by-step.
+
+### Step 1: Identify the Domain
+
+Ask yourself:
+- What knowledge do I repeatedly need to reference?
+- What patterns do I want enforced consistently?
+- What would a senior developer on this project know?
+
+For this tutorial: **Testing patterns for a Next.js + Vitest + React Testing Library project.**
+
+### Step 2: Create the Directory
+
+```bash
+mkdir -p .claude/skills/testing-patterns
+```
+
+### Step 3: Create SKILL.md
+
+Create `.claude/skills/testing-patterns/SKILL.md`:
+
+```markdown
+---
+name: Testing Patterns
+description: Vitest + React Testing Library patterns for this project
+triggers:
+  - test
+  - spec
+  - vitest
+  - testing library
+  - write tests
+  - unit test
+  - integration test
+version: 1.0.0
+---
+
+# Testing Patterns
+
+## When to Use
+
+Load this skill when:
+- Writing new tests
+- Reviewing test code
+- Debugging test failures
+- Setting up test infrastructure
+
+## Test File Organization
+
+```
+src/
+├── components/
+│   └── Button/
+│       ├── Button.tsx
+│       └── Button.test.tsx    # Co-located
+└── lib/
+    └── utils/
+        ├── formatters.ts
+        └── formatters.test.ts  # Co-located
+```
+
+## Test Structure
+
+Use the Arrange-Act-Assert pattern:
+
+```typescript
+describe('ComponentName', () => {
+  describe('when [condition]', () => {
+    it('should [expected behavior]', () => {
+      // Arrange
+      const props = { ... };
+      
+      // Act
+      render(<Component {...props} />);
+      
+      // Assert
+      expect(screen.getByRole('button')).toBeInTheDocument();
+    });
+  });
+});
+```
+
+## Query Priority
+
+Follow Testing Library's query priority:
+
+1. `getByRole` — Accessible queries (preferred)
+2. `getByLabelText` — Form fields
+3. `getByPlaceholderText` — When no label
+4. `getByText` — Non-interactive elements
+5. `getByTestId` — Last resort only
+
+## Async Patterns
+
+```typescript
+// Waiting for elements
+await waitFor(() => {
+  expect(screen.getByText('Loaded')).toBeInTheDocument();
+});
+
+// Waiting for removal
+await waitForElementToBeRemoved(() => 
+  screen.queryByText('Loading...')
+);
+
+// User events (always async)
+await user.click(button);
+await user.type(input, 'text');
+```
+
+## Mocking Patterns
+
+```typescript
+// Mock modules
+vi.mock('@/lib/api', () => ({
+  fetchUser: vi.fn(),
+}));
+
+// Mock implementations
+const mockFetchUser = vi.mocked(fetchUser);
+mockFetchUser.mockResolvedValue({ id: '1', name: 'Test' });
+
+// Reset between tests
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+```
+
+## Anti-Patterns
+
+❌ **Don't test implementation details**
+```typescript
+// Bad: Testing internal state
+expect(component.state.isOpen).toBe(true);
+
+// Good: Testing user-visible behavior
+expect(screen.getByRole('dialog')).toBeVisible();
+```
+
+❌ **Don't use arbitrary waits**
+```typescript
+// Bad
+await new Promise(r => setTimeout(r, 1000));
+
+// Good
+await waitFor(() => expect(...));
+```
+
+❌ **Don't rely on test order**
+```typescript
+// Bad: Shared mutable state between tests
+let sharedData;
+
+// Good: Fresh setup per test
+beforeEach(() => {
+  sharedData = createTestData();
+});
+```
+
+## Checklist
+
+Before committing tests:
+
+- [ ] Tests are co-located with source files
+- [ ] Descriptive test names (reads like documentation)
+- [ ] Using accessible queries (getByRole preferred)
+- [ ] No arbitrary timeouts
+- [ ] Mocks cleaned up in beforeEach/afterEach
+- [ ] Edge cases covered (empty states, errors, loading)
+- [ ] No console warnings in test output
+```
+
+### Step 4: Add Examples (Optional)
+
+Create `.claude/skills/testing-patterns/examples/component.test.tsx`:
+
+```typescript
+/**
+ * Example: Complete component test
+ * Demonstrates patterns from SKILL.md
+ */
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { UserProfile } from './UserProfile';
+import { fetchUser } from '@/lib/api';
+
+// Mock the API module
+vi.mock('@/lib/api', () => ({
+  fetchUser: vi.fn(),
+}));
+
+describe('UserProfile', () => {
+  const user = userEvent.setup();
+  const mockFetchUser = vi.mocked(fetchUser);
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('when loading', () => {
+    it('should show loading spinner', () => {
+      mockFetchUser.mockReturnValue(new Promise(() => {})); // Never resolves
+      
+      render(<UserProfile userId="1" />);
+      
+      expect(screen.getByRole('status')).toHaveTextContent('Loading');
+    });
+  });
+
+  describe('when loaded successfully', () => {
+    it('should display user name', async () => {
+      mockFetchUser.mockResolvedValue({ id: '1', name: 'Jane Doe' });
+      
+      render(<UserProfile userId="1" />);
+      
+      await waitFor(() => {
+        expect(screen.getByRole('heading')).toHaveTextContent('Jane Doe');
+      });
+    });
+  });
+
+  describe('when user clicks edit', () => {
+    it('should open edit modal', async () => {
+      mockFetchUser.mockResolvedValue({ id: '1', name: 'Jane Doe' });
+      
+      render(<UserProfile userId="1" />);
+      
+      await waitFor(() => {
+        expect(screen.getByRole('heading')).toBeInTheDocument();
+      });
+      
+      await user.click(screen.getByRole('button', { name: /edit/i }));
+      
+      expect(screen.getByRole('dialog')).toBeVisible();
+    });
+  });
+
+  describe('when API fails', () => {
+    it('should show error message', async () => {
+      mockFetchUser.mockRejectedValue(new Error('Network error'));
+      
+      render(<UserProfile userId="1" />);
+      
+      await waitFor(() => {
+        expect(screen.getByRole('alert')).toHaveTextContent('Failed to load');
+      });
+    });
+  });
+});
+```
+
+### Step 5: Test the Skill
+
+Start a Claude session and ask:
+
+> "Help me write tests for the checkout flow"
+
+Claude should:
+1. Load the testing-patterns skill
+2. Follow the patterns defined in SKILL.md
+3. Use the query priority and async patterns
+4. Avoid the anti-patterns
+
+---
+
+## More Skill Ideas
+
+| Skill | Triggers | Content |
+|-------|----------|---------|
+| `api-design` | api, endpoint, route, REST | API conventions, error handling, auth patterns |
+| `component-patterns` | component, UI, React | Component structure, props, state management |
+| `database-patterns` | database, query, Supabase, SQL | Query patterns, RLS, migrations |
+| `security-patterns` | security, auth, validation | Auth flows, input validation, CSRF |
+| `performance-patterns` | performance, optimize, slow | Caching, lazy loading, profiling |
+
+---
+
+## Skill Triggers
+
+Skills are loaded when Claude detects trigger keywords in the conversation.
+
+### Good Triggers
+- Specific: `vitest`, `supabase`, `shadcn`
+- Action-oriented: `write tests`, `create component`
+- Domain terms: `authentication`, `database query`
+
+### Bad Triggers
+- Too generic: `code`, `help`, `fix`
+- Too rare: Jargon only you use
+- Overlapping: Same triggers in multiple skills
+
+### Updating Triggers
+
+After using a skill, if you notice it should have loaded but didn't, add the missing trigger keyword to the SKILL.md frontmatter.
+
+---
+
+## Skill Maintenance
+
+### When to Update
+- New patterns emerge in your codebase
+- Anti-patterns discovered
+- Team conventions change
+- New tools adopted
+
+### Version Bumping
+Increment the version in SKILL.md when making significant changes:
+- Patch (1.0.1): Typo fixes, clarifications
+- Minor (1.1.0): New patterns, examples
+- Major (2.0.0): Breaking changes to conventions
+
+---
+
+## Next Steps
+
+1. **Create one skill** for your most-referenced domain
+2. **Use it for a week** — note what's missing
+3. **Iterate** — add examples, refine patterns
+4. **Create more** — as patterns emerge in your work