⚓ Skill Standards

Skill Harbor enforces a standardized anatomy for AI agent skills to ensure they are platform-agnostic, auditable, and ready for automated chaining. By following these standards, your skills are "Harbor Certified" and can be precision-engineered by the up command for various environments.

Every skill is a combination of strategic markdown headers and optional metadata that define its purpose, constraints, and operational boundaries.

🌍 The Value of Portability

File-based skills using the SKILL.md standard can improve performance across diverse commercial agent harnesses (including Claude Code, Gemini, and Codex) when they are well-authored and well-curated. By utilizing Skill Harbor as the middle layer, your team can manage and distribute skills universally while avoiding proprietary vendor lock-in.

🏗️ Skill Structure (Anatomy)

Standardization is the key to deterministic agent behavior. Each SKILL.md file should include the following structural elements.

1. Strategic Headers

These headers provide the core logic that agents use to understand their tools.

🤝 Semantic Contracts (I/O)

To safely chain skills together, Harbor monitors Engagements via input/output contracts. You can define contracts in two ways.

Method 1: Frontmatter (Recommended)

Place a contracts block directly inside your skill's YAML frontmatter:

---
name: fetch-logs
description: Fetches application logs from AWS Cloudwatch
contracts:
  requires:
    aws_region: string
    service_name: string
  produces:
    log_stream: json array
---

Method 2: Markdown Sections

Use ## Requires and ## Produces headers with an unordered list of code-ticked variable names:

## Requires
- `project_root`: path
- `target_file`: path

## Produces
- `refactor_log`: json
- `new_component`: string

Validation Rules

Contracts now participate in the default command model like this:

• skill-harbor check validates contract structure by default.
• skill-harbor check --strict escalates missing or underspecified contracts more aggressively.
• skill-harbor fathom surfaces contract health as part of normal fleet analysis.
• skill-harbor fathom --contracts acts as a stricter / more focused contract-audit mode during the migration period.

That means:

• Missing Standards: If no contracts frontmatter or ## Requires/## Produces sections are found, the skill is surfaced as a warning by default.
• Malformed Structure: If contract sections are malformed or declared types are invalid, check should fail.
• Missing Inputs: If a skill requires a variable that no other skill produces, Fathom raises a Warning (the input may come from the user prompt).
• Type Mismatches: If Skill A produces user_id as integer but Skill B requires it as string, Fathom can treat that as a fleet health problem and fail report gating.

Customization

You can change the header names to fit your team's nomenclature via profiler.yaml:

# profiler.yaml
contracts:
  requiresHeader: "Inputs"
  producesHeader: "Outputs"

🚢 Ship Classes (Displacement)

We classify the scale of a skill by its Token Displacement to ensure the fleet remains light and efficient.

🛠️ Management & Control

While the Skill Standard defines the content of a skill, the Manifest & .harbor Folder defines how that skill is tracked, versioned, and delivered to your agent fleet.

Reference: Li, X., et al. (2026). SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks. https://www.skillsbench.ai/skillsbench.pdf

For the broader alignment story, see How does Skill Harbor align with SkillsBench?.