anthropics / anthropics/skills

Proposal: Add AI transparency metadata fields to SKILL.md specification

Open
#180 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
176k
Forks
20.9k
Avg merge
7h 21m
Merged PRs (30d)
5

Description

## Summary

The current SKILL.md specification only requires `name` and `description` fields. As AI-generated skills become more common—especially with tools like Claude Code's `skills-creator` skill —I propose adding optional metadata fields to support AI transparency and provenance tracking.

## Motivation

With the EU AI Act and increasing focus on AI transparency, users benefit from knowing:
- Whether a skill was AI-generated or human-authored
- Which AI model was used (if applicable)
- The reliability/testing status of the skill
- Who maintains the skill

This aligns with emerging AI transparency best practices and helps users make informed decisions about skill adoption.

## Proposed Fields

```yaml
---
name: skill-name
description: "What the skill does"
version: "1.0.0"

# Proposed AI transparency fields (optional)
status: tested | experimental | deprecated # Reliability indicator
author: "GitHub handle or name" # Human maintainer
generated_by: "Claude Opus 4.5" # AI model used (if applicable)
license: MIT # License for the skill
---
```

### Field Descriptions

| Field | Type | Description |
|-------|------|-------------|
| `status` | enum | `tested`, `experimental`, or `deprecated` - indicates reliability level |
| `author` | string | Human responsible for maintaining the skill |
| `generated_by` | string | AI model used to create/assist with the skill (omit if fully human-authored) |
| `license` | string | SPDX license identifier for the skill itself |

## Benefits

1. **Transparency**: Users know the provenance of skills they're adopting
2. **Trust**: `status` field helps users assess reliability
3. **Compliance**: Supports EU AI Act transparency requirements
4. **Discoverability**: Enables filtering by author, license, or AI-generated status
5. **Accountability**: Clear ownership for maintenance and issues

## Context: AI-Assisted Skill Creation

Claude Code includes a `/skills-creator` command that generates SKILL.md files using AI. As this and similar tools become more widely used, having standardized metadata to indicate AI involvement becomes increasingly important for:
- Distinguishing AI-generated from human-authored skills
- Tracking which AI model/version created the skill
- Enabling users to make informed trust decisions

## Implementation in Practice

I've implemented these fields in my skills repository: https://github.com/s-celles/ai-config

Example from a skill:
```yaml
---
name: license-advisor
description: "Expert assistant helping users choose licenses..."
version: "1.0.0"
status: tested
author: s-celles
generated_by: "Claude Opus 4.5"
license: MIT
---
```

Documentation: https://s-celles.github.io/ai-config/docs/ai-limitations/#ai-transparency-metadata-for-skills

## References

- [EU AI Act - Transparency Requirements](https://artificialintelligenceact.eu/)
- [NIST AI Risk Management Framework](https://www.nist.gov/itl/ai-risk-management-framework)

## Questions for Discussion

1. Should `generated_by` be a structured object (model name, version, date) or a simple string?
2. Should there be a `human_reviewed: true/false` field for AI-generated skills?
3. Should `skills-creator` automatically add these fields when generating skills?

I'd be happy to contribute a PR if this proposal is accepted.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.