Skills

Skills are the primary mechanism for packaging and distributing domain knowledge to AI agents in CodeCourier. Each skill is a named collection of files - markdown documents, code examples, API references, best-practice guides - that are injected into the .claude/skills/ directory of the sandbox before the CLI tool starts. When an agent reads those files, it gains expert-level knowledge about a specific technology or practice area.

Skills support multiple files, which means a single skill can contain a thorough, multi-document knowledge base rather than a single monolithic file. Each skill is independently versioned, enabling you to update domain knowledge without touching unrelated skills.

What Skills Are

Think of skills as the library that you hand to an AI agent when it sits down to work. Rather than hoping the agent’s training data contains the right patterns for your specific stack, you provide curated, accurate, up-to-date reference material at session start.

Example skills and what they contain:

Skill Data Model

Skills are stored across three related tables in the database:

// Core skill record
skills: {
  skillId: string       // unique identifier
  name: string          // display name (e.g., "frontend-design")
  description: string   // what this skill does and when to use it
  category: string      // grouping (e.g., "frontend", "testing", "backend", "security")
  fileCount: number     // number of files in the active version of this skill
  isEnabled: boolean    // whether this skill is selectable in the UI
}

// Individual files within a skill
skillFiles: {
  skillId: string
  path: string          // file path within the skill directory (e.g., "patterns.md")
  content: string       // full file content (markdown or code)
}

// Version history
skillVersions: {
  skillId: string
  version: number       // incrementing version number
  name: string          // name at time of publish
  description: string   // description at time of publish
  category: string      // category at time of publish
  fileCount: number     // number of files in this version
  status: "active" | "inactive"
  publishedAt: number   // Unix timestamp
  publishedBy: string   // user ID of publisher
}

Creating a Custom Skill

Custom skills are created from the Skills management page. Navigate to the skills section of your project or access the global skills library from the platform settings.

# Convex Query Patterns

## Reading Data
Always use `useQuery` for reactive data subscriptions in React components.
Use `ctx.db.query` inside Convex server functions.

### Pagination
Never use `.collect()` on large tables. Use `.paginate()` instead:
```ts
const results = await ctx.db
  .query("posts")
  .order("desc")
  .paginate(opts); // opts.numItems controls page size
```

## Writing Data
All data mutations must go through Convex mutation functions.
Never write directly to the database from client code.

### Scheduling Background Work
Heavy operations go to `ctx.scheduler.runAfter` to avoid timeout:
```ts
await ctx.scheduler.runAfter(0, internal.tasks.processLargeDataset, {
  datasetId: args.datasetId,
});
```

## Validators
Use Convex's built-in validators for all mutation and action arguments.
Do NOT use Zod inside Convex functions.

Skill File Organization Best Practices

How you organize files within a skill affects how easily an agent can navigate the knowledge. Follow these guidelines:

• One topic per file - An overview.md for high-level concepts, a patterns.md for code patterns, an anti-patterns.md for things to avoid, and an api-reference.md for specific APIs. This makes each file scannable without overwhelming context.
• Lead with the most important rules - Agents read files sequentially. Put the most critical constraints at the top of each file, not buried in the middle.
• Use concrete code examples - Markdown explanations are useful, but code snippets showing correct and incorrect usage are even more effective.
• Keep individual files under 500 lines - Very long files are harder for agents to process effectively. Split large reference documents across multiple focused files.
• Name files for discoverability - Use names like quick-reference.md, gotchas.md, examples.mdso the agent can infer the file’s purpose from its name alone.

Versioning Skills

Skills follow the same versioning lifecycle as Context Documents. Editing a skill’s files creates a draft. Publishing creates a new version, activates it, and deactivates the previous version.

Key scenarios that should trigger a new skill version:

• A library releases a major version with breaking API changes
• Your team adopts a new coding convention that agents should follow
• An agent made a systematic mistake that can be prevented with a new rule in the skill
• You discover that an existing pattern in the skill is outdated or incorrect

Assigning Skills to Personas

To assign skills to a persona, navigate to the persona’s detail page and open the Skills tab. The tab shows all enabled skills in the project organized into three sections:

• Skills - The skill packages described in this guide
• Commands - Claude Code slash-command extensions
• Scripts - Executable shell/Python scripts

Select the checkboxes next to each skill you want available for this persona. The selections are saved immediately and apply to all sessions run by this persona going forward.

Assigning Skills to Session Types

Default skill assignments for each session type are configured in the corresponding setup tab within Project Settings. For example, to configure the default skills for all Issue Discovery sessions, navigate to /p/{id}/issues-setup and select the desired skills from the Skills, Commands, and Scripts sections on that page.

These session-type defaults apply to any session of that type where the running persona does not have its own explicit skill selections.

Enabling and Disabling Skills

Skills have an isEnabled flag. Disabled skills do not appear in the selection checkboxes on persona Skills tabs or in Project Settings. This is useful for skills that are in development or that you want to temporarily hide from the selection UI without deleting them.

Disabling a skill does not remove it from sandboxes that were already assigned it - existing assignments are preserved. Disabling only prevents the skill from appearing as a selectable option for new assignments.

Next Steps