Skills

Skills are portable, reusable instruction bundles that give Kepler expertise in specific domains. Each skill is a SKILL.md file with frontmatter metadata and optional reference resources.

What Are Skills?

A skill is a self-contained package that teaches Kepler how to do something well — a coding framework, a testing pattern, a deployment workflow, or any repeated task.

Skills are:

• Portable — share them across projects and teams
• Installable — from local files, GitHub repos, or URLs
• Discoverable — listed by name, description, and scope
• Compatible — work with both Kepler and Claude Code

Skill Structure

A skill is a directory or file with this layout:

my-skill/
├── SKILL.md          # Skill definition (required)
└── references/       # Optional reference resources
    ├── api.md
    └── examples/

SKILL.md Frontmatter

---
name: my-skill
description: "Brief description of what this skill provides"
compatibility: "kepler"  # or "claude-code" or both
---

The body of SKILL.md contains the instructions Kepler will follow when the skill is invoked. This can include code patterns, conventions, architecture guidelines, and step-by-step workflows.

References Directory

The references/ directory can contain additional files that the skill references. These are loaded on demand when the agent uses the skill_view tool with a specific resource path.

Skill Discovery

Kepler searches for skills in four locations, in priority order (higher priority shadows lower):

1. .kepler/skills/ — project-local skills (highest priority)
2. .claude/skills/ — project-local Claude Code compatibility
3. ~/.kepler/skills/ — user-global skills
4. ~/.claude/skills/ — user-global Claude Code compatibility

A project-level skill with the same name as a global skill shadows the global one. This lets you override team-wide skills with project-specific versions.

Managing Skills

List Installed Skills

# List all skills (global and project)
kepler skills list
 
# List only project-level skills
kepler skills list --project
 
# List only global skills
kepler skills list --all

Install a Skill

# Install from a local path
kepler skills install ./path/to/my-skill
 
# Install from a GitHub repository
kepler skills install https://github.com/org/my-skill
 
# Install from a URL
kepler skills install https://example.com/skills/my-skill.tar.gz
 
# Install as a project-level skill (not global)
kepler skills install ./path/to/my-skill --project

View a Skill

# View the skill's instructions
kepler skills view my-skill
 
# View a specific reference resource within the skill
kepler skills view my-skill references/api.md

Update a Skill

kepler skills update my-skill
kepler skills update my-skill --project

Remove a Skill

kepler skills remove my-skill
kepler skills remove my-skill --project

Using Skills in a Session

Once installed, Kepler’s agent can invoke skills automatically using the Skill tool. The agent:

1. Discovers available skills via skills_list (filterable by name, description, source, or scope)
2. Loads metadata — the skill’s SKILL.md frontmatter is cached
3. Applies instructions — the full SKILL.md content is loaded on demand when the skill is activated

You can also reference skills in your prompts:

> using the react-testing skill, write tests for the Button component

Creating a Skill

Create a directory with a SKILL.md file:

---
name: react-testing
description: "Best practices for testing React components with Testing Library"
compatibility: "kepler"
---
 
# React Testing Guidelines
 
## Conventions
- Use `@testing-library/react` for component tests
- Use `@testing-library/jest-dom` for custom matchers
- Prefer `getByRole` over `getByTestId`
 
## Patterns
 
### Testing User Interactions
```tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
 
it('submits the form on button click', async () => {
  const user = userEvent.setup();
  render(<MyForm />);
  await user.click(screen.getByRole('button', { name: /submit/i }));
  expect(screen.getByText(/success/i)).toBeInTheDocument();
});

Async Testing

Use waitFor or findBy queries for async operations.

Then install it:

```bash
kepler skills install ./react-testing

Related

• Commands → Skills Subcommands — Full skill command reference
• Getting Good Results — Patterns for effective skill usage