agent-ctx 1.0.0

package/src/templates/en/skills/skill-generating.md

@@ -0,0 +1,116 @@
+---
+name: generating-skills
+description: Create new agent skills following SKILL.md best practices. Use when creating, validating, or improving skill files for AI agent consumption.
+---
+
+# Generating Skills
+
+Create effective skills that AI agents can discover and use.
+
+## When to use
+
+- Creating a new skill from scratch
+- Validating existing skill format
+- Improving skill discoverability
+- Converting documentation to skill format
+
+## Standard Folder Structure
+
+```
+skill-name/
+├── SKILL.md        # Required: instructions + metadata
+├── scripts/        # Optional: executable utilities
+├── references/     # Optional: detailed documentation
+└── assets/         # Optional: templates, resources
+```
+
+For simple skills, a single `SKILL.md` file is sufficient.
+
+## YAML Frontmatter Requirements
+
+```yaml
+---
+name: skill-name
+description: What the skill does and when to use it. Third person. Max 1024 chars.
+---
+```
+
+### Name Validation
+
+- Maximum 64 characters
+- Lowercase letters, numbers, hyphens only
+- No consecutive hyphens (`--`)
+- Cannot start/end with hyphen
+- Pattern: `^[a-z0-9]+(-[a-z0-9]+)*$`
+
+**Good names**: `api-design`, `git-workflow`, `processing-pdfs`
+**Bad names**: `APIDesign`, `git--workflow`, `-api-design`
+
+### Description Guidelines
+
+- Write in third person
+- Include both what it does AND when to use it
+- Be specific with trigger terms
+- Max 1024 characters
+
+**Good**: `Design REST APIs with consistent patterns. Use when creating endpoints or handling errors.`
+**Bad**: `Helps with APIs`
+
+## SKILL.md Template
+
+```markdown
+---
+name: skill-name
+description: Brief description in third person. Include when to use.
+---
+
+# Skill Name
+
+Brief overview.
+
+## When to use
+
+- Trigger condition 1
+- Trigger condition 2
+
+## Quick start
+
+Minimal example to get started.
+
+## Implementation steps
+
+1. Step 1
+2. Step 2
+
+## Best practices
+
+### ✅ Do
+- Good practice
+
+### ❌ Avoid
+- Anti-pattern
+
+## References
+
+- [Link](url)
+```
+
+## Token Efficiency
+
+- Keep SKILL.md under 500 lines
+- Split content into separate files for complex skills
+- Use progressive disclosure (reference files loaded on-demand)
+- Assume Claude knows common patterns
+
+## Workflow Checklist
+
+Copy and track progress:
+
+```
+- [ ] Name follows lowercase-hyphen format
+- [ ] Description is specific and includes triggers
+- [ ] "When to use" section present
+- [ ] Quick start example included
+- [ ] Best practices documented
+- [ ] Under 500 lines
+```

package/src/templates/en/skills/skill-git.md

