Skip to content

Write skills and agents ​

Skills, agents, and prompts are only Markdown and configuration, so they are the easiest resources to write and review. This page takes you from scaffolding to submitting to Tara.

First, install Phillip and sign in to Tara. To submit a resource to the official catalog or to your organization's private store, you need to be a Member or above in the organization (the Viewer role can't submit). The store you pick decides who approves: an Admin or Owner of the organization approves a submission to its private store, and PhillipCLI platform staff review the official catalog. Community resources need no approval, because Tara scans them automatically.

Which type should you choose? ​

Choose a skill to give the agent knowledge or a procedure it applies on its own. Choose a prompt to create a named command that users invoke by hand. Choose an agent to assign a distinct role, such as BA, Dev, or code review, with its own instructions and a limited set of tools.

Directory layout ​

A skill named skill-api-spec has this layout.

text
skill-api-spec/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── api-spec/
│       ├── SKILL.md
│       └── reference/
│           └── template.md
├── README.md
└── CHANGELOG.md

An agent named agent-reviewer looks like this.

text
agent-reviewer/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   └── reviewer.md
├── README.md
└── CHANGELOG.md

A prompt has the same layout as a skill. Put it under skills/<name>/SKILL.md and invoke it with /prompt-<name>:<command>.

README.md and CHANGELOG.md are required. Don't put a CLAUDE.md at the package root, because Claude Code doesn't load it. Put that content in a skill, or in a harness if it's a shared convention. The directory name must match name in plugin.json.

Scaffold from a template ​

bash
ph tara new skill skill-api-spec --org acme --description "Write API specifications to our standard"

This command creates the layout above, with org set to your organization (acme here). To create a community resource, use --personal instead of --org. You can also use the wizard in the Portal (the Contribute section, then Create resource) and edit the files in the browser.

Write plugin.json ​

json
{
  "name": "skill-api-spec",
  "displayName": "API specification",
  "version": "1.0.0",
  "description": "Write API specifications to our standard",
  "author": { "name": "Platform team" },
  "license": "UNLICENSED",
  "keywords": ["api", "spec"],
  "metadata": {
    "forge": {
      "schema": 1,
      "type": "skill",
      "org": "acme",
      "owners": ["owner@example.com"],
      "roles": ["BA", "SA", "Dev"],
      "engines": ["claude-code"],
      "status": "active"
    }
  }
}

On Tara, version, description, and author.name are required, even though Claude Code treats them as optional. owners lists the emails of the people responsible for maintenance. All fields are in Resource format.

If an agent needs another skill, declare a dependency. Use ~ or ^ instead of leaving the range empty.

json
"dependencies": [
  { "name": "skill-api-spec", "version": "^1.0" }
]

A dependency must be a resource already released on Tara, and an official resource can depend only on official resources.

Write the content ​

Skill ​

SKILL.md has a YAML header followed by the instructions.

markdown
---
name: api-spec
description: Write an API specification from requirements. Use when the user needs to describe endpoints, parameters, and error codes.
---

Write the specification using the template in `reference/template.md`.

## Steps

1. List the endpoints and methods.
2. Describe the parameters, results, and error codes.
3. Give an example request and response.

Claude reads description to decide when to load the skill, so state clearly when to use it. For long content, split it into files under reference/ so the skill loads them only when needed.

Prompt ​

To make a prompt callable only by users, add disable-model-invocation: true to the header. Add argument-hint to suggest arguments.

Agent ​

markdown
---
name: reviewer
description: Review code changes against a checklist. Use when you need to read a diff before merging.
tools: Read, Grep, Glob, Bash(git diff:*)
---

You are a reviewer. Read the diff, compare it against the checklist, and report issues with the code line.

## Limits

Don't edit files. Don't put secrets in the output.

Limit tools. Tara warns you when it finds unrestricted Bash or WebFetch, or permissionMode: bypassPermissions. If you really need them, explain why in the ## Permissions section of the README.

A few tips. Make each resource do one thing. Keep information in one place and have other places refer to it by code instead of copying it. Tell the agent to ask when important information is missing.

Write CHANGELOG.md ​

Each version must have a ## <version> section.

markdown
# Changelog

## 1.0.0 - 2026-11-01

- First version.

If the section for the version you submit is missing, the check reports an error. Phillip also uses this section to notify users of a new version.

Check and submit ​

bash
ph tara check ./skill-api-spec
ph tara publish ./skill-api-spec
ph tara status skill-api-spec@1.0.0

check runs the same rules as Tara without saving anything, so fix every error line before you submit. publish submits the version. Without options it goes to your personal store; --org acme (or metadata.forge.org: acme) publishes to your organization if its publish policy allows you. Tara scans the package and releases it at once if nothing blocks it. Only org: aiforge waits for approval by platform staff. status shows the state, the check results, and the reason if the submission was blocked or returned.

If a submission is blocked or returned, pull the code, fix it, and submit a new version.

bash
ph tara pull skill-api-spec@1.0.0 --dir ./skill-api-spec
ph tara bump ./skill-api-spec 1.0.1 --changelog "Fix template missing error codes"
ph tara publish ./skill-api-spec

The criteria used for approval are in Review criteria. For how to choose a version number, see Versioning rules.

Further reading ​