# BIRD.skills (Agent Skills)

[English](./README.md) | [中文](./README.zh.md)

[![License](https://img.shields.io/github/license/bird-chinese-community/BIRD.skills)](./LICENSE) [![GitHub stars](https://img.shields.io/github/stars/bird-chinese-community/BIRD.skills)](https://github.com/bird-chinese-community/BIRD.skills/stargazers)

> Agent skills for BIRD 2/3 projects, editor tooling, CI/CD, source research, and incident diagnosis. BIRD 1 is handled as a legacy, best-effort target.

## Which skill do I need?

| If your pain point is...                                                          | Use this skill                           |
| --------------------------------------------------------------------------------- | ---------------------------------------- |
| "I need to write or fix `bird.conf`, `bird2.conf`, `bird3.conf`, or `bird6.conf`" | [`bird-agent`](./bird-agent)                 |
| "I need editor support or the `birdcc` CLI installed"                             | [`birdcc-installer`](./birdcc-installer)     |
| "I want BIRD linting or formatting in GitHub Actions"                             | [`birdcc-cicd`](./birdcc-cicd)               |
| "I want to understand how BIRD implements something internally"                   | [`bird-source-explorer`](./bird-source-explorer) |
| "I need to diagnose a BIRD daemon crash or runtime issue"                         | [`bird-troubleshooting`](./bird-troubleshooting) |

### Skill descriptions

- **[`bird-agent`](./bird-agent)** — Discover project entry points, generate or migrate `bird.config.json`, and lint, format, or natively validate BIRD 2/3 configurations.
- **[`bird-source-explorer`](./bird-source-explorer)** — Trace behavior from parser/registry definitions through runtime dispatch and tests at an exact BIRD source revision.
- **[`bird-troubleshooting`](./bird-troubleshooting)** — Separate project discovery, static diagnostics, native parsing, live daemon state, and source evidence during incidents.
- **[`birdcc-installer`](./birdcc-installer)** — Install the verified VS Code extensions, `BIRD.nvim`, `BIRD.vim`, JetBrains TextMate bundle, or `@birdcc/cli`, including legacy repository migrations.
- **[`birdcc-cicd`](./birdcc-cicd)** — Build GitHub Actions from the current `setup-birdcc` contract without duplicate checkout, missing CLI installation, or stale cache inputs.

## What are Agent Skills?

[Agent Skills](https://agentskills.io/) are reusable, agent-readable capability bundles. Each skill contains a `SKILL.md` manifest, `agents/openai.yaml` metadata, optional PEP 723 stdlib-only helper scripts, and focused reference guides.

## Quick start for AI agents

After installing the skills, point an agent at a workspace with BIRD files and ask naturally:

```text
"Discover this BIRD project and check every entry"
"Install BIRD support for my editor"
"Add BIRD validation to our GitHub Actions workflow"
"Trace this BGP behavior through the matching BIRD source"
```

The agent will use the right skill, run `birdcc lint` / `fmt`, validate with `bird -p`, or generate CI snippets as needed.

## Installation

```prompt
Read https://raw.githubusercontent.com/bird-chinese-community/BIRD.skills/main/INSTALL.md in full, then install the BIRD skills for my harness now.
```

## Security

BIRD configs may contain sensitive AS numbers, peer IPs, BGP passwords, and BGP community. DO NOT commit production secrets or share unsanitized configs publicly.

## Contributing

See [`AGENTS.md`](./AGENTS.md) for development conventions. To add a skill, create a new folder matching the existing layout with `SKILL.md`, `agents/openai.yaml`, and references/scripts as appropriate.

Repository maintenance is provided by a Python 3.14 uv project:

```bash
uv sync --locked --group dev
uv run bird-skills check
uv run pytest
uv run ruff check .
uv run ruff format --check .
```

The CLI synchronizes release metadata and every marketplace, safely links local skills, and plans or
runs harness-neutral evaluations. See [`docs/evaluation.md`](./docs/evaluation.md) for the external
Agent runner protocol.

## License

[MIT](./LICENSE)