Skills Overview

Skills give an Intern its job-specific behavior. A freshly paired device ships with no role-specific skills installed — on the first user message, a built-in onboarding skill asks for the user's role, fetches the matching skill bundle from GitHub, and extracts it into the device's skills directory. From then on, the runtime can route requests to the right skill (e.g. /code-review, /expense-tracker, /seo-audit) without firmware updates.

Source of truth for the skill catalog: autonomous-ai/intern-skills.

What's on the device vs. what's on GitHub

┌─ GitHub: autonomous-ai/intern-skills ─────────────────────┐
│                                                            │
│  main/                                                     │
│  ├── version.txt              ← semver, e.g. "1.0.43"      │
│  ├── manifest.json            ← role → zip + skill list    │
│  └── skills_zip/                                           │
│      ├── generic.zip          ← always installed           │
│      ├── developer.zip        ← role bundles               │
│      ├── marketing.zip                                     │
│      ├── designer.zip                                      │
│      └── …one zip per role                                 │
└────────────────────────────────────────────────────────────┘
                            │
                            │  raw.githubusercontent.com/…/main
                            ▼
┌─ Intern device ────────────────────────────────────────────┐
│                                                            │
│  workspace/skills/                                         │
│  ├── autonomous-intern-onboarding/                         │
│  │   ├── SKILL.md             ← built-in, ships with image │
│  │   ├── onboarding.json      ← installed role + version   │
│  │   └── manifest_cache.json  ← last fetched manifest      │
│  ├── <generic skill folders>  ← extracted from generic.zip │
│  └── <role skill folders>     ← extracted from {role}.zip  │
└────────────────────────────────────────────────────────────┘

The onboarding skill is the only one that ships in the device image. Everything else — the generic bundle and the role bundle — is pulled from GitHub on first use.

The onboarding flow

The autonomous-intern-onboarding skill runs as a mandatory pre-reply check on every user message. Its SKILL.md instructs the runtime: before answering anything, read workspace/skills/autonomous-intern-onboarding/onboarding.json. If that file doesn't exist or installed_role is empty, ignore the user's message and run onboarding instead.

First user message
       │
       ▼
┌─────────────────────────────┐
│ onboarding.json exists?      │
└─────────────────────────────┘
       │ no                    │ yes
       ▼                       ▼
 Send greeting + ask role     do nothing — answer normally
       │
       ▼
 Fetch manifest.json ──────► cache as manifest_cache.json
       │
       ▼
 Match user reply against
 manifest.roles[*].keywords
       │
       ├─ confident match ─────────────────► install
       ├─ ambiguous → ask which one ──┐
       ├─ no match → list roles ──────┤ retry, max 3 attempts
       └─ user says "skip" ───────────┘ → install generic only
       │
       ▼
 Download generic.zip + {role}.zip
 from raw.githubusercontent.com/…/skills_zip/
 → extract to workspace/skills/
       │
       ▼
 Write onboarding.json:
   { installed_role, installed_version,
     installed_at, generic_installed,
     skills: [generic… + role…] }
       │
       ▼
 Send confirmation to user's channel

The greeting the user sees:

👋 Hey there! Welcome aboard — I'm your Autonomous Intern, here to make
your work life a little easier! 🎉

Before we dive in, I'd love to get to know you a bit better.
What's your role or what do you do day-to-day?

Here are some examples to get you started:
💻 Developer · 📣 Marketing · 🎨 Designer · 💰 Sales · ⚙️ Operations
👥 HR · 📊 Finance · 🎧 Customer Service · 📋 Project Manager

Just type your role or describe what you do — I'll take it from there! 😊

Matching is keyword-based against the keywords array in manifest.json. The full keyword list per role is in Role Catalog.

What lands on disk

After a successful onboarding for, say, the developer role at manifest version 1.0.43, workspace/skills/ looks like this:

workspace/skills/
├── autonomous-intern-onboarding/
│   ├── SKILL.md
│   ├── onboarding.json
│   └── manifest_cache.json
├── calendar-helper/        ← from generic.zip
├── file-manager/
├── gmail/
├── web-search/
├── …other generic skills…
├── code-review/            ← from developer.zip
├── debug/
├── git-helper/
├── system-design/
└── …other developer skills…

Each skill folder contains its own SKILL.md (the runtime contract) and any helper files. Skill folders from the role-specific zip overwrite generic folders if names collide — role wins over generic.

The corresponding onboarding.json:

{
  "installed_role": "developer",
  "installed_version": "1.0.43",
  "installed_at": "2026-05-18T06:30:00Z",
  "generic_installed": true,
  "skills": [
    "calendar-helper", "file-manager", "gmail", "web-search",
    "code-review", "debug", "git-helper", "system-design"
  ],
  "update_cronjob_id": "abc-123-def"
}

Lifecycle

Event	What happens
Device first boot	Only `autonomous-intern-onboarding` exists in `workspace/skills/`. No `onboarding.json`.
First user message	Greeting fires, role is matched, generic + role zips are fetched and extracted, `onboarding.json` written.
Subsequent messages	Onboarding skill sees `onboarding.json`, does nothing — normal skill routing applies.
User says "change my role"	Old role-specific skill folders are deleted, new role's zip is fetched, generic is kept. See Managing Skills → Role Change.
Every 6 hours (cronjob)	Onboarding skill fetches `version.txt`, compares to `installed_version`, re-downloads zips if newer. See Managing Skills → Auto-Update.
`onboarding.json` corrupted	Onboarding skill deletes it and re-triggers the greeting.

Failure modes

Case	Behavior
No internet during onboarding	Retry on next session. User is informed but not blocked.
Zip download fails	Retry 3× with 5s delay, then notify and retry next session.
User gives gibberish role	Re-ask, max 3 attempts. After that → install generic only.
`keywords` match multiple roles	Skill asks the user to pick between the top matches.
Folder name conflict (generic vs. role)	Role-specific overwrites generic.
`manifest.json` unreachable	Use `manifest_cache.json` from the last successful fetch.

When you'd care about this as a developer

You're building a custom skill and need to know where it lands and how a device picks it up — see Role Catalog for the bundles, and the skill spec in the repo for the SKILL.md format.
You're debugging an Intern that "doesn't know" a skill it should — start with Managing Skills → Troubleshooting.
You want to ship a new role bundle — add it to manifest.json, drop {role}.zip into skills_zip/, bump version.txt. Devices pick it up on the next cronjob tick.

Where to go next

Role Catalog — every role in manifest.json with keywords, description, and the skills it ships.
Managing Skills — role change, auto-update cronjob, manual reset, troubleshooting.

What's on the device vs. what's on GitHub​

The onboarding flow​

What lands on disk​

Lifecycle​

Failure modes​

When you'd care about this as a developer​

Where to go next​