Skip to content

Commit b9c9563

Browse files
devrimcavusogludevrimcavusoglu
authored
Merge pull request #24 from devrimcavusoglu/docs/vitepress-site
Add VitePress documentation site for skern.dev
2 parents 3296c2e + eeb4efe commit b9c9563

30 files changed

Lines changed: 3740 additions & 0 deletions

‎.github/workflows/docs-deploy.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**'
8+
- '.github/workflows/docs-deploy.yml'
9+
workflow_dispatch:
10+
11+
permissions:
12+
contents: read
13+
pages: write
14+
id-token: write
15+
16+
concurrency:
17+
group: pages
18+
cancel-in-progress: false
19+
20+
jobs:
21+
build:
22+
runs-on: ubuntu-latest
23+
steps:
24+
- uses: actions/checkout@v4
25+
with:
26+
fetch-depth: 0
27+
28+
- uses: actions/setup-node@v4
29+
with:
30+
node-version: 22
31+
cache: npm
32+
cache-dependency-path: docs/package-lock.json
33+
34+
- uses: actions/configure-pages@v4
35+
36+
- run: npm ci
37+
working-directory: docs
38+
39+
- run: npm run docs:build
40+
working-directory: docs
41+
42+
- uses: actions/upload-pages-artifact@v3
43+
with:
44+
path: docs/.vitepress/dist
45+
46+
deploy:
47+
environment:
48+
name: github-pages
49+
url: ${{ steps.deployment.outputs.page_url }}
50+
needs: build
51+
runs-on: ubuntu-latest
52+
steps:
53+
- id: deployment
54+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,8 @@ tests/manual/reports/
2424

2525
# bv (beads viewer) local config and caches
2626
.bv/
27+
28+
# Docs (VitePress)
29+
docs/.vitepress/cache
30+
docs/.vitepress/dist
31+
docs/node_modules

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
<a href="https://github.com/devrimcavusoglu/skern/blob/main/LICENSE"><img src="https://img.shields.io/github/license/devrimcavusoglu/skern" alt="License"></a>
1313
<img src="https://img.shields.io/badge/type-CLI-black" alt="CLI">
1414
<a href="https://agentskills.io"><img src="https://img.shields.io/badge/spec-Agent%20Skills-blue" alt="Agent Skills"></a>
15+
<a href="https://skern.dev"><img src="https://img.shields.io/badge/docs-skern.dev-blue" alt="Docs"></a>
1516
</p>
1617

1718
---

‎docs/.vitepress/config.mts‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
export default defineConfig({
4+
title: 'Skern',
5+
description: 'System-wide skill registry for AI agents',
6+
7+
base: '/',
8+
cleanUrls: true,
9+
lastUpdated: true,
10+
11+
head: [
12+
['link', { rel: 'icon', href: '/logo.png' }],
13+
['meta', { property: 'og:type', content: 'website' }],
14+
['meta', { property: 'og:title', content: 'Skern' }],
15+
['meta', { property: 'og:description', content: 'System-wide skill registry for AI agents' }],
16+
['meta', { property: 'og:url', content: 'https://skern.dev' }],
17+
['meta', { property: 'og:image', content: 'https://skern.dev/logo.png' }],
18+
['meta', { name: 'twitter:card', content: 'summary' }],
19+
['meta', { name: 'twitter:title', content: 'Skern' }],
20+
['meta', { name: 'twitter:description', content: 'System-wide skill registry for AI agents' }],
21+
['meta', { name: 'twitter:image', content: 'https://skern.dev/logo.png' }],
22+
],
23+
24+
themeConfig: {
25+
logo: '/logo.png',
26+
27+
nav: [
28+
{ text: 'Guide', link: '/guide/' },
29+
{ text: 'Reference', link: '/reference/' },
30+
{ text: 'Concepts', link: '/concepts/' },
31+
{ text: 'Platforms', link: '/platforms/' },
32+
],
33+
34+
sidebar: {
35+
'/guide/': [
36+
{
37+
text: 'Guide',
38+
items: [
39+
{ text: 'Getting Started', link: '/guide/' },
40+
{ text: 'Installation', link: '/guide/installation' },
41+
{ text: 'Quick Start', link: '/guide/quick-start' },
42+
{ text: 'Agent Setup', link: '/guide/agent-setup' },
43+
],
44+
},
45+
],
46+
'/reference/': [
47+
{
48+
text: 'Reference',
49+
items: [
50+
{ text: 'Overview', link: '/reference/' },
51+
{ text: 'Commands', link: '/reference/commands' },
52+
{ text: 'Validation', link: '/reference/validation' },
53+
{ text: 'Overlap Detection', link: '/reference/overlap-detection' },
54+
],
55+
},
56+
],
57+
'/concepts/': [
58+
{
59+
text: 'Concepts',
60+
items: [
61+
{ text: 'Architecture', link: '/concepts/' },
62+
{ text: 'Skill Format', link: '/concepts/skill-format' },
63+
{ text: 'Registry', link: '/concepts/registry' },
64+
{ text: 'Platform Adapters', link: '/concepts/platform-adapters' },
65+
],
66+
},
67+
],
68+
'/platforms/': [
69+
{
70+
text: 'Platforms',
71+
items: [
72+
{ text: 'Overview', link: '/platforms/' },
73+
{ text: 'Claude Code', link: '/platforms/claude-code' },
74+
{ text: 'Codex CLI', link: '/platforms/codex-cli' },
75+
{ text: 'OpenCode', link: '/platforms/opencode' },
76+
],
77+
},
78+
],
79+
'/contributing/': [
80+
{
81+
text: 'Contributing',
82+
items: [
83+
{ text: 'Contributing Guide', link: '/contributing/' },
84+
{ text: 'Development', link: '/contributing/development' },
85+
{ text: 'Manual Testing', link: '/contributing/manual-testing' },
86+
],
87+
},
88+
],
89+
},
90+
91+
socialLinks: [
92+
{ icon: 'github', link: 'https://github.com/devrimcavusoglu/skern' },
93+
],
94+
95+
editLink: {
96+
pattern: 'https://github.com/devrimcavusoglu/skern/edit/main/docs/:path',
97+
text: 'Edit this page on GitHub',
98+
},
99+
100+
search: {
101+
provider: 'local',
102+
},
103+
104+
footer: {
105+
message: 'Released under the Apache 2.0 License.',
106+
copyright: 'Copyright © 2025-present Devrim Cavusoglu',
107+
},
108+
},
109+
})

