Skills

Teach the Agent your team's workflows, runbooks, and conventions with custom Skills

Skills are reusable instructions you write once and the Agent follows whenever they apply. Use them to encode personal preferences, team runbooks, naming conventions, investigation playbooks, or any context you'd otherwise repeat in every prompt.

Skills can be personal or organizational. Personal Skills are visible only to you. Organizational Skills are readable and usable by everyone in the organization, and only admins can create, edit, or delete them.

Personal vs. Organizational Skills

Use the Skill scope to decide who should be able to use the instructions:

Scope	Who can use it	Who can manage it	Best for
Personal Skill	Only the user who created it	The creator, if they have Skill permissions	Individual response preferences, personal shortcuts, private workflows
Organizational Skill	Everyone in the organization	Admins only	Shared investigation runbooks, team conventions, common operating guides

Organizational Skills appear with an Org badge in the Skills list and detail view. They can be selected from the Skill picker and can also auto-activate from their When to use field, just like personal Skills.

Creating a Skill

Open the Skills page from the Agent sidebar. Click New Skill and fill in:

Field	Required	Purpose
Name	Yes	A short identifier shown in the picker (e.g. Incident Triage).
When to use	Yes	Plain-language description of when this Skill should apply. The Agent reads this to decide whether to activate the Skill.
Description	No	Short summary shown alongside the name in the picker.
Instructions	Yes	Markdown describing how the Agent should operate when this Skill is active.
Organizational Skill	No	Admin-only toggle. Turn it on to make the Skill available to everyone in the organization.

Click Save. Personal Skills are available immediately in your next Agent message. Organizational Skills are available to everyone in the organization after they are saved.

Ask the Agent to draft a Skill for you

You don't have to write Skills from scratch. Once the Agent has done useful work in a conversation - an RCA, a triage walk-through, a parsing-rule investigation, a dashboard build - you can ask it to turn that work into a Skill without leaving the chat. The Agent drafts a Name, When to use, and Instructions from the current conversation, and you review and save. If you are an admin, you can choose whether the draft stays personal or becomes an Organizational Skill before saving.

The better your ask, the better the resulting Skill. Thin asks produce thin Skills:

create a skill for investigating DB-related errors for checkout-service

A better ask spells out the activation trigger, the scope, and which parts of the conversation are the reusable pattern:

Turn this investigation into a Skill. Call it "Postgres slow-query triage for checkout". Activate it when I ask about checkout-service latency or errors that look database-bound. The Instructions should keep the steps we just did: pull pg_stat_statements top queries over the incident window, correlate with the deploy timeline of checkout-api, then trace one failing request end-to-end. Default lookback is 1 hour, and always use P95 for latency.

Or:

Save this conversation as a Skill for Redis authentication failures. Name it "Redis auth troubleshooting". Activate it when Redis clients in cache-* namespaces start failing auth after a deploy or config change. Instructions should capture exactly what we just checked - Redis config history, client library version, and TLS cert expiry - in that order. Skip the side tangent about node labels.

The Agent produces a better Skill when you tell it:

• The activation condition - which services, namespaces, alert shapes, or user phrasings should trigger it. Vague activation causes the Skill to either miss the prompt or auto-pull on unrelated questions.

• Which parts of the current conversation are the reusable pattern vs. incidental details. "Keep the three checks we did, drop the bit about node labels."

• Conventions that should survive - your preferred metric (P95 vs P99), default lookback, output format, namespaces to ignore, services to exclude.

• A Name - or let the Agent propose one. "Postgres slow-query triage" beats "DB stuff."

The draft is a starting point - edit any field before saving, or tweak the Skill from the Skills page later.

Using a Skill

There are two ways a Skill gets activated in a conversation:

Explicit - type / in the Agent input. A picker shows your Skills; select one to attach it to your next message.

/incident-triage investigate the alert on checkout-service

Automatic - the Agent reads the When to use field of all your Skills and activates the relevant ones based on your prompt. For example, if your Skill's When to use says "Use when I ask for incident triage or RCA follow-ups", asking the Agent to investigate an incident will pull it in automatically.

When a Skill is active, its Instructions are injected into the Agent's context alongside the base system prompt. The Agent will mention which Skills it used, and you can see them attached to the message.

Writing Good Instructions

The Instructions field is Markdown - structure it like a runbook or spec. A few patterns that work well:

Goals and scope

# Goal
Run a 5-whys root cause analysis for production incidents.

# Scope
Only for workloads in the `prod-*` namespaces.

Step-by-step procedures

