Agent Skills, working: a guide with 6 real Atlassian examples

Your coding agent just made up an API again

Your agent just confidently wrote a Forge manifest with a jira:workflowValidator module that doesn't compile, paginated /rest/api/3/search with startAt (which Atlassian removed in August 2025), and edited a Confluence page without bumping version.number — silent 409 forever. None of these are obscure. All three are common knowledge in the heads of Atlassian developers, and missing knowledge in every coding agent shipped today.

This isn't a model-quality problem. It's a knowledge-loading problem. And it's exactly what Agent Skills were built to fix.

This tutorial covers the mechanics — how skills load, how to write one, how to install one — and uses six open-source skills we maintain at LeanZero as the worked examples. By the end, your agent will know the things it should already know.

Why pasting docs into the prompt doesn't work

The instinct, when an agent hallucinates, is to paste more documentation into the system prompt. This works for one task and breaks every other:

Token bloat. Every token in the system prompt is paid for on every turn, for the whole session. The Confluence REST API reference alone is ~80,000 tokens. Multiply by the four other Atlassian surfaces and you've burned a whole context window before the user has said anything.

Context dilution. Long system prompts measurably reduce instruction-following. The agent stops attending to your actual task instructions because they're buried.

No selection. Even if you could paste it all, the agent reads the entire thing every time. You're paying full price for the JQL section while editing a Confluence page.

The other workarounds have their own problems. RAG retrieves relevant chunks, but the agent still has to reason about which chunk applies — and you're back to hallucinations when the retrieval is fuzzy. Fine-tuning bakes knowledge into weights, which is expensive, slow to update, and locks you to one model.

What a Skill actually is

From Anthropic's official docs:

Skills are reusable, filesystem-based resources that provide Claude with domain-specific expertise: workflows, context, and best practices that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), Skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations.

A Skill is a directory on disk with a SKILL.md file at its root. That SKILL.md has YAML frontmatter (a name and a description) and a markdown body with instructions. The directory can also contain supporting files: reference docs, templates, scripts the agent can execute via bash.

The mental model from the docs is good: Skills are onboarding materials for a new team member. You wouldn't paste your entire engineering wiki into a new hire's onboarding doc. You'd give them a map: "here's the Forge module reference, here's the JQL gotchas list, here's how we structure migration scripts." The new hire reads the relevant page when they need it.

That's exactly what an agent does with a skill.

The minimum viable SKILL.md

---
name: my-skill-name
description: "Brief description of what this skill does and when Claude should use it."
--- 
# My Skill

## Instructions
Step-by-step guidance for the agent here.

## Examples
Concrete examples here.

That's the whole format. Two required fields in the frontmatter, free-form markdown below. The format is an open standard at agentskills.io — the same SKILL.md works in Claude Code, Cline, Qwen Code, and any other agent that implements the spec.

Progressive disclosure — the trick that makes skills cheap

Here's the part that turns "another way to load context" into something genuinely new.

A skill loads in three levels, each at a different time:

This is progressive disclosure, and it's the architectural decision that makes skills work.

At startup, your agent loads the descriptions of every installed skill — about 100 tokens each. You can install 50 skills for ~5,000 tokens, and the agent now knows it has a skill for Forge manifests, a skill for JQL, a skill for migrations, and 47 others. But none of their bodies are loaded yet.

When you ask "write me a Forge workflow validator," the agent matches your request to the atlassian-jira-forge-skill description, reads that one skill's body into context via bash, and proceeds. The other 49 stay on disk, costing nothing.

When the Forge skill references forge-manifest-reference.md, the agent reads that one file — and only that file. The bundled scripts in the same directory? Their source code never enters context. The agent just runs them and reads the output.

The practical consequence: you can ship a skill with 50,000 words of reference material and the agent pays nothing for it until the moment it's needed. This is impossible with a system prompt and clumsy with RAG. With skills, it's the default.

How a skill gets triggered

Two ways: automatically (the agent decides) or manually (you decide).

Auto-trigger via description

