---
description: Modify your agent's output easily with skills and actions
---

# Basics

**PLEASE NOTE: This feature is currently in beta. This is due to it being untested and the changing nature of this feature on the Carter API end. Please report any issues through a GitHub issue.**

The Carter Object can detect [forced behaviours](https://carterapi.gitbook.io/carter-docs/agents/custom-triggers) which are returned with the Carter API response. You can combine these with `carter-js` skills in order to customise the output.

It begins with registering a skill with your Carter Object. A skill contains a name, action, and some options. The name must match the name of your custom trigger in the Carter dashboard. The action is a function which takes in the response from your custom trigger and the initial CarterAPI response, and allows you to return a new output. It looks something like this:

```javascript
// already created a CarterObject called carter

const skill = {
    name: "weather",
    action: (response) => { // THis function will be called with async by carter-js
        return {"This is my altered response with weather api data"}
    },
    auto: true
}

    // Do whatever you like here
    return CarterSkillOutput(skill)
```

`registerSkill()` accepts an action function. An action allows you to modify the output based on this information and any code you run inside it. An action **MUST** take in the response parameter, as carter will call it with this parameter behind the scenes.. `response` is the initial output text from CarterAPI. You could combine this with the personalise feature to build completely custom api responses with your characters personality still at the forefront.

**If your action doesn't modify your agent's output then you need not return anything from this function**. If you would like your action to modify the agent's output then you can return a `SkillOutput` object.

```typescript
CarterSkillOutput {
    output: string, // the new agent output text
    skillData: any // custom data you can access from inside the 
    // triggered skills array, this is optional and can be anything
}
```

How your return affects the interaction output depends on whether your skill is an automatic skill or not.

## Skill Options

You can pass currently pass one option when you register a skill.

### auto

A carter skill can be either automatic or manual. Manual is the default, if you wish to make it automatic you must set `auto` to true when you register the skill.

By default, when a forced behaviour is detected the corresponding skill is returned with the interaction response. These skills are added to the `interaction.triggeredSkills` array. The output text and audio link remain the same. If you wish to execute the skill and retrieve the modified output you can call `await skill.execute()` on that skill and the new response text will be returned. **The text and audio link in `interaction.carterData.output` will remain the same.**

When `auto` is set to `true`, the skill will be executed automatically when detected and `interaction.carterData.output` will be modified. The skill will then be added to the `interaction.executedSkills` array.
