Skills

Markdown files that give Cora domain knowledge specific to your project, stack, or technical conventions.

A skill is a structured document that teaches Cora something it should know when working on your codebase. Skills are loaded into context when relevant to the current task, so they influence code generation and planning without you repeating the same information in every prompt.

---

Storage locations

Global skills apply to every project:

~/.config/Code/User/globalStorage/codemateai.codemate-agent/settings/skills/

Project skills apply to the current workspace only:

your-project/.cora/skills/

Project skills take precedence over global skills when a file with the same name exists in both locations.

---

What goes in a skill

Skills work best for knowledge that is specific, reusable, and stable the kind of thing you'd put in a team wiki or an onboarding doc every new developer needs to read. Good candidates:

• How your API is structured authentication headers, error response shapes, pagination conventions

• How your components are organized and when to use which one

• How your testing approach works what to test, what to mock, naming conventions for test files

• Domain vocabulary what a "tenant," "workspace," "pipeline," or "event" means in your product

• Third-party integrations with non-obvious behavior an SDK with quirks, a service with particular rate limit semantics

---

Creating a skill

Create a .md file in the skills directory for the appropriate scope. The filename becomes the skill name. Write plain Markdown headers, code blocks, and lists as normal.

Open the file with a single sentence describing what it covers. Cora uses this to decide whether the skill is relevant to the current task.

Example: skills/api-conventions.md

# API conventions

This skill describes the request and response patterns used across
all backend endpoints in this project.

## Authentication

All authenticated endpoints expect a Bearer token in the Authorization
header. The token is a JWT signed with RS256.

Machine-to-machine requests use an API key in the X-Api-Key header —
never a JWT. The two auth flows are separate and must not be conflated.

## Error responses

All errors return JSON in this shape:

{
  "error": "human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "status": 400
}

The `code` field is always SCREAMING_SNAKE_CASE and safe to match on
in client code. The `error` field is for display only.

## Pagination

List endpoints use cursor-based pagination. The response includes
`nextCursor` when more results exist. Pass it as `?cursor=` on the
next request. There is no offset-based pagination in this project.

---

When skills are applied

Cora reads the skill files at the start of each task and loads those relevant to what it's about to do. Writing a new endpoint loads api-conventions.md. Writing a component loads component-patterns.md. You don't need to reference skills in your prompt Cora matches them to tasks automatically using the opening description of each file.

---

Editing skills directly

Because skill files are plain Markdown on your filesystem, you can open and edit them in any editor:

# Edit a global skill
code ~/.config/Code/User/globalStorage/codemateai.codemate-agent/settings/skills/api-conventions.md

# Edit a project skill
code .cora/skills/api-conventions.md

When a convention in your project changes, update the corresponding skill file. Stale skill files produce output that matches old conventions rather than current ones.