Publish your AI resources

Your team keeps skills, agents, rules and runbooks in a Git repository. You declare the folders in the catalog-info.yaml of that repository, and Astrolabe lists each resource on the AI resources page and on a tab of the repository.

The plugin must be on first: see Turn on AI resources.

📚 The four kinds of resource

Kind	What it is	Annotation	What Astrolabe recognizes under the path
Skill	A folder of instructions an AI tool loads when it needs it	astrolabe.forgeit.tech/ai-skills-path	Each folder that contains a SKILL.md
Agent	A sub-agent or persona	astrolabe.forgeit.tech/ai-agents-path	Each *.md file that starts with a name and a description (front matter), and each *.agent.md file
Rule	The instructions given to every session	astrolabe.forgeit.tech/ai-rules-path	AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, *.mdc, *.instructions.md and the *.md of .claude/rules
Runbook	A procedure to follow, for a person or an assistant	astrolabe.forgeit.tech/ai-runbooks-path	Each *.md file

🗂️ Where to put the files in the repository

A value is a path from the root of the repository: a folder or a file. Put several paths on one line, separated by commas.

acme-ai-kit/
├── catalog-info.yaml
├── AGENTS.md
├── skills/
│   └── code-review/
│       └── SKILL.md
├── .claude/
│   └── agents/
│       └── test-writer.md
├── .cursor/
│   └── rules/
│       └── typescript.mdc
└── runbooks/
    └── rotate-a-token.md

🚀 Declare the repository

1. Open the catalog-info.yaml at the root of the repository.

2. Add the annotations of the kinds you publish, under metadata.annotations. Keep only the lines you use.

   apiVersion: backstage.io/v1alpha1
   kind: Component
   metadata:
     name: acme-ai-kit
     description: Skills, agents and rules shared by the platform team
     tags: [ai, platform]
     annotations:
       astrolabe.forgeit.tech/ai-skills-path: skills, .claude/skills
       astrolabe.forgeit.tech/ai-agents-path: .claude/agents
       astrolabe.forgeit.tech/ai-rules-path: AGENTS.md, .cursor/rules
       astrolabe.forgeit.tech/ai-runbooks-path: runbooks
   spec:
     type: library
     lifecycle: production
     owner: group:default/platform-team

   Field	What to enter	Example
   metadata.name	The name of the repository's component	acme-ai-kit
   metadata.tags	Words people search for. Every resource gets them	[ai, platform]
   spec.owner	The group that owns the repository. Every resource gets this owner	group:default/platform-team
   spec.lifecycle	experimental, production or deprecated. Every resource gets it	production

3. Commit the file and push it to the default branch.

4. If the repository is not in the catalog yet, register it: see Register a component.

tip

A component without any astrolabe.forgeit.tech/ai-… annotation is never read.

✨ Start from the template instead

The template creates a repository with one example of each kind and the annotations already written.

1. In the left sidebar, click The Foundry.

2. On the card AI resources repository, click Choose.

3. In the step The repository, fill in:

   Field	What to write	Example
   Name	Lowercase letters, digits and hyphens. It names the repository and the component	acme-ai-kit
   Description	What the resources of this repository are for	Skills and agents of the platform team
   Owner	The team that answers for these resources. Click the field and pick one	platform-team
   Kinds of resources	Tick Skills, Agents, Rules (AGENTS.md), Runbooks: one folder and one example for each kind you tick	all four

4. Click Next.

5. In the step Where to create it, pick the Host, then fill in Owner (the organization or user of the new repository) and Repository (its name).

6. Click Review, check your answers, then click Create.

Not verified on an instance yet: the creation itself, which needs a GitHub host the instance can write to.

✅ Check that it worked

1. In the left sidebar, click Catalog, then click the component of the repository.

2. Click the tab AI resources. It shows the state of the reading (Read), the commit, and the resources found, for example 2 skills and 1 agent.

3. Click Read the repository again. The message Reading of the repository started. appears at the bottom of the screen, then Repository read again: 3 resources.

4. In the left sidebar, click AI resources: each resource is a card, with the owner of the repository.

✅ That's it!

Next: Find and install an AI resource.

❓ Frequently asked questions

Can I put several kinds in the same folder? Each path belongs to one kind. A SKILL.md found under ai-rules-path is not published as a rule: Astrolabe tells you to add its folder to ai-skills-path.

Where do the owner and the lifecycle of a resource come from? From the repository's catalog-info.yaml (spec.owner, spec.lifecycle), never from the file of the resource.

Does Astrolabe run my scripts? No. See the FAQ.

How do I remove a resource? Delete it from the repository, or remove the annotation. It disappears at the next reading.

Where do I see what is wrong with my repository? On the tab AI resources of the component, under Problems: see Troubleshooting.