‎docs/.vitepress/theme/custom.css‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
:root {
2+
--vp-c-brand-1: #5b8def;
3+
--vp-c-brand-2: #4a7de0;
4+
--vp-c-brand-3: #3a6dd1;
5+
--vp-c-brand-soft: rgba(91, 141, 239, 0.14);
6+
7+
--vp-home-hero-name-color: transparent;
8+
--vp-home-hero-name-background: linear-gradient(135deg, #5b8def 0%, #a855f7 100%);
9+
10+
--vp-home-hero-image-background-image: linear-gradient(135deg, rgba(91, 141, 239, 0.2) 0%, rgba(168, 85, 247, 0.2) 100%);
11+
--vp-home-hero-image-filter: blur(44px);
12+
}
13+
14+
.dark {
15+
--vp-c-brand-1: #7da5f4;
16+
--vp-c-brand-2: #5b8def;
17+
--vp-c-brand-3: #4a7de0;
18+
--vp-c-brand-soft: rgba(91, 141, 239, 0.16);
19+
20+
--vp-home-hero-image-background-image: linear-gradient(135deg, rgba(91, 141, 239, 0.3) 0%, rgba(168, 85, 247, 0.3) 100%);
21+
}

‎docs/.vitepress/theme/index.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
import DefaultTheme from 'vitepress/theme'
2+
import './custom.css'
3+
4+
export default DefaultTheme

‎docs/concepts/index.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Architecture
2+
3+
Skern separates concerns into four layers:
4+
5+
```
6+
Skill Author --> skern --> Registry --> Agent Runtime
7+
|
8+
+-------+-------+
9+
| | |
10+
Claude Codex OpenCode
11+
Code CLI
12+
```
13+
14+
## Layers
15+
16+
### Skill Definition
17+
18+
Metadata and behavior live in a single `SKILL.md` file. The file uses YAML frontmatter for structured fields (name, description, author, version, allowed-tools) and markdown body for the skill's instructions.
19+
20+
See [Skill Format](/concepts/skill-format) for the full specification.
21+
22+
### Skill Registry
23+
24+
Skills are stored as directories containing a `SKILL.md` file. Two scopes are available:
25+
26+
- **Project scope** — `.skern/skills/<name>/` in the current project
27+
- **User scope** — `~/.skern/skills/<name>/` for system-wide skills
28+
29+
See [Registry](/concepts/registry) for details.
30+
31+
### Validation
32+
33+
Before a skill enters the registry, skern validates it against the [Agent Skills](https://agentskills.io) specification. This includes name format checks, description requirements, and overlap detection against existing skills.
34+
35+
See [Validation](/reference/validation) and [Overlap Detection](/reference/overlap-detection) for rules and thresholds.
36+
37+
### Platform Adapters
38+
39+
Each supported platform has an adapter that knows where to install skills. Adapters copy the `SKILL.md` to the platform-specific directory, making the skill immediately available to the agent runtime.
40+
41+
See [Platform Adapters](/concepts/platform-adapters) for how adapters work.

‎docs/concepts/platform-adapters.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Platform Adapters
2+
3+
Platform adapters bridge the skill registry with agent runtimes. Each adapter knows the target platform's directory structure and copies skill files accordingly.
4+
5+
## How Adapters Work
6+
7+
When you run `skern skill install`, the adapter:
8+
9+
1. Reads the `SKILL.md` from the skern registry
10+
2. Creates the platform-specific skill directory
11+
3. Copies the `SKILL.md` into the target location
12+
4. The agent runtime discovers the skill on its next invocation
13+
14+
## Supported Platforms
15+
16+
| Platform | Adapter name | Detection |
17+
|----------|-------------|-----------|
18+
| Claude Code | `claude-code` | Looks for `.claude/` or `~/.claude/` |
19+
| Codex CLI | `codex-cli` | Looks for `.agents/` or `~/.agents/` |
20+
| OpenCode | `opencode` | Looks for `.opencode/` or `~/.config/opencode/` |
21+
22+
## Installation Paths
23+
24+
Each platform uses different directories for user-level and project-level skills:
25+
26+
| Platform | User-level | Project-level |
27+
|----------|-----------|---------------|
28+
| Claude Code | `~/.claude/skills/<name>/` | `.claude/skills/<name>/` |
29+
| Codex CLI | `~/.agents/skills/<name>/` | `.agents/skills/<name>/` |
30+
| OpenCode | `~/.config/opencode/skills/<name>/` | `.opencode/skills/<name>/` |
31+
32+
## Auto-Detection
33+
34+
Skern auto-detects which platforms are installed on your system. Use `skern platform list` to see detected platforms:
35+
36+
```sh
37+
skern platform list
38+
```
39+
40+
## Install to All Platforms
41+
42+
Use `--platform all` to install a skill to every detected platform at once:
43+
44+
```sh
45+
skern skill install code-review --platform all
46+
```
47+
48+
## Platform Status Matrix
49+
50+
View which skills are installed on which platforms:
51+
52+
```sh
53+
skern platform status
54+
```
55+
56+
This shows a matrix of skills and their installation status across all detected platforms.

‎docs/concepts/registry.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Registry
2+
3+
The skill registry is where skern stores skill definitions. Skills are organized as directories, each containing a `SKILL.md` file.
4+
5+
## Scopes
6+
7+
### Project Scope
8+
9+
Project-scoped skills live in `.skern/skills/` within your project directory. These are specific to the project and can be checked into version control.
10+
11+
```
12+
.skern/
13+
skills/
14+
code-review/
15+
SKILL.md
16+
deploy/
17+
SKILL.md
18+
```
19+
20+
Initialize the project registry with:
21+
22+
```sh
23+
skern init
24+
```
25+
26+
### User Scope
27+
28+
User-scoped skills live in `~/.skern/skills/` and are available across all projects on your machine.
29+
30+
```
31+
~/.skern/
32+
skills/
33+
global-lint/
34+
SKILL.md
35+
```
36+
37+
### Scope Selection
38+
39+
Most commands accept a `--scope` flag:
40+
41+
| Value | Description |
42+
|-------|-------------|
43+
| `project` | Project-level registry only (default for most commands) |
44+
| `user` | User-level registry only |
45+
| `all` | Both registries |
46+
47+
## Skill Count Warnings
48+
49+
Registries have recommended size limits:
50+
51+
- **Project scope** — warns at > 20 skills
52+
- **User scope** — warns at > 50 skills
53+
54+
These are soft limits — skern will continue to work, but warns to encourage organization.
55+
56+
## Registry vs Platform
57+
58+
The registry is where skills are **defined**. Platforms are where skills are **installed**. A skill must exist in the registry before it can be installed to a platform.
59+
60+
```
61+
Registry (.skern/skills/) --install--> Platform (.claude/skills/)
62+
```
63+
64+
See [Platform Adapters](/concepts/platform-adapters) for installation details.

0 commit comments

Comments
 (0)