The Open SkillTree Schema — Adoption Guide

SKILL.md is an open, portable format for skill data. If you have read the introduction, you know why it exists. This guide covers how to use it: exporting your data, validating files, extending the schema, and integrating it into real workflows.

What You Need

SKILL.md is just Markdown with YAML front matter. You need:

• A text editor
• Basic familiarity with YAML
• Git (optional, but recommended for versioning)

There is no proprietary software to install, no API key to request, and no vendor to depend on. That is the point.

Step 1: Export from SkillTree

The fastest way to get started is to export an existing SkillTree profile. Log in to your account, navigate to Settings, and click "Export SKILL.md." You will receive a file that looks like this:

---
name: "Alex Chen"
version: "1.0"
schema_url: "https://futurelabs.vip/schema/skill.md/v1"
last_updated: "2026-05-20"
---

# Skills

## Programming Languages
- **Python**: Expert (9/10)
  - Since: 2017
  - Projects:
    - https://github.com/alexc/ml-pipeline
    - https://github.com/alexc/data-api
- **TypeScript**: Advanced (7/10)
  - Since: 2020
  - Currently learning: false

## Frameworks & Libraries
- **React**: Expert
  - Prerequisites: [JavaScript, HTML, CSS]
  - Unlocks: [Next.js, React Native]
- **Next.js**: Advanced
  - Prerequisites: [React, Node.js]
- **FastAPI**: Advanced
  - Prerequisites: [Python]

## Domains
- **Backend Development**: Expert
- **Machine Learning**: Advanced
- **Human-AI Collaboration**: Intermediate

## Collaborations
- **AI Agent Projects**: 8
- **Human Teams**: 12
- **Trust Score**: 91/100

## Schema Extensions
- certifications: ["AWS Solutions Architect", "CKAD"]
- languages: ["English (fluent)", "Mandarin (native)"]
- availability: "open_to_collaboration"

Save this file as SKILL.md in your project root or personal website repository.

Step 2: Validate Your File

Invalid SKILL.md files break parsers. We provide a lightweight validator you can run locally or in CI.

Local Validation (Node.js)

# Install the validator
npm install -g @futurelabs/skill-md-validator

# Validate a file
skill-md validate ./SKILL.md

# Expected output:
# ✓ YAML front matter parsed
# ✓ Required fields present (name, version, skills)
# ✓ Skill levels are numeric or descriptive
# ✓ Prerequisites reference existing skills
# ✓ No circular dependencies detected

CI Integration (GitHub Actions)

# .github/workflows/validate-skill.yml
name: Validate SKILL.md

on:
  push:
    paths:
      - "SKILL.md"
  pull_request:
    paths:
      - "SKILL.md"

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install -g @futurelabs/skill-md-validator
      - run: skill-md validate ./SKILL.md

This ensures your skill data stays valid as you update it. Catching a broken prerequisite reference in CI is faster than debugging a failed parser in production.

Step 3: Extend the Schema

SKILL.md is intentionally minimal. The schema_extensions block lets you add custom fields without breaking compatibility.

Example: Adding Portfolio Links

## Schema Extensions
- portfolio: "https://alexchen.dev"
- speaking:
    - event: "React Conf 2025"
      talk: "Scaling Component Libraries"
      url: "https://youtube.com/..."
- publications:
    - title: "Observability for LLM Applications"
      venue: "ACM Queue"
      url: "https://queue.acm.org/..."

Example: Adding Verified Credentials

## Schema Extensions
- verifiable_credentials:
    - issuer: "coursera.org"
      course: "Machine Learning Specialization"
      completed: "2024-03-15"
      credential_url: "https://coursera.org/verify/..."
    - issuer: "aws.amazon.com"
      certification: "AWS Solutions Architect – Associate"
      earned: "2025-01-10"
      expires: "2028-01-10"

Extensions are key-value pairs. Consuming tools can ignore fields they do not recognize, which means your extended SKILL.md remains backward-compatible. This pattern is borrowed from W3C Verifiable Credentials, which uses the same extensibility model.

Step 4: Render on Your Site

A SKILL.md file sitting in a repo is useful. A rendered skill graph on your personal website is powerful. Here is a minimal React component that parses SKILL.md and renders a skill tree:

import { parseSkillMd } from "@futurelabs/skill-md-parser";
import SkillTree from "./SkillTree";

export default async function SkillsPage() {
  const skillData = await parseSkillMd(
    await fetch("/SKILL.md").then((r) => r.text())
  );

  return (
    <div>
      <h1>{skillData.name}</h1>
      <SkillTree skills={skillData.skills} />
    </div>
  );
}

The parser returns a typed JSON object that you can feed into any visualization library. We recommend D3.js for custom graphs or our own @futurelabs/skill-tree-react component for a drop-in solution.

Step 5: Integrate with Agents

The most forward-looking use case: making your skills discoverable by AI agents. Publish your SKILL.md at a well-known URL (e.g., https://yourdomain.com/SKILL.md) and agents can parse it without API keys or scraping.

# Agent discovers a human collaborator
GET https://alexchen.dev/SKILL.md

# Parses structured capabilities
# Matches against task requirements
# Initiates collaboration proposal

This is not science fiction. Early versions of this flow are already running in the SkillTree ecosystem, where agents parse public SKILL.md files to find humans with complementary expertise. The agent does not need access to LinkedIn. It just needs a URL.

Migration from Other Platforms

If you have skill data trapped in another platform, you can migrate it. We provide converters for common sources:

Converters are lossy. They give you a starting point, not a finished file. Plan to spend 15–30 minutes reviewing and editing the output.

Best Practices

After reviewing hundreds of SKILL.md files from early adopters, here are the patterns that separate useful files from decorative ones:

1. Be specific, not comprehensive. A file with 50 shallow skills is less useful than one with 15 deep ones. Focus on what you can actually do.
2. Link to proof. Every skill should have at least one project link, endorsement, or credential. Claims without evidence are noise.
3. Version your file. Use Git. Track how your skills evolve. A commit history is a career narrative.
4. Update quarterly. Skills atrophy and emerge. A SKILL.md from last year is a history document, not a current profile.
5. Validate before publishing. Run the validator in CI. A broken file reflects poorly on you and breaks parsers.

The Ecosystem

SKILL.md is gaining adoption beyond SkillTree. Community tools include:

• Obsidian plugin: Track skills as linked notes
• VS Code extension: Auto-complete skill names from the taxonomy
• Notion integration: Sync SKILL.md to a Notion database
• GitHub Action: Validate on every push

If you build something, let us know. We maintain a community ecosystem page and feature the best integrations.

Schema Versioning

SKILL.md is currently at version 1.0. When we release 2.0, we will provide migration guides and backward-compatible parsers. The schema evolves through open RFCs, not unilateral decisions. If you have a proposal, open an RFC.

Ready to adopt SKILL.md? Create your SkillTree profile for a one-click export, or read the full specification to hand-author your first file.