# Steps
1. Pull error logs from the last 30 minutes, grouped by pattern.
2. Correlate with deploy events in the same window.
3. Check upstream and downstream services for related errors.
4. Summarize findings with Who / What / Where / When / Why.

Conventions and preferences

# Output format
- Lead with a one-line summary.
- Use a bulleted timeline for the chronology.
- Always include the monitor name and namespace.

# Query style
- Prefer P95 over P99 for latency charts.
- Default lookback is 1 hour unless I say otherwise.

Tips

• Be specific about when it applies - the Agent uses When to use to decide whether to pull the Skill in. Vague descriptions lead to unexpected activations or missed ones.

• Write for the Agent, not for a human reader - imperative instructions ("Always include X", "Never do Y") are followed more reliably than prose.

• Keep it focused - one Skill per workflow. Two Skills with overlapping triggers are fine; one giant Skill covering every scenario is harder to maintain.

• Iterate - if the Agent doesn't behave as expected, refine the Instructions and try again. Changes take effect on the next message.

A Full Example: Payments Incident Triage

Here's a complete, copy-ready Skill that codifies how one engineer wants the Agent to handle incidents on their payments service. Use it as a starting point and adapt it to your own stack.

Name

Payments Incident Triage

When to use

Use when I ask to triage an alert, investigate an incident, or do an RCA on any service in the `payments-*` namespaces.

Description

5-whys triage playbook for the payments platform.

Instructions

# Goal
Triage a production incident on the payments platform end-to-end and produce a written summary I can paste into the incident channel.

# Scope
Only for workloads in `payments-api`, `payments-worker`, `payments-ledger`, and `payments-gateway` namespaces. If the alert is for a different service, say so and stop.

# Procedure
1. **Anchor the timeline.** Find when the alert first fired and when symptoms started in the data. Use the earlier of the two as t=0.
2. **Check the blast radius.** For the affected workload, report:
   - Error rate (last 1h, broken down by endpoint)
   - P95 latency (last 1h vs. the prior 24h baseline)
   - Pod-level restarts, OOMKills, and crashloops in the window
3. **Look for change correlation.** In a ±30 min window around t=0, list:
   - Deploys (image tag changes) for any payments-* workload
   - ConfigMap / Secret updates
   - HPA scaling events
   - Upstream incidents (check `auth-*` and `fraud-*` dependencies)
4. **Trace a bad request.** Pull one representative failing trace and walk through the span tree. Identify the first span that shows the error.
5. **Check the database.** Query latency and error rate on the Postgres calls from `payments-ledger`. Flag any query pattern that crossed 500ms P95.
6. **Summarize** in this exact format:

   ```
   **Impact:** <one line>
   **Likely cause:** <one line, cite the evidence>
   **Timeline:**
   - HH:MM — <event>
   - HH:MM — <event>
   **Suggested next step:** <one action>
   **Evidence:** <links to the groundcover views you used>
   ```

# Conventions
- Always use P95 for latency, never average.
- Default lookback is 1 hour; extend to 6 hours only if the alert is older than that.
- Ignore `payments-staging-*` namespaces.
- If you can't find deploy events, say so explicitly — don't guess.

Why this Skill works

A few things make this Skill reliable in practice:

• The When to use is specific. It names the namespace prefix and the types of prompts that should trigger it. The Agent uses this field to decide whether to auto-activate the Skill, so vague wording like "use for incidents" would cause it to fire on unrelated services.

• The scope is bounded. Explicitly listing the four payments namespaces and telling the Agent to stop if the alert is elsewhere prevents it from applying payments-specific assumptions to, say, an auth service outage.

• Steps are imperative and ordered. "Anchor the timeline", "Check the blast radius", "Trace a bad request" — each step is a concrete action the Agent can execute against groundcover data. Prose like "investigate thoroughly" produces inconsistent results.

• The output format is pinned. Giving the Agent an exact template (Impact / Likely cause / Timeline / Next step / Evidence) means every triage summary looks the same and is safe to paste into an incident channel without reformatting.

• Defaults and exceptions are explicit. "Default lookback is 1 hour", "Ignore staging namespaces", "Don't guess if deploys aren't found" — each of these is a decision the Agent would otherwise make inconsistently from one run to the next.

Managing Skills

On the Skills page you can:

• Search Skills by name.

• Edit a personal Skill - changes apply to new messages immediately.

• Delete a personal Skill - removes it from the picker and stops auto-activation.

• Manage an Organizational Skill - admins can edit or delete it from the same page.

If an admin changes an Organizational Skill back to a personal Skill, groundcover asks for confirmation. Once the Skill is personal, only its creator can see it.

Skills are versioned - when a conversation uses a Skill, the revision in use at send time is what the Agent saw.