bird-chinese-community/BIRD.skills / bird-agent
bird-agent
VerifiedWrite, review, discover, lint, format, and validate BIRD 2/3 routing-daemon projects with the @birdcc toolchain. Use for bird.conf, bird2.conf, bird3.conf, bird6.conf, .bird/.bird2/.bird3 files, bird.config.json, birdcc.config.json, include graphs, BIRD filters and protocols, birdcc init/lint/fmt/lsp, or bird -p checks. Treat BIRD 1 as legacy and verify it with the actual BIRD 1 binary. Route editor and CLI installation to birdcc-installer, GitHub Actions to birdcc-cicd, runtime incidents to bird-troubleshooting, and implementation archaeology to bird-source-explorer.
| File | Kind | Size |
|---|---|---|
| .mcp.json | config | 227 B |
| SKILL.md | skill md | 5.6 KB |
| agents/openai.yaml | config | 381 B |
| assets/logo-small.png | binary | 2.9 KB |
| assets/logo.png | binary | 6.5 KB |
| evals/evals.json | config | 5.5 KB |
| evals/fixtures/bird-unformatted.conf | config | 147 B |
| evals/fixtures/bird.conf | config | 144 B |
| evals/fixtures/cross-file/main.conf | config | 44 B |
| evals/fixtures/cross-file/peers.conf | config | 122 B |
| metadata.json | config | 527 B |
| plugin.json | config | 554 B |
| references/birdcc-ecosystem.md | markdown | 5.7 KB |
| references/cicd.md | markdown | 718 B |
| references/editors.md | markdown | 742 B |
| references/examples.md | markdown | 1.6 KB |
| references/project-config.md | markdown | 3.3 KB |
| references/safety.md | markdown | 1.2 KB |
| references/toolchain.md | markdown | 3.0 KB |
| scripts/detect_bird_context.py | script | 7.4 KB |
| scripts/run_birdcc.py | script | 7.0 KB |
scripts/run_birdcc.py
View on GitHub# /// script
# requires-python = ">=3.10"
# dependencies = []
# ///
"""Run birdcc lint or fmt with structured JSON output.
Safety defaults:
- fmt defaults to --check; --write requires an additional --confirmed flag.
- The config path must resolve to a regular file inside --root.
- Paths starting with "-" are rejected to avoid being parsed as flags.
"""
from __future__ import annotations
import argparse
import json
import re
import shutil
import subprocess
import sys
from pathlib import Path
VALID_SUBCOMMANDS = {"lint", "fmt"}
MAX_OUTPUT_BYTES = 2 * 1024 * 1024
# Whitelist for --validate-command templates. Only simple command characters plus
# the required {file} placeholder are allowed; this blocks shell metacharacters
# such as backticks, pipes, semicolons, globs, and escapes.
_VALIDATE_COMMAND_RE = re.compile(r"^[A-Za-z0-9_./\- ]*\{file\}[A-Za-z0-9_./\- ]*$")
def fail(message: str, hint: str | None = None, code: int = 1) -> int:
"""Emit a JSON error and return a non-zero exit code."""
payload: dict[str, object] = {"error": message}
if hint:
payload["hint"] = hint
json.dump(payload, sys.stderr, indent=2, ensure_ascii=False)
sys.stderr.write("\n")
return code
def validate_config_path(config: str, root: Path) -> Path:
"""Validate that the user-supplied config path is safe to pass to birdcc."""
if config.startswith("-"):
raise ValueError("config path must not start with '-'")
raw = Path(config)
if not raw.is_absolute():
raw = root / raw
try:
resolved = raw.resolve(strict=True)
except FileNotFoundError as exc:
raise ValueError(f"config file not found: {config}") from exc
except OSError as exc:
raise ValueError(f"cannot access config file: {config}") from exc
try:
root_resolved = root.resolve()
except OSError as exc:
raise ValueError(f"cannot resolve root: {root}") from exc
try:
resolved.relative_to(root_resolved)
except ValueError as exc:
raise ValueError(
f"config path must be inside root ({root_resolved}): {config}"
) from exc
if not resolved.is_file():
raise ValueError(f"config path is not a regular file: {config}")
return resolved
def build_command(args: argparse.Namespace) -> list[str]:
"""Build the birdcc command from parsed arguments."""
cmd = [args.birdcc, args.subcommand, str(args.config)]
if args.subcommand == "lint":
cmd.extend(["--format", "json"])
if args.bird:
cmd.append("--bird")
if args.validate_command:
if _VALIDATE_COMMAND_RE.fullmatch(args.validate_command) is None:
raise ValueError(
"--validate-command must contain {file} and only safe command characters"
)
cmd.extend(["--validate-command", args.validate_command])
elif args.subcommand == "fmt":
if args.write:
cmd.append("--write")
else:
cmd.append("--check")
return cmd
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(
description="Run birdcc lint or fmt and return structured output."
)
parser.add_argument(
"subcommand",
choices=sorted(VALID_SUBCOMMANDS),
help="birdcc subcommand to run (lint or fmt).",
)
parser.add_argument("config", help="Path to the BIRD config file.")
parser.add_argument(
"--root",
type=Path,
default=Path.cwd(),
help="Project root used to contain allowed config paths (default: current directory).",
)
parser.add_argument(
"--birdcc",
default=shutil.which("birdcc") or "birdcc",
help="Path to the birdcc executable (default: birdcc on PATH).",
)
parser.add_argument(
"--bird",
action="store_true",
help="For lint: also run BIRD runtime validation with bird -p.",
)
parser.add_argument(
"--validate-command",
help="For lint: custom validation command template (e.g., 'docker exec bird bird -p -c {file}').",
)
parser.add_argument(
"--write",
action="store_true",
help="For fmt: write formatted output instead of checking (default: --check).",
)
parser.add_argument(
"--confirmed",
action="store_true",
help="Required alongside --write to actually modify files. Without this flag fmt uses --check.",
)
parser.add_argument(
"--dry-run",
action="store_true",
help="Print the command that would run without executing it.",
)
args = parser.parse_args(argv)
if not args.root.is_dir():
parser.error(f"--root must be a directory: {args.root}")
if shutil.which(args.birdcc) is None:
return fail(
"birdcc not found",
"MUST DO: Load the `birdcc-installer` skill and follow its guidance to install @birdcc/cli. "
"If you need a manual fallback: npm install -g @birdcc/cli@latest (or npx -y @birdcc/cli@latest).",
code=127,
)
try:
args.config = validate_config_path(args.config, args.root)
except ValueError as exc:
return fail(str(exc), code=2)
if args.subcommand == "fmt" and args.write and not args.confirmed:
return fail(
"fmt --write requires --confirmed to modify files",
"Run with --confirmed only after the user explicitly approves modifying the file.",
code=2,
)
try:
cmd = build_command(args)
except ValueError as exc:
return fail(str(exc), code=2)
if args.dry_run:
json.dump({"dry_run": True, "command": cmd}, sys.stdout, indent=2)
sys.stdout.write("\n")
return 0
result = subprocess.run(
cmd,
capture_output=True,
text=False,
check=False,
timeout=300,
)
stdout_truncated = len(result.stdout) > MAX_OUTPUT_BYTES
stderr_truncated = len(result.stderr) > MAX_OUTPUT_BYTES
stdout_bytes = (
result.stdout[:MAX_OUTPUT_BYTES] if stdout_truncated else result.stdout
)
stderr_bytes = (
result.stderr[:MAX_OUTPUT_BYTES] if stderr_truncated else result.stderr
)
stdout = stdout_bytes.decode("utf-8", errors="replace")
if stdout_truncated:
stdout += "\n[truncated]\n"
stderr = stderr_bytes.decode("utf-8", errors="replace")
if stderr_truncated:
stderr += "\n[truncated]\n"
output: dict[str, object] = {
"command": cmd,
"returncode": result.returncode,
"stdout": stdout,
"stderr": stderr,
}
if args.subcommand == "lint" and result.stdout:
try:
parsed = json.loads(result.stdout.decode("utf-8", errors="replace"))
if isinstance(parsed, list):
output["diagnostics"] = parsed
else:
output["report"] = parsed
except json.JSONDecodeError:
pass
json.dump(output, sys.stdout, indent=2, ensure_ascii=False)
sys.stdout.write("\n")
return result.returncode
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |