[RFC]: Skillware tiered architecture — soft skills, hard skills, and ultimate skills

[rosspeili]

Summary

Propose a formal tiered skill architecture for Skillware that distinguishes between three classes of skills based on implementation complexity, dependency requirements, and deployment context.

Motivation

As the Skillware registry grows, a single flat skill standard is increasingly difficult to apply uniformly. A prompt-based reasoning skill has fundamentally different requirements than a skill that calls external APIs or runs cloud-only enterprise pipelines. The current standard conflates these cases, leading to inconsistency in manifests, documentation, and contributor expectations.

A tiered architecture would:

• Set clear expectations for contributors about what level of complexity their skill represents.
• Allow the loader and documentation to handle each tier differently where appropriate.
• Create a natural progression from simple to advanced skills that mirrors how the ecosystem can grow.

Detailed Design

Tier 1 — Soft Skills (Anyone can contribute)

Prompt-based skills with no external dependencies. The skill's logic lives entirely in instructions.md. There is no skill.py or only a trivial passthrough implementation. These are analogous to the skills.md by Anthropic, Google, etc.

• No external API calls.
• No additional Python dependencies beyond the core framework.
• Can be run with any supported LLM provider without configuration.
• Suitable for contribution by anyone familiar with prompt engineering.

Tier 2 — Hard Skills (Anyone can contribute)

The current Skillware standard. A full implementation in skill.py with a manifest.yaml, card.json, and instructions.md. May call external APIs. Requires standard Python dependencies. Runs locally with appropriate environment variable configuration.

• May have external dependencies declared in the manifest.
• Requires environment variable configuration for API keys.
• Tested with the standard CI pipeline.

Tier 3 — Ultimate Skills (ARPA Core Enterprise Solutions Devs Only)

Enterprise-grade skills that may require cloud infrastructure, paid API access, proprietary data sources, or managed deployment. Not intended for local self-hosting without configuration.

• May require cloud provider credentials or KMS integration.
• May depend on private or paid data sources.
• Documentation directs users to contact the maintainers for deployment support.
• Not expected to pass the standard CI suite without additional configuration.

Proposed manifest change

skill_tier: soft | hard | ultimate

### Open questions
- Should tier be enforced by CI or only by convention?
- Should soft skills have their own directory separate from skills/?
- Should the registry surface tier information on skillware.site?
- Other?

### Drawbacks

- Adds complexity to the manifest schema and documentation.
- The line between tiers may be subjective in some cases.