Every skill's description is always in the agent's context. When you make a request, the agent matches your intent against those descriptions and loads the most relevant skill. This is why the description field is the most important line in your SKILL.md.

A bad description:

description: Helps with Atlassian stuff.

A good description (this is one of ours, verbatim):

description: Scaffold idempotent, resumable Atlassian migration scripts in Node.js — Data Center to Cloud or Cloud to Cloud — using the Plan/Sync/Audit triad, native-https clients with 429/5xx retry, post-JCMA ID mapping, identity resolution, seeded-sample audits with CSV spot-check outputs, and Forge KVS remote app-data mending. Use when migrating Jira issues or Confluence pages in bulk, mending Forge app data after JCMA, backfilling custom fields, security levels, or content properties, rewriting macros at scale, fixing broken filter JQL after a tenant move, or building any two-phase Atlassian sync job with audit verification and human-reviewable CSVs.

The first half says what the skill does. The second half says when to use it — with concrete trigger phrases like "after JCMA," "broken filter JQL," "bulk-mutate." The agent matches those phrases against the user's request and decides whether to load.

Constraint: the description has a 1,024-character cap (Claude API) and gets truncated at 1,536 characters in the skill listing (Claude Code). Put the key use case first.

Manual invocation via /skill-name

You can also trigger a skill directly. In Claude Code, type:

/atlassian-migration-scripts-skill

…and the skill loads regardless of whether the agent thought it was relevant. Useful when you know exactly what you need and don't want to waste a turn on the agent's auto-selection.

You can also pre-empt auto-loading entirely with disable-model-invocation: true in the frontmatter — useful for skills with side effects like /deploy or /commit where you don't want the agent deciding for you.

Installing a skill in Claude Code

Claude Code reads skills from three locations:

LocationPathScope*Personal~/.claude/skills/<skill-name>/SKILL.mdAll your projectsProject.claude/skills/<skill-name>/SKILL.mdOne repo (commit to share with team)Plugin*<plugin>/skills/<skill-name>/SKILL.mdBundled with a plugin

If you put a skill at all three levels with the same name, project wins over personal wins over plugin.

To install our six Atlassian skills:

git clone https://github.com/leanzero-srl/leanzero-forge-skills
cd leanzero-forge-skills
./scripts/install-skills.sh

The install script symlinks each skill into ~/.claude/skills/ so updates are pulled with git pull. Same script works for Cline and Qwen Code — pass --target=cline or --target=qwen.

Six worked examples — the leanzero-forge-skills set

We forged these against two production Atlassian apps over 18 months (CogniRunner and Sentinel Vault, both on the Atlassian Marketplace). Each one closes a specific class of hallucination we caught coding agents committing — repeatedly, on real tasks.

The full set lives at github.com/leanzero-srl/leanzero-forge-skills. Below, one paragraph each on what they teach an agent.

1. atlassian-jira-forge-skill

For Forge code running inside Jira. Teaches the workflow trio (workflowValidator, workflowCondition, workflowPostFunction) — the doc that finally kills the long-stale myth that workflow validators are Connect-only. Includes async-event handlers with timeoutSeconds: 900 to escape Forge's 25-second function ceiling, KVS sharding patterns for hot keys lifted from a real PPM app, and capability-token webtriggers done right (public HTTPS endpoints with bearer auth). 16 templates, 30 docs.

1. atlassian-confluence-forge-skill

The Confluence counterpart. pageBanner, contentAction, contextMenu, custom content, macros. The headliner is ADF tree surgery — patterns for idempotent edits to Confluence's Atlas Document Format JSON without breaking pages. Also includes the three-level Confluence authorization model (requestConfluence in the bridge, asApp vs asUser in resolvers) which is the #1 source of mysterious 401s. And the GET → bump version.number → PUT dance that kills the silent 409 Conflict cycle on every page update. 14 templates, 30 docs.

1. atlassian-organizations-api-skill

