Skills

Backcap Skills are machine-readable documentation files that make each domain understandable to AI coding assistants. A skill is a Markdown file with structured frontmatter that describes the module’s architecture, contracts, and usage rules in a form optimized for language models.

What is a Skill?

A skill is a SKILL.md file for a domain. It contains:

• A YAML frontmatter block with a name, description, and metadata
• A prose explanation of the module’s purpose and structure
• Tables mapping every file to its exported type and responsibility
• Explicit import rules and naming conventions
• Extension guides and constraint summaries

Skills are located at:

packages/registry/
  skills/
    backcap-core/
      SKILL.md          # Architecture rules for all domains
      references/
    backcap-auth/
      SKILL.md          # Auth domain detail
      references/

The backcap-core Skill

The backcap-core skill describes the global architecture rules that apply to every Backcap domain:

---
name: backcap-core
description: >
  Backcap is a DDD domain registry and CLI for TypeScript backends. Each domain follows
  strict Clean Architecture layers: domain (entities, value objects, domain errors, domain events),
  application (use cases, ports as interfaces, DTOs), and contracts (public factory + service interface,
  the only barrel index.ts). The Result<T,E> monad replaces exceptions for expected failures.
  Ports define interfaces that you implement with your own adapters.
metadata:
  author: Backcap
  version: 1.0.0
---

AI tools that load the backcap-core skill understand:

• The three-layer architecture and its import rules
• The Result<T, E> monad and when to use it vs. throwing
• File naming conventions (.entity.ts, .vo.ts, .port.ts, etc.)
• How the CLI commands work

The backcap-auth Skill

The backcap-auth skill provides domain-specific detail:

---
name: backcap-auth
description: >
  Backcap auth domain: DDD-structured user registration and login for TypeScript backends.
  Domain layer contains User entity, Email and Password value objects, and four typed errors
  (InvalidEmail, InvalidCredentials, UserNotFound, UserAlreadyExists). Application layer has
  RegisterUser and LoginUser use cases, plus IUserRepository, IPasswordHasher, and ITokenService
  port interfaces. Public surface is IAuthService and createAuthService factory in contracts/.
  All expected failures return Result<T,E> — no thrown errors. You implement adapters on the
  exposed ports (e.g., Prisma for IUserRepository, bcrypt for IPasswordHasher).
  Zero npm dependencies in domain and application.
---

This gives an AI assistant enough context to:

• Know which port interfaces to implement
• Understand which errors can be returned by each use case
• Generate correct code that follows the existing architectural patterns
• Avoid introducing framework imports into the domain layer

Using Skills with AI Tools

Claude Code

When working in a Backcap project, ask Claude to read the relevant skill files before making changes:

Read .claude/skills/backcap-core/SKILL.md and
.claude/skills/backcap-auth/SKILL.md, then help me
add an updatePassword use case to the auth domain.

With the skill loaded, the AI understands:

• The application/ layer is the right place for the new use case
• It must depend only on port interfaces, not on Prisma or bcrypt directly
• It must return Result<void, Error>, not throw
• The new port interface (if any) goes in application/ports/

Cursor and Similar Tools

Add the skill files to your AI context window via the @ include syntax or project context settings. The structured format of skill files is deliberately concise to fit within context limits.

Skill File Structure

A skill file has six main sections:

1. Frontmatter

YAML block at the top of the file. Contains name, description (a single dense paragraph summarizing the module), and metadata.

The description field is the most important — it is short enough to be embedded directly in a system prompt or tool description.

2. Overview

High-level summary of the module’s purpose, structure, and key design decisions.

3. Domain Map

Architecture prose and reference tables mapping every file to its exported types and responsibilities. Written for humans but structured to be parseable by machines.

4. Extension Guide

Instructions for adding new use cases or ports to the domain.

5. Conventions

File naming rules, import rules, and coding conventions specific to the module.

6. Additional Sections

Depending on the skill, additional sections may include CLI Commands or other domain-specific reference material.

Creating Skills for Your Own Domains

When you create a new domain, you should create a corresponding SKILL.md. The file should:

1. Have a one-paragraph description in the YAML frontmatter dense enough to be used as a prompt prefix
2. List every file in a table with its export and responsibility
3. State all import rules explicitly
4. Document what Result error types each use case can return
5. Reference the backcap-core skill for shared architecture rules

See backcap-core SKILL.md for a complete example.