@@ -0,0 +1,109 @@
+---
+name: git-workflow
+description: Git conventions, branching strategies, and commit message formatting. Use when creating commits, branches, PRs, or resolving git conflicts.
+---
+
+# Git Workflow
+
+Git conventions, commits, and workflow patterns.
+
+## When to use
+
+- Writing commit messages
+- Creating feature branches
+- Managing pull requests
+- Resolving conflicts or rebasing
+
+## Commit Messages (Conventional Commits)
+
+### Format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting (no code change) |
+| `refactor` | Code refactoring |
+| `test` | Add/modify tests |
+| `chore` | Maintenance, deps |
+| `perf` | Performance improvement |
+
+### Examples
+
+```bash
+feat(auth): add login with Google OAuth
+fix(api): handle null response in user fetch
+docs: update installation guide
+refactor(utils): simplify date formatting function
+
+# Breaking change
+feat(api)!: change response format
+
+BREAKING CHANGE: Response now returns data in `result` instead of `data`
+```
+
+## Branching Strategy (Git Flow)
+
+```
+main (production)
+  │
+  └── develop (development)
+        │
+        ├── feature/new-feature
+        ├── bugfix/fix-bug
+        └── release/v1.2.0
+```
+
+### Create Feature Branch
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feature/descriptive-name
+```
+
+## Useful Commands
+
+```bash
+# Stash
+git stash                    # Save changes
+git stash pop                # Restore changes
+
+# Interactive Rebase
+git rebase -i HEAD~3         # Last 3 commits
+
+# Cherry Pick
+git cherry-pick abc123       # Apply specific commit
+
+# Bisect (find bug)
+git bisect start
+git bisect bad               # Current commit has bug
+git bisect good abc123       # Known good commit
+```
+
+## Best practices
+
+### ✅ Do
+
+- Atomic commits (one logical change per commit)
+- Small, focused PRs
+- Rebase before merge
+- Squash WIP commits
+
+### ❌ Avoid
+
+- Commits with just "fix" or "update"
+- Giant PRs (>500 lines)
+- Force push to shared branches
+- Mixing refactors with features

package/src/templates/en/skills/skill-project-state.md

@@ -0,0 +1,99 @@
+---
+name: tracking-project-state
+description: Manage project state documentation for AI agent context. Use when updating current work status, priorities, or project phase.
+---
+
+# Tracking Project State
+
+Maintain a living document of current project status for AI agents.
+
+## When to use
+
+- Starting or completing major tasks
+- Changing project priorities
+- Blocking issues arise
+- Sprint or phase transitions
+
+## Project State Structure
+
+```markdown
+# Project State
+
+## Current Phase
+[Development / Testing / Maintenance / etc.]
+
+## Active Work
+
+### In Progress
+- [ ] Feature X - [brief status]
+- [ ] Bug fix Y - [brief status]
+
+### Blocked
+- Issue Z - [reason] - [owner]
+
+## Recent Completions
+- ✅ Feature A (date)
+- ✅ Bug fix B (date)
+
+## Next Priorities
+1. Priority task 1
+2. Priority task 2
+
+## Known Issues
+- Issue description - [severity]
+```
+
+## Update Frequency
+
+Update project_state.md when:
+- Starting significant work
+- Completing features or fixes
+- Encountering blockers
+- Changing priorities
+- Beginning new sprint/phase
+
+## Best Practices
+
+### ✅ Do
+
+- Keep it current (update same day)
+- Be specific about status
+- Include blockers and owners
+- Date recent completions
+- Limit to top priorities
+
+### ❌ Avoid
+
+- Stale information (>1 week old)
+- Too much detail (link to issues instead)
+- Historical log (keep only recent)
+- Vague status updates
+
+## Integration with AI Agents
+
+AI agents check project_state.md to:
+- Understand what's being worked on
+- Avoid conflicting changes
+- Prioritize their suggestions
+- Provide contextual help
+
+## File Location
+
+```
+project/
+└── .context/
+    └── project_state.md  # Current project state
+```
+
+## Quick Update Template
+
+When updating, use this format:
+
+```markdown
+## Update [Date]
+
+**Completed**: [what was finished]
+**In Progress**: [what's being worked on]
+**Next**: [upcoming priority]
+**Blocked**: [any blockers] (if applicable)
+```

package/src/templates/en/skills/skill-react.md

@@ -0,0 +1,94 @@
+---
+name: react-patterns
+description: React component patterns, hooks, and best practices for TypeScript. Use when creating components, custom hooks, or optimizing rendering.
+---
+
+# React Patterns
+
+Patterns and best practices for React development.
+
+## When to use
+
+- Creating reusable components
+- Handling complex state
+- Optimizing rendering performance
+- Building custom hooks
+
+## Component Patterns
+
+### Functional Component with Typed Props
+
+```tsx
+interface ButtonProps {
+  variant: 'primary' | 'secondary';
+  children: React.ReactNode;
+  onClick?: () => void;
+  disabled?: boolean;
+}
+
+export function Button({ variant, children, onClick, disabled }: ButtonProps) {
+  return (
+    <button
+      className={`btn btn-${variant}`}
+      onClick={onClick}
+      disabled={disabled}
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+### Custom Hook
+
+```tsx
+function useToggle(initialValue = false) {
+  const [value, setValue] = useState(initialValue);
+  
+  const toggle = useCallback(() => setValue(v => !v), []);
+  const setTrue = useCallback(() => setValue(true), []);
+  const setFalse = useCallback(() => setValue(false), []);
+  
+  return { value, toggle, setTrue, setFalse };
+}
+```
+
+### Compound Components
+
+```tsx
+const Card = ({ children }) => <div className="card">{children}</div>;
+Card.Header = ({ children }) => <div className="card-header">{children}</div>;
+Card.Body = ({ children }) => <div className="card-body">{children}</div>;
+
+// Usage:
+<Card>
+  <Card.Header>Title</Card.Header>
+  <Card.Body>Content</Card.Body>
+</Card>
+```
+
+## Directory Structure
+
+```
+components/
+├── ui/           # Base components (Button, Input, Modal)
+├── features/     # Feature-specific components
+├── layouts/      # Layouts and wrappers
+└── hooks/        # Reusable custom hooks
+```
+
+## Best practices
+
+### ✅ Do
+
+- Use `useMemo` and `useCallback` for optimization
+- Type all props with TypeScript
+- Extract logic to custom hooks
+- Use composition over inheritance
+
+### ❌ Avoid
+
+- Excessive props drilling (use Context)
+- useEffect without correct dependencies
+- State in the wrong component
+- Rendering lists without `key`

package/src/templates/en/skills/skill-rules.md

@@ -0,0 +1,100 @@
+---
+name: creating-rules
+description: Define coding rules and standards documentation. Use when establishing or updating coding conventions, linter rules, or team standards.
+---
+
+# Creating Coding Rules
+
+Define and document coding standards that AI agents and developers must follow.
+
+## When to use
+
+- Establishing new coding conventions
+- Documenting existing team standards
+- Adding linter or formatter rules
+- Clarifying ambiguous code patterns
+
+## Rule Document Structure
+
+```markdown
+# Rule: [Rule Name]
+
+> Brief description of the rule
+
+## Why this rule exists
+
+[Explain the problem this prevents or benefit it provides]
+
+## Requirements
+
+- Requirement 1
+- Requirement 2
+
+## ✅ Correct Examples
+
+[Code showing correct usage]
+
+## ❌ Incorrect Examples
+
+[Code showing what to avoid]
+
+## Exceptions
+
+[Valid exceptions or "No exceptions"]
+
+## Enforcement
+
+- [ ] Linter rule: [rule name]
+- [ ] Code review checklist
+- [ ] Automated test
+```
+
+## Common Rule Categories
+
+### Code Style
+
+- Naming conventions (camelCase, PascalCase)
+- File organization
+- Import ordering
+- Comment standards
+
+### Architecture
+
+- Component structure
+- State management patterns
+- API design patterns
+- Error handling
+
+### Quality
+
+- Test coverage requirements
+- Performance thresholds
+- Security practices
+- Accessibility standards
+
+## Writing Effective Rules
+
+### ✅ Do
+
+- Provide concrete examples
+- Explain the "why" not just the "what"
+- Include both correct and incorrect examples
+- Make rules enforceable (linter, tests)
+
+### ❌ Avoid
+
+- Vague requirements
+- Rules without examples
+- Conflicting rules
+- Overly strict exceptions
+
+## File Organization
+
+```
+.context/
+└── rules/
+    ├── coding-standards.md    # Main standards
+    ├── naming-conventions.md  # Naming rules
+    ├── testing-rules.md       # Test requirements
+    └── security-rules.md      # Security practices
+```

package/src/templates/en/skills/skill-testing.md

@@ -0,0 +1,139 @@
+---
+name: testing-practices
+description: Testing strategies, patterns, and best practices with Jest/Vitest. Use when writing unit tests, integration tests, or mocking dependencies.
+---
+
+# Testing Practices
+
+Strategies and patterns for effective testing.
+
+## When to use
+
+- Writing unit tests
+- Creating integration tests
+- Mocking dependencies
+- Testing React components
+
+## Testing Pyramid
+
+```
+        /\
+       /  \     E2E Tests (Playwright, Cypress)
+      /----\    
+     /      \   Integration Tests
+    /--------\  
+   /          \ Unit Tests
+  /____________\
+```
+
+## Unit Tests (Vitest)
+
+### Basic Test
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { sum } from './sum';
+
+describe('sum', () => {
+  it('should add two positive numbers', () => {
+    expect(sum(1, 2)).toBe(3);
+  });
+  
+  it('should handle negative numbers', () => {
+    expect(sum(-1, 1)).toBe(0);
+  });
+});
+```
+
+### Test with Setup/Teardown
+
+```typescript
+describe('UserService', () => {
+  let service: UserService;
+  
+  beforeEach(() => {
+    service = new UserService();
+  });
+  
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+  
+  it('should create a user', async () => {
+    const user = await service.create({ name: 'Test' });
+    expect(user.id).toBeDefined();
+  });
+});
+```
+
+## Mocking
+
+```typescript
+// Module mock
+vi.mock('./database', () => ({
+  query: vi.fn().mockResolvedValue([{ id: 1, name: 'Test' }])
+}));
+
+// Function mock
+const mockFetch = vi.fn().mockResolvedValue({
+  json: () => Promise.resolve({ data: 'test' })
+});
+
+// Spy
+const spy = vi.spyOn(console, 'log');
+myFunction();
+expect(spy).toHaveBeenCalledWith('expected message');
+```
+
+## React Testing Library
+
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react';
+
+test('should display and interact with button', async () => {
+  const handleClick = vi.fn();
+  render(<Button onClick={handleClick}>Click me</Button>);
+  
+  const button = screen.getByRole('button', { name: /click me/i });
+  expect(button).toBeInTheDocument();
+  
+  await fireEvent.click(button);
+  expect(handleClick).toHaveBeenCalledTimes(1);
+});
+```
+
+## Test Structure
+
+```
+__tests__/
+├── unit/
+│   ├── services/
+│   └── utils/
+├── integration/
+│   └── api/
+└── e2e/
+    └── flows/
+```
+
+## Best practices
+
+### ✅ Do
+
+- One assertion per test (when possible)
+- Descriptive names: `should_X_when_Y`
+- Arrange-Act-Assert (AAA)
+- Independent tests
+
+### ❌ Avoid
+
+- Tests that depend on order
+- Logic in tests
+- Flaky tests (intermittent)
+- Mocking everything
+
+## Coverage Targets
+
+- Statements: 80%
+- Branches: 75%
+- Functions: 80%
+- Lines: 80%

package/src/templates/es/base/_agents.md

@@ -0,0 +1,62 @@
+# Contexto para Agentes IA
+
+> **LEE ESTO PRIMERO** — Este archivo es el punto de entrada para cualquier agente IA trabajando en este proyecto.
+
+Eres un desarrollador experto senior uniéndote a este proyecto.
+Tu objetivo es ayudar a construir, refactorizar y mantener este código siguiendo estrictamente nuestra arquitectura y reglas.
+
+---
+
+## Índice de Conocimiento
+
+Antes de escribir **cualquier** código, **DEBES** leer y entender:
+
+| Prioridad | Archivo | Propósito |
+|-----------|---------|-----------|
+| 1 | `.context/architecture.md` | Stack tecnológico completo, estructura, flujo de datos |
+| 2 | `.context/rules/coding-standards.md` | Convenciones de código, reglas TypeScript, naming |
+| 3 | `.context/project_state.md` | Tareas actuales, TODOs, bloqueantes |
+| 4 | `.context/skills/` | Patrones para React, APIs, testing, etc. |
+
+---
+
+## Memory Bank
+
+Para persistencia de sesión y continuidad de contexto, revisa:
+
+- `.context/memory/project_brief.md` — Resumen de alto nivel del proyecto
+- `.context/memory/tech_context.md` — Decisiones técnicas y su justificación
+- `.context/memory/active_context.md` — Foco actual y cambios recientes
+- `.context/memory/progress.md` — Trabajo completado y milestones
+
+---
+
+## Inicio Rápido para Agentes
+
+1. **Lee** este archivo completamente
+2. **Abre** `.context/architecture.md` para entender el stack
+3. **Revisa** `.context/rules/coding-standards.md` para convenciones
+4. **Consulta** `.context/project_state.md` para prioridades actuales
+5. **Sigue** todos los patrones en `.context/skills/` cuando aplique
+
+---
+
+## Instrucciones Específicas del Proyecto
+
+<!-- 
+TODO: Añade tus instrucciones específicas aquí.
+Ejemplos:
+- "Siempre usa pnpm, no npm"
+- "Ejecuta `pnpm test` antes de commitear"
+- "La rama main está protegida, usa feature branches"
+-->
+
+[Añade tus instrucciones específicas del proyecto aquí]
+
+---
+
+## Notas
+
+- Este archivo fue generado por [agent-ctx](https://github.com/avicdro/agent-ctx)
+- Personaliza todos los archivos `.context/` según tu proyecto
+- Mantén este archivo actualizado conforme evoluciona tu proyecto