Agent Skills Index

An Agent Skills index is a publisher-maintained catalog of reusable Agent Skills. It can help people and compatible agent runtimes understand which packages exist, what tasks they support, and where to install them.

The phrase “skills index” is useful documentation language, but it is not a universal web standard. The open Agent Skills specification standardizes an individual skill directory with a required SKILL.md; it does not define a mandatory /.well-known/agent-skills URL or one link relation that every crawler follows.

What A Skill Package Contains

At minimum, a skill is a directory containing SKILL.md with YAML frontmatter and Markdown instructions:

site-audit/
├── SKILL.md
├── scripts/       # optional executable helpers
├── references/    # optional detailed documentation
└── assets/        # optional templates or resources

The required frontmatter fields are name and description. The description should explain both what the skill does and when it applies because compatible clients can use that metadata to decide whether to load the full instructions.

Optional fields and folders add licensing, compatibility notes, scripts, detailed references, and reusable assets. They do not remove the need for normal permission checks or reliable product documentation.

What A Useful Catalog Should Show

Field	Why it matters
Skill name	Matches the package directory and required metadata
Supported outcome	Describes the user task, not a vague department
Inputs	Makes required URLs, files, or account context explicit
Read/write behavior	Signals whether the workflow changes state
Authentication	Explains what access is required without exposing secrets
Compatible runtime	Prevents unsupported-client claims
Package URL and version	Lets users install and review the exact artifact
Owner and review date	Makes maintenance responsibility visible

Only list packages that actually exist and can be tested. A catalog full of proposed capabilities is marketing copy, not an operational index.

Skill Versus API, MCP, And A2A

• Agent Skill: reusable instructions and supporting materials for a compatible runtime.
• OpenAPI description: a machine-readable contract for HTTP operations.
• MCP server: live tools and resources exposed through MCP.
• A2A Agent Card: metadata for an A2A server that accepts agent-to-agent interactions.
• Human documentation: the source people use to understand behavior, policies, and support.

A skill can call an API or MCP tool and can explain when to contact an A2A agent. It does not replace those interfaces.

Publishing Workflow

1. Choose one bounded user outcome that already works.
2. Write a specific activation description with inputs and limits.
3. Keep core instructions concise; move depth into focused references.
4. Declare side effects, authentication, dependencies, and approval gates.
5. Validate package structure with the official reference tooling.
6. Test the skill in every runtime you claim to support.
7. Publish the package and catalog page with an owner and review date.

Never embed credentials, private endpoints, customer data, or hidden administrative instructions in a public package.

SEO And Discovery Limits

Publishing a skill does not make a page indexable, improve rankings, or guarantee adoption by search or answer engines. Keep the catalog crawlable for human discovery, link it from relevant product documentation, and use ordinary technical SEO practices.

For the implementation guide, see Agent Skills Index: How Websites Expose Reusable Capabilities. Related concepts include API Catalog SEO, MCP Server Card, and A2A Agent Card.

Validation Checklist

• Every catalog item points to a real package.
• Directory name and name metadata match.
• Descriptions state the task and activation conditions.
• Scripts document dependencies and failure behavior.
• Side effects and required approvals are explicit.
• Compatibility claims were tested in the named runtime.
• The owner and review date are current.

Primary Sources

• Agent Skills specification
• How to add skills support to an agent
• Agent Skills best practices