SharpAgent Skill Contract v1.0.0#

Foundation shovel — Generate, validate, and package all SharpAgent skills. Fusion of Ontology Schema + Skill Creator + Skill Oracle.

When to Use#

Use this skill when:

• Creating a new SharpAgent-compliant Skill from scratch
• Validating an existing Skill for contract compliance
• Packaging a Skill for ClawHub publication under SharpAgent
• Upgrading a legacy Skill to SharpAgent standards

What Is a Skill Contract#

Every SharpAgent Skill must declare a contract — a YAML block that states:

yaml

contract:
  name: sharpagent-five-factor-review
  version: "1.0.0"
  category: analysis
  trust_level: verified            # draft | verified | audited
  reads:
    - InformationSource
    - LearningEntry
  writes:
    - FiveFactorResult
  preconditions:
    - "Must have at least one InformationSource to analyze"
    - "Must have access to web_search or memory_search tool"
  postconditions:
    - "Output contains overall_confidence score (0-10)"
    - "Each of 5 factors has a value"
  calibration:
    default_mode: professional     # warm | professional | deep
    modes_supported: [warm, professional, deep]
  compliance:
    jurisdiction: global           # cn | us | eu | global
    safety_level: standard         # minimal | standard | strict
  lifecycle:
    status: active
    publish_as: SharpAgent

Workflow#

Step 1: Scaffold a New Skill#

bash

sharpagent scaffold --name sharpagent-five-factor-review --category analysis

Generates:

text

/sharpagent-skills/sharpagent-five-factor-review/
├── SKILL.md            # Contract + documentation
├── contract.yaml       # Machine-readable contract (auto-derived)
├── scripts/            # Runtime scripts (optional)
├── references/         # Supporting docs (optional)
└── test/               # Validation tests (optional)

Step 2: Validate Contract#

bash

sharpagent validate --path ./sharpagent-five-factor-review/SKILL.md

Checks:

• Structural: All required YAML fields present
• Semantic: reads/writes match known ontology types
• Integrity: preconditions reference real capabilities
• Naming: snake_case, no spaces, max 40 chars

json

{
  "valid": true,
  "warnings": [],
  "errors": [],
  "score": 100,
  "missing_optional": ["scripts/ directory missing"]
}

Step 3: Package for Publication#

bash

sharpagent package --name sharpagent-five-factor-review --output ./dist/

Produces:

text

./dist/sharpagent-five-factor-review.tar.gz
├── SKILL.md
├── contract.yaml
├── scripts/
└── references/

Contract YAML Schema Reference#

Top-Level Fields#

FieldTypeRequiredDefaultcontract.namestring✅-contract.versionsemver✅"0.0.1"contract.categoryenum✅-contract.trust_levelenum✅"draft"contract.readsstring[]✅[]contract.writesstring[]✅[]contract.preconditionsstring[]✅[]contract.postconditionsstring[]❌[]contract.calibrationobject✅defaultcontract.complianceobject✅defaultcontract.lifecycleobject✅default

Contract Categories#

CategoryDescriptionExample SkillsanalysisAnalyzes input, produces structured outputFive-factor reviewworkflowMulti-step process with gatesEngineering lifecyclemonitorPeriodic scanning and alertingIntelligence briefingmemoryStorage, retrieval, consolidationMemory managementscaffoldCode/file generationSkill creationintegrationExternal service bridgingAPI clients

Trust Levels#

LevelMeaningWhendraftWork in progress, unverifiedInitial creationverifiedContract structure validatedAfter validationauditedFull five-factor trust audit passedCommunity verified

Calibration Modes#

yaml

calibration:
  default_mode: professional
  modes_supported: [warm, professional, deep]

ModeWarmProfessionalDeepToneFriendly, supportiveNeutral, preciseAnalytical, detailedDetailConciseBalancedExhaustiveUse caseUser-facingInternal reportsResearch analysis

Integration Points#

With Five-Factor Review#

• writes: [FiveFactorResult] → Contract schema is consumed by the five-factor review skill
• Contract trust_level is validated using FiveFactorResult as part of skill audit

With Calibration Framework#

• contract.calibration block defines which modes are supported
• At runtime, the calibration engine checks contract.calibration.modes_supported

With Content Safety Engine#

• contract.compliance block sets safety policies
• safety_level: standard is the minimum for ClawHub publication

Quality Gates#

CheckWhatFail actionSchema validAll required YAML fields presentBlock packagingType consistencyreads/writes reference known typesWarnNaming conventionsnake_case, ≤40 charsWarnCalibration declaredAt least default_mode setWarnPreconditions non-emptypreconditions list ≥1 itemWarnVersion formatvalid semverBlock packaging

Edge Cases#

SituationActionNo reads (standalone)Allow with warningreads = writesWarn (likely mistake)Type cross-reference failsWarn + list unknown typesCalibration missingSet default: professional + standardDraft trust_levelAllow creation, warn on packagingSKILL.md has no contract blockFail validation

Dependencies#

• YAML parser (for reading contract blocks)
• jq or Python 3 (for validation scripts)
• tar (for packaging)

Version History#

• v1.0.0 — Initial release. Skill Contract scaffolding + validation + packaging.

---

SharpAgent · MIT-0 · 2026-05-11