The cross-product admin surface at api.atlassian.com/admin — orgs, users, groups, audit events, SAML/MFA policies, DLP, API tokens. Four sub-APIs covered with their distinct auth boundaries (the Bearer-only-on-DLP/Admin-Control gotcha that silently breaks OAuth integrations is the kind of thing nobody tells you until you've burned an afternoon on it). Cursor-paginated audit-event polling for what is reliably the strictest rate-limited Atlassian surface. 5 templates, 14 docs.

1. jira-api-skill

External Node, Python, or CI services calling Jira Cloud over HTTPS. The big one here: POST /rest/api/3/search/jql with nextPageToken. The old startAt-based pagination is gone as of August 2025, and most agents still write it. The skill also covers OAuth 2.0 3LO end-to-end (authorize → token exchange → /accessible-resources → gateway calls), ADF construction for descriptions and comments (it's a JSON tree, not Markdown), and a hard "no, you cannot sign your own JWT for Cloud REST" disclaimer for anyone half-remembering Connect. 4 templates, 10 docs.

1. confluence-api-skill

External services calling Confluence Cloud — v2 pages with ADF, the same GET → bump → PUT version dance (this one bites you twice if you don't have it), v1 fallback for CQL search. v2 cursor pagination for /spaces and /pages with the actually-working ?cursor= shape. The note that body.atlas_doc_format.value is stringified JSON (you have to JSON.parse before traversing) — agents miss this every time. 5 templates, 10 docs.

1. atlassian-migration-scripts-skill

The newest of the six. Idempotent, resumable Atlassian migration scripts using the Plan→Sync→Audit triad: plan-script discovers, sync-script applies, audit-script verifies. Two-gate safety (--dry-run for preview, --confirm for the real thing) means you can't accidentally mutate the wrong tenant. Built for the work nobody plans for — post-JCMA cleanup, Cloud-to-Cloud tenant consolidation, rewriting broken filter JQL after IDs shift, mending Forge KVS app data from outside the app. 29 templates, 21 docs.

Writing your own skill

The fastest path is to crib from one of ours and replace the body. The pattern:

Pick something specific. Skills are for one thing done well, not "everything about Jira." Each of our six closes a defined boundary (Forge vs REST, Jira vs Confluence, runtime vs migration).

Write the description first. What does it do? When should the agent use it? Read it aloud — if it sounds vague, it'll trigger on the wrong tasks or fail to trigger on the right ones.

Keep **SKILL.md** under 500 lines. Move detailed reference into supporting files in the same directory. The skill body should be a map; the reference is the territory.

Test by asking, not invoking. Don't type /your-skill — ask the question your skill is supposed to answer and see if the agent picks it up. If it doesn't, your description is wrong.

Ship it. Drop it in ~/.claude/skills/ and use it. The feedback loop is short.

A minimum viable skill, end-to-end:

mkdir -p ~/.claude/skills/my-skill

---
name: my-skill
description: Does X for the user. Use when the user mentions X, Y, or Z. ---

# My Skill

## Instructions
1. Do this.
2. Then do that.

## Examples
Concrete example here.

That's it. Restart Claude Code (or wait — it auto-detects new skills), and you're done.

2: A note on security

The official docs put this in a warning box and we'll echo it: only install skills from sources you trust. A skill can give the agent new bash commands to run and new tools to invoke; a malicious skill is functionally indistinguishable from any other piece of executable code on your machine. Treat skill installation like installing a package.

Our leanzero-forge-skills repo is MIT-licensed, public, and audit-friendly — every skill is a flat directory of markdown and .js templates with no install-time scripts. Read what you install.

TL;DR

If you've ever lost an afternoon to an agent confidently producing JQL that 400s, a Forge manifest that doesn't compile, or a Confluence edit that silently 409s — that's the friction skills exist to remove. The six above remove it for Atlassian. Write your own for whatever framework keeps tripping yours up.

Sources cited in this tutorial

https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

https://code.claude.com/docs/en/skills

https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

https://agentskills.io

https://github.com/leanzero-srl/leanzero-forge-skills