skillc 0.2.1

A development kit for Agent Skills - the open format for extending AI agent capabilities
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# Introduction

**skillc** is the development kit for [Agent Skills](https://agentskills.io/) — the open format for extending AI agent capabilities with specialized knowledge and workflows.

## At a Glance

```text
                        SKILL.md (source)
                              │
              ┌───────────────┴───────────────┐
              │                               │
              ▼                               ▼
   ┌─────────────────────┐         ┌─────────────────────┐
   │  skillc (optional)  │         │      git push       │
   │                     │         │         ↓           │
   │  lint · build       │         │  npx skills add     │
   │  stats · search     │         │         ↓           │
   │         ↓           │         │  Claude · Cursor    │
   │  local testing      │         │  Codex · Copilot    │
   └─────────────────────┘         └─────────────────────┘
```

**skillc helps authors** validate and test skills locally. Consumers just run `npx skills add` — no compilation needed.

## Who is this for?

| Audience          | What skillc provides                                |
| ----------------- | --------------------------------------------------- |
| **Skill authors** | Create, validate, and test skills before publishing |
| **Power users**   | Track how agents use skills locally                 |

## Core Commands

| Command   | What it does                                   |
| --------- | ---------------------------------------------- |
| `init`    | Create a new skill or project structure        |
| `lint`    | Validate structure, frontmatter, and links     |
| `build`   | Compile for local testing and deploy to agents |
| `list`    | Show all managed skills                        |
| `outline` | List sections across all files                 |
| `show`    | Retrieve specific section content              |
| `open`    | Read a file                                    |
| `search`  | Full-text search with FTS5                     |
| `sources` | Tree view of source files                      |
| `stats`   | Usage analytics                                |
| `sync`    | Merge local logs to global store               |
| `mcp`     | Start MCP server for agent integration         |

### Common Options

| Command   | Option        | Description                                                       |
| --------- | ------------- | ----------------------------------------------------------------- |
| `outline` | `--level <n>` | Filter to headings ≤ level n (1-6)                                |
| `show`    | `--max-lines` | Truncate output to first n lines                                  |
| `open`    | `--max-lines` | Truncate output to first n lines                                  |
| `stats`   | `--group-by`  | Aggregate by: sections, files, commands, projects, errors, search |

## Two Interfaces

| Interface       | For                 | Example             |
| --------------- | ------------------- | ------------------- |
| **CLI** (`skc`) | Humans, scripts, CI | `skc lint my-skill` |
| **MCP**         | AI agents directly  | `skc_lint` tool     |

Both expose the same functionality. MCP provides structured output for agent integration.

## Key Concepts

### Source vs. Compiled

|              | Source                            | Compiled                                  |
| ------------ | --------------------------------- | ----------------------------------------- |
| **What**     | Your `SKILL.md` with full content | Stub directing agents to gateway commands |
| **For**      | Publishing to GitHub              | Local development/testing                 |
| **Publish?** | Yes                               | No                                        |

**Always push source, never compiled output.**

### Skill Resolution

When you run `skc <command> my-skill`, skillc searches:

1. **Project**: `.skillc/skills/my-skill/` (from current directory upward)
2. **Global**: `~/.skillc/skills/my-skill/`

Project-local skills take precedence.

### Project Detection

skillc walks upward from your current directory looking for `.skillc/`:

```
~/projects/myapp/src/          ← you are here
~/projects/myapp/.skillc/      ← project root found
```

Run commands from anywhere within a project.

## Workflow Guides

- **[Authoring](./workflows/authoring.md)** — create and structure skills
- **[Validating](./workflows/validating.md)** — lint and check quality
- **[Testing](./workflows/testing.md)** — local testing with gateway commands
- **[Publishing](./workflows/publishing.md)** — git-based distribution
- **[Analytics](./workflows/analytics.md)** — track skill usage

## Supported Agents

skillc deploys to these agent directories:

| Target     | Directory             |
| ---------- | --------------------- |
| `claude`   | `~/.claude/skills/`   |
| `codex`    | `~/.codex/skills/`    |
| `copilot`  | `~/.github/skills/`   |
| `cursor`   | `~/.cursor/skills/`   |
| `gemini`   | `~/.gemini/skills/`   |
| `kiro`     | `~/.kiro/skills/`     |
| `opencode` | `~/.opencode/skills/` |
| `trae`     | `~/.trae/skills/`     |

Use `skc build my-skill --target cursor` to deploy to a specific agent.