> ## Documentation Index
> Fetch the complete documentation index at: https://teamcopilot.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating a Skill

> Learn how to create a skill in TeamCopilot, what files it starts with, and how to write instructions the AI can reliably follow.

A skill is the right choice when you want to teach the AI how your team handles a task.

In TeamCopilot, you can create a skill in two ways:

* manually from the **Skills** tab
* by asking the **AI Assistant** to create one for you

In both cases, the skill is stored as instruction files in your workspace.

## Before you create one

Create a skill when:

* you want reusable instructions for the AI
* the task depends on judgment, policy, or process
* you want the AI to follow your team's way of working

If the task needs code to run against APIs, databases, or external systems, create a workflow instead.

## Two ways to create a skill

### Create a skill manually

1. Open TeamCopilot.
2. Go to the **Skills** tab.
3. Click **Create Skill**.
4. Enter a skill name.
5. Open the new skill in the editor.
6. Edit the `SKILL.md` file.
7. Save your changes.
8. Have an engineer approve the skill before your team starts using it.

When you create a skill, TeamCopilot normalizes the name into a lowercase slug. The name and slug are treated as the same value.

### Create a skill with AI

1. Open TeamCopilot.
2. Go to the **AI Assistant**.
3. Ask the assistant to create a skill for a specific task or process.
4. Describe what the skill should do, when it should be used, and any rules it must follow.
5. Review the generated skill in the **Skills** tab.
6. Refine the `SKILL.md` instructions as needed.
7. Have an engineer approve the skill before your team starts using it.

This is useful when you want a fast first draft and prefer refining instructions instead of writing them from scratch.

## What gets created

Each skill lives in:

```text theme={null}
.agents/skills/<slug>/
```

The main file is:

```text theme={null}
SKILL.md
```

That file is the source of truth for the skill.

## Import existing skills

You do not always need to create a skill from scratch. You can also import existing skills into TeamCopilot.

One practical option is to use the [`skills`](https://www.npmjs.com/package/skills) CLI on the machine where the TeamCopilot service is running.

### How to import skills

1. Access the machine where TeamCopilot is running.
2. Navigate to your TeamCopilot workspace directory.
3. Run an `npx skills add ...` command from that workspace.
4. Confirm the install target if prompted.
5. Verify that the imported skills appear under `.agents/skills/`.
6. Open TeamCopilot and go to the **Skills** tab.
7. Have an engineer review and approve the imported skills.
8. After approval, update permissions so the right people or the whole team can use them.

Because the CLI installs project-scoped skills into the workspace, imported skills end up in TeamCopilot's `.agents/skills/` folder, where TeamCopilot can discover them.

### Example commands

List the skills available in a repository before installing:

```bash theme={null}
npx skills add vercel-labs/agent-skills --list
```

Install a specific skill into the current workspace:

```bash theme={null}
npx skills add vercel-labs/agent-skills --skill frontend-design -a opencode
```

Install all skills from a repository into the current workspace:

```bash theme={null}
npx skills add vercel-labs/agent-skills --skill '*' -a opencode
```

The important part is to run the command from your TeamCopilot workspace directory so the imported skills are added to the workspace-level `.agents/skills` folder.

### After import

Imported skills are not automatically ready for organization-wide use.

After importing them:

* review the imported `SKILL.md` files
* have an engineer approve them in TeamCopilot
* set permissions for specific people or **Everyone**

That approval step is what makes the imported skills usable in a controlled team environment.

## What to put in `SKILL.md`

A good skill should tell the AI a few key things:

* what the skill is for
* when it should be used
* how to perform the task well
* what rules or constraints must be followed

A practical structure is:

1. A short name and description
2. Any `required_secrets` the skill needs
3. The task or use case
4. Step-by-step instructions for the AI
5. Important rules, checks, and constraints
6. References to relevant files, scripts, systems, or docs

```mermaid theme={null}
flowchart LR
    A[Write SKILL.md] --> B[Add required secrets if needed]
    B --> C[Save in .agents/skills/<slug>/]
    C --> D[Engineer reviews diff]
    D --> E[Approve snapshot]
    E --> F[Set permissions]
    F --> G[Use skill in chat]
```

If the skill needs credentials, declare them in frontmatter and reference them by placeholder instead of raw value:

```yaml theme={null}
---
required_secrets:
  - SENDGRID_API_KEY
---
```

```text theme={null}
Use {{SECRET:SENDGRID_API_KEY}} in the Authorization header.
```

Users then add that key in **Profile Secrets**. If your team has a shared fallback, an engineer can provide it as a **Global Secret**.

If the skill references secret placeholders, keep them only in supported runtime contexts. TeamCopilot rejects unsupported secret usage instead of silently exposing values.

## What good skill instructions look like

Good skill instructions are:

* specific
* actionable
* scoped to a clear use case
* opinionated where your team has standards

Good examples:

* "Check `package.json` and `package-lock.json` versions before publishing."
* "Always review the last approved config before suggesting infra changes."
* "Summarize the issue in customer-friendly language before proposing next steps."

Weak examples:

* "Help with releases."
* "Be careful."
* "Do the right thing."

## Tips for writing better skills

* Keep one skill focused on one job or type of task.
* Prefer concrete instructions over general advice.
* Include decision rules when the AI needs to choose between options.
* Reference scripts or internal docs when they are part of the process.
* Update the skill as your team's process changes.

## Approval and access

Skills are visible in TeamCopilot, but engineer approval matters.

Before a skill becomes something the platform should rely on for team use:

* an engineer should review it
* an engineer should approve it
* access permissions should be set appropriately for your organization

This helps ensure the AI only uses reviewed instructions in production team workflows.

## What happens after approval

After approval:

* the approved snapshot is stored
* the skill can be used through chat and skill selection flows
* permissions can be updated to broaden or restrict access
* later edits will show as pending until reviewed again

## When to choose a skill instead of a workflow

Choose a skill when the main value is in the instructions themselves.

Examples:

* incident response guidance
* code review standards
* release process rules
* support escalation playbooks

If you need Python code, structured inputs, or repeatable execution, create a workflow instead.