# Author and improve a Skill (/docs/guides/author-skills)

You can improve a shared Skill from your own editor. BarnDog keeps track of what you changed, so you don't need Git or local commits.

## Improve an existing Skill [#improve-an-existing-skill]

<Steps>
<Step>

### Pull it into a working folder [#pull-it-into-a-working-folder]

```bash
barndog skills pull code-review --origin team/engineering
cd code-review
```

This creates a new `./code-review` folder. Use `--directory <path>` to choose another location. Pull refuses to write into a folder that already exists.

</Step>
<Step>

### Edit the files [#edit-the-files]

Change `SKILL.md` or any supporting file with any editor. Then check your work:

```bash
barndog status
barndog diff
```

`status` shows changed files and the state of your proposal. `diff` shows your changes against the version you pulled.

</Step>
<Step>

### Suggest the change [#suggest-the-change]

```bash
barndog push --title "Clarify the review checklist"
```

BarnDog uploads your edits as one **Suggested Change** and prints its ID. Your team reviews it in the web workspace or with [`barndog changes`](/docs/cli/changes).

</Step>
<Step>

### Respond to feedback [#respond-to-feedback]

If a reviewer asks for changes, edit the files again and run `barndog push`. That updates the same Suggested Change with a new revision.

If a reviewer applies one of their own suggestions, run `barndog pull` to bring it into your folder.

</Step>
</Steps>

Once the change is merged, it becomes the Skill's next published version and reaches everyone on their next `barndog sync`.

## Create a new Skill [#create-a-new-skill]

Create a folder with a `SKILL.md`, then push it with an origin:

```bash
mkdir release-notes && cd release-notes
# Write SKILL.md
barndog push --origin team/engineering
```

A new Skill is proposed the same way as a change to an existing one: it shows up as **In review** until it is merged.

## Publish directly [#publish-directly]

Team and repository admins can publish in their scopes without review, and organization admins can publish anywhere. You can always publish your own personal Skills.

```bash
barndog push --publish
```

A normal `barndog push` always creates a Suggested Change, even for admins.

## Keep up with the published version [#keep-up-with-the-published-version]

If someone publishes a newer version while you're working, run:

```bash
barndog pull
```

BarnDog merges the latest published version into your folder. Text edits that don't overlap are combined automatically.

When edits do overlap, the file gets conflict markers showing the base, your version, and the published one. For binary files, and for files one side deleted, your local version is kept. Fix each file, then mark it resolved:

```bash
barndog resolve SKILL.md
```

You can't push until every conflict is resolved. An out-of-date Suggested Change can't be merged, even by an admin.

## Good to know [#good-to-know]

- Run commands from the working folder or any folder inside it.
- Keep the folder where you pulled it. BarnDog registers the working copy by its path.
- Working copies are separate from installed Skills. Pulling and editing never changes what's installed in your harnesses.
- `.git` folders are left out of uploads. Symlinks are rejected.
- If an upload fails partway, the next push retries the same submission, so nothing is lost.
- Before each pull, BarnDog saves a recovery snapshot in `~/.barndog/workspaces/snapshots/`.