Creating Your First Skill

Skills are reusable folders that teach Cosine how to handle a specific kind of task better. A good skill gives the agent extra instructions, supporting context, and small reusable tools it can pull in when they are relevant.

This idea is bigger than Cosine itself. Agent Skills are an open standard, originally developed by Anthropic and now used across many agent products. In practice, that means a skill is a portable package of instructions, scripts, and references that helps an agent do specialised work more reliably.

If you want the broader background, see Agent Skills and the Agent Skills specification.

In one sentence

A good skill is a small reusable workflow: clear trigger, clear steps, clear output, and just enough supporting material to help the agent succeed without loading unnecessary context.

Quick checklist before you write one

Use this as a fast gut check:

Is the job repeatable?
Can you describe when it should trigger in one sentence?
Do you know what the output should look like?
Would a small script remove boring or error-prone steps?
Can you test it with two or three real prompts today?

What a skill actually is

At minimum, a skill is a folder containing a SKILL.md file. That file includes:

a name
a description
the instructions the agent should follow when the skill is active

Many skills also include supporting files:

.agents/skills/release-notes/
├── SKILL.md
├── references/
│   └── style-guide.md
└── scripts/
    └── collect_commits.py

The description is usually the most important field. It should explain both what the skill does and when it should be used. If it is vague, the skill will not trigger reliably.

If you have already used agent.md, the difference is simple:

agent.md gives broad, always-on guidance for a repo or workspace
a skill is a task-specific package that is loaded when needed

Use agent.md for general rules like coding style, testing expectations, or team norms. Use a skill when you want the agent to follow a repeatable workflow for one class of tasks.

Where skills live in Cosine

There are two scopes worth knowing about.

1. Project or repo-scoped skills

Project installs and repo-shared skills are the same project-scoped idea.

Cosine can find project-scoped skills in two forms:

a managed project install created by cos skills add --project
a repo-native .agents/skills/ directory committed with the codebase

The managed install lives under:

~/.cosine/projects/<project-id>/skills/

The repo-native form lives in:

.agents/skills/

In both cases, the skill belongs to that project rather than to your whole machine. The practical difference is that .agents/skills/ lives in the repository itself, so it is the version you can review in Git and share with teammates by committing it.

This is the right scope for skills that depend on repo architecture, internal conventions, or team workflows.

2. Private skills in ~/.cosine/skills/

Use ~/.cosine/skills/ for personal skills.

these are private to your machine and user account
they are available across all of your local Cosine sessions
they are not shared with your team unless you copy them into a repo

This is a good place for personal writing helpers, private research workflows, or habits you want available everywhere.

The easiest way to create your first skill

We recommend starting with Anthropic’s skill-creator skill:

cos skills add https://github.com/anthropics/skills --skill skill-creator

That helper is built specifically for creating and improving skills. It can help you:

shape the idea for a new skill
draft SKILL.md
come up with realistic test prompts
improve the description so the skill triggers more reliably

Once it is installed, you can invoke it explicitly in a prompt with $skill-creator if you want to make sure Cosine uses it.

Here are some of the team’s favourite skills

If you want examples of what “good” looks like in practice, these are five strong skills from this repo:

1. `axiom-logs`

Why the team likes it: It turns production log investigation into a repeatable workflow instead of a vague “go search the logs” prompt.
What makes it strong: It includes the real dataset name, field names, quoting rules, ready-to-run query patterns, and troubleshooting advice.
Good pattern to copy: If a workflow has sharp edges, document the exact edge cases inside the skill.

2. `cli2-changelog`

Why the team likes it: It converts a messy release-notes task into a deterministic collection step plus a clear writing step.
What makes it strong: It pairs SKILL.md guidance with a concrete helper script in scripts/get_commits.py.
Good pattern to copy: Automate the repetitive data gathering and keep the judgment-heavy writing instructions in the skill.

3. `cos2-tmux-controller`

Why the team likes it: It gives the agent a dependable way to drive and test the cos2 terminal UI.
What makes it strong: It combines exact commands, known-good terminal dimensions, keybindings, troubleshooting, and a reusable helper in scripts/tmux_cos2_controller.py.
Good pattern to copy: A great skill does not just tell the agent what to do — it also tells the agent how to observe whether it worked.

4. `cli2-internals`

Why the team likes it: It gives a fast mental model of a large and complex codebase area without pretending to replace the source code.
What makes it strong: It is structured around real sub-systems and common failure modes, with concrete file paths and implementation notes throughout.
Good pattern to copy: Reference-heavy skills work best when they are organised around the questions people actually ask.

5. `api-backend`

Why the team likes it: It helps people orient quickly in services/api, which is large and easy to navigate poorly.
What makes it strong: It maps the important flows — auth, controllers, orchestration, persistence, inference, and integrations — and points directly to the directories that matter.
Good pattern to copy: Good skills reduce orientation time first. They help the agent find the right files and concepts quickly.

Taken together, these show that strong skills do not all look the same:

some are workflow-first
some are tool-first
some are reference-first
some are operations-first

That is the right mindset for your first skill. Do not aim for a perfect universal template. Aim for something that makes repeated work easier and more reliable.

How to make a good skill

The best first skills are narrow, practical, and easy to test. A simple process usually works best:

Pick one repeatable job. Good first skills solve something concrete, like writing release notes from merged PRs, producing incident summaries in a standard format, or following a repo-specific review checklist.
Be explicit about when the skill should trigger. The description should say what the skill does and when the agent should use it.
Put the workflow in SKILL.md. Tell the agent what steps to follow, what output structure to use, and what to avoid.
Move large background material out of the main file. Keep SKILL.md focused. Put long guidance in references/ and deterministic repeatable logic in scripts/.
Test with real prompts. Try a clear request, a messy real-world request, and a near miss that should not trigger the skill. Then tighten the description and instructions based on what happened.

As a rule of thumb, strong skills tend to:

solve one category of problem well
save you from repeating the same prompt over and over
define the expected output clearly
explain the reasoning behind important steps
improve through real use rather than theory alone

A simple first version

This is enough for a real first draft:

---
name: incident-summary
description: Write incident summaries for engineering teams. Use this whenever the user asks for a postmortem summary, incident recap, outage write-up, or internal timeline summary from logs, notes, or chat transcripts.
---

# Incident Summary

## Workflow

1. Identify the timeline, impact, root cause, and resolution.
2. Call out unknowns rather than guessing.
3. Write for an internal engineering audience.

## Output format

Use this structure:

- Summary
- Customer impact
- Timeline
- Root cause
- Follow-up actions

That is enough to begin testing. You can add references and scripts later once you see what the agent still struggles with.

Key takeaways

Skills are reusable packages made from instructions, scripts, and supporting resources.
Project installs and .agents/skills/ are both project-scoped skills; .agents/skills/ is the repo-native version you can commit and share with your team.
~/.cosine/skills/ is for private skills that stay local to you and work across your sessions.
cos skills add --project installs into ~/.cosine/projects/<project-id>/skills/, which is the managed storage for that same project scope.
The fastest way to make a good first skill is to install and use skill-creator.
Good skills are narrow, explicit about when they should trigger, and tested against real prompts.

Next: Automating Content and Blog Post Research