If you’re building software today, you’ve probably noticed that it’s like… really fast now. And that’s the thing: it’s not just that we code faster. It’s how we code, review, and ship that has changed (and is changing). You might have seen the Octoverse 2025 report, but in case you haven’t, the stats are pretty wild: developers created 230+ repositories per minute and pushed 986 million commits last year. Almost a billion commits! With a b! Because developers (and teams of developers) are moving faster overall, the expectation is to make different choices because they’re moving faster. When they move faster, their workflows change, too. Iteration is the default state What’s really interesting is that this doesn’t feel like a temporary spike. It feels like an actual long-term shift in iteration. The days of shipping big releases once per quarter are rapidly going away. Developers are pushing constantly, not just when things are “ready.” Smaller and more frequent commits are becoming more of the norm. Personally, I love that. Nobody wants to review a gigantic, 1000-line pull request all the time (only to inevitably plop in a “LGTM” as their eyes glaze over). It’s still more code, shipped faster, but in smaller bursts.  The new normal is lightweight commits. You fix a bug, write a small feature, adjust some configurations, and… push. The shift we’re seeing is that things continue to move, not that things are “done” in huge chunks, because “done”-ness is temporary! “Art Code is never finished, only abandoned iterated upon.” Leonardo Da Vinci Cassidy, as well as most developers at this point And devs know that shipping constantly is about reducing risk, too. Small, frequent changes are easier to debug, and easier to roll back if things go wrong. You don’t have to sift through a month’s worth of changes to get something fixed.This cycle changes how teams think about quality, about communication, and even hiring. If your team is still moving at a pace where they wait weeks to ship something, your team honestly isn’t working like a lot of the world is anymore. Shipping looks different now Because we’re iterating differently, we’re shipping differently. In practice, that looks like: More feature flags: Feature flags used to be “for A/B testing and maybe the spooky experimental feature.” Now they’re core to how we ship incomplete work safely. Feature flags are everywhere and let teams ship code behind a toggle. You can push that “maybe” feature to prod, see how it behaves, and then turn it off instantly if something goes sideways. Teams don’t have to hold up releases to finish edge cases. And feature flags are more a part of main workflows now instead of an afterthought. CI/CD runs everything: Every push sets off a chain of events: tests, builds, artifact generations, security scans… if it passes, it deploys. Developers expect pipelines to kick in automatically, and manual deploys are more and more rare. Smaller, focused pull requests: Pull requests simply aren’t novels anymore. We’re seeing more short, readable pull requests with a single purpose. It’s easier and faster to review, and that mental overhead alone increases speed and saves us some brain cells. Tests drive momentum: Developers used 11.5 billion GitHub Actions minutes running tests last year (a 35% increase! That’s with a b! Again!). With all this automation, we’re seeing unit tests, integration tests, end-to-end tests, and all the tests becoming more and more necessary because automation is how we keep up with the new pace. How teams communicate should also change We know it’s a fact now that developer workflows have changed, but I personally think that communication around development should also follow suit. This is how I envision that future: Standups are shorter (or async). Status updates live in issues (and “where code lives,” not meetings). “Blocked because the pull request isn’t reviewed yet” is no longer acceptable. Hiring shifts toward people who can ship fast and communicate clearly. Yes, the code got faster, so developers have to move faster as well. Developers are still a part of engineering speed. But developer workflows should never slow things down too much. Take this with you It’ll be interesting to see what developer workflows in 2026 look like after such rapid changes in 2025. I think “AI fatigue” is incredibly real (and valid) and we’ll see many tools fall by the wayside, of course, as the natural productivity enhancers succeed and the ones that add friction go away. But I also think new standards and tooling will emerge as our new “baseline” for our ever-changing success metrics. In the future, specs and code will live closer together (Markdown-to-code workflows are only going to grow). That will mean more communication across teams, and perhaps even more documentation overall. And we’ll continue to see more and more constant and collaborative shipping (even from companies that are still slow to adopt AI tooling) because it’s necessary. This year, we’ve seen a lot of growth across the board in terms of pull requests, projects overall, contributions, and so on… so perhaps we’ll see some stabilization?  But, of course, the only constant is change. Looking to stay one step ahead?  Read the latest Octoverse report and consider trying Copilot CLI. The post What 986 million code pushes say about the developer workflow in 2025 appeared first on The GitHub Blog. ​ News & insights, Octoverse, agentic workflows, CI/CD, developer productivity, developer workflows, feature flags, GitHub Actions, modern developer practices, pull requests The GitHub Blog

As engineers at GitHub, “dogfooding” is core to our culture. We build GitHub on GitHub, using the same tools we ship to developers. But as GitHub Copilot has evolved from an autocomplete suggestion to a sophisticated AI assistant, our own use of it has evolved, too. It’s no longer just a tool in our editors. We’ve integrated Copilot directly into our development lifecycle. Inside our core repository, the one we use to build github.com, @Copilot isn’t just suggesting code; it’s an active contributor. It gets assigned issues by human engineers, opens pull requests, and does the work assigned. Copilot is a prolific engineer within GitHub, and it’s taking on some of our most time-consuming and tedious tasks. For this article, we analyzed a month of pull requests created within our core repo by Copilot. Here’s what we found. Copilot does simple work that saves time Before we get to the complex, architectural work, it’s worth noting how much of Copilot’s day-to-day work is about accelerating the small tasks that add up. These are the quick fixes that save engineers from constant context-switching. UI and copy tweaks: It gets tasked with fixing minor UI bugs, like realigning a misaligned icon, or updating placeholder text in a filter bar to be more accurate. Documentation and cleanup: It also handles straightforward cleanup. In one pull request, @Copilot was assigned to fix 161 typos in comments and documentation strings across 100 different files. It’s a simple task, but one that no human engineer wants to spend an afternoon doing. Critical cleanup and maintenance A healthy codebase requires constant care. This is where @Copilot shines. A significant portion of the pull requests were focused on code maintenance, modernization, and large-scale refactors that would have been time-consuming for human engineers, including: Removing feature flags: This is a huge one. @Copilot is constantly assigned to clean up deprecated feature flags, removing the conditional logic, stale code, and old tests across the entire codebase. Large-scale refactoring: When we need to rename a class used across the application, @Copilot can take it on. It’s even authored massive, repository-wide pull requests to rename core internal classes, a task that would be tedious and time-consuming for any developer. Performance optimization: It finds and fixes common performance anti-patterns, replacing inefficient code with more optimized alternatives in high-traffic areas. Fixing bugs and flaky tests @Copilot also helped us solve a number of bugs. It’s patched production issues and improved the stability of our CI/CD pipeline. Production errors: It’s not just fixing simple bugs; it’s resolving tricky NoMethodError issues in core logic and even fixing complex error masking issues in our caching infrastructure. Performance bottlenecks: One of its most impactful contributions was a pull request that fixed a severe performance issue where git push was taking ~15 minutes for engineers in Codespaces. Fixing flaky tests: We all know the pain of a test breaking a build. @Copilot was regularly assigned to investigate and fix them. Building new features This is where it gets really interesting. @Copilot isn’t just maintaining old code; it’s actively building new functionality. Human engineers spec out the work in an issue, assign it to @Copilot, and it gets to work. It’s adding: New API endpoints: One pull request added a new REST API endpoint to list repository security advisory comments. New internal tools: It’s not just adding production features. Copilot has been extensively used to improve our internal tools. Our internal intranet, training sites, onboarding, etc. All of these have been maintained significantly by Copilot.  Migrations and security Beyond daily tasks, we’re also assigning @Copilot to high-stakes, complex projects that are critical for the platform’s future. Security gating: @Copilot has been tasked with adding security gates to prevent our own internal integrations from performing sensitive actions, such as modifying releases or release assets. Database migrations: It’s even handling database schema migrations. We’ve assigned it critical, high-precision tasks like migrating column types to support new standards. Documentation creation: It’s used to keep documentation in sync with fast-moving code. For example, it has authored numerous pull requests to add comments to our rate-limiting code to ensure developers easily remember to keep it synchronized with another service. Codebase-wide audits and analysis: Discerning problems, then solving them In some of its most advanced tasks, @Copilot acts as a researcher. We can assign it an ambiguous task, and it will analyze the codebase and report back with its findings in a pull request. In one pull request, it was tasked with auditing all our Codespaces feature flags. It returned a pull request with a comprehensive report categorizing all the flags and their references throughout the code. In another, it performed a “comprehensive analysis of authorization queries” to identify opportunities for performance and safety improvements. This moves Copilot’s role from code generation to systems-level architectural analysis, helping developers to jump straight to solving a complex problem rather than spending days just identifying it. A new way to collaborate If you check Copilot’s merged pull request rate in your repo, you’ll notice it’s lower than human contributors. That’s expected—and useful. Here’s the pattern we discovered: You assign @Copilot an issue It opens a pull request with a first-pass solution You review it like any other pull request Then you choose to merge it, iterate on the branch, or close it and take a different approach. The value isn’t in blindly merging. It’s in not starting from zero. You’ll get a concrete implementation to critique right away. All the boilerplate and the basic scaffolding is already handled. This shifts our focus away from writing all the code. Instead, you get to jump straight to the most critical parts of engineering: solving the core problem, refining Copilot’s suggestions, working in areas of the codebase not fit for AI, and owning the architecture, security, and user experience. It’s not about automating our jobs; it’s about letting Copilot handle the tedious 80% of the work. This frees us up to dedicate our expertise to the critical 20% that truly matters.

When people talk about AI and software development, the focus usually lands on productivity: faster pull requests, fewer boilerplate chores, auto-generated tests, autocomplete that feels psychic. But according to Idan Gazit, who leads GitHub Next—the team behind Copilot and GitHub’s long-range R&D—that’s the shallow end of the change curve. The deeper shift is happening before a single line of code is written. “AI isn’t just changing how we write code,” Gazit says. “It’s starting to change what we choose to build with in the first place.” That shift is already visible in this year’s Octoverse report. In 2025, TypeScript overtook both JavaScript and Python as the most-used language on GitHub—a 66% year-over-year surge and the biggest language movement in more than a decade.  But the story isn’t “TypeScript beats Python.” It’s that AI is beginning to shape language trends from the inside out. The last generation of change was about where code runs: cloud, containers, CI/CD, open source ecosystems.The next one is about what code is made of, and why those choices suddenly have different stakes. TypeScript passed Python. But the real story is why. Developers don’t usually switch languages just for philosophical reasons—they switch when something makes their work meaningfully faster, simpler, or less risky. And increasingly, what feels “easier” is tied to how well AI tools will support their work with that language. “Statically typed languages give you guardrails,” Gazit says. “If an AI tool is going to generate code for me, I want a fast way to know whether that code is correct. Explicit types give me that safety net.” Typed languages reduce hallucination surface area. They also give models more structure to reason about during generation. That’s not a theoretical benefit. It’s now a behavioral signal in the data: AI models tend to perform better on languages which expose information about correctness, like a type system Developers using AI tools are more likely to adopt typed languages for new projects The more teams rely on AI assistance, the more language choice becomes an AI-compatibility decision, not merely a personal preference That shift sets up a feedback loop. AI assistance is a new consideration when developers are selecting languages and frameworks AI models are strongest at authoring code in popular languages: TypeScript, Python, Java, and Go, just to name a few. “If the model has seen a trillion examples of TypeScript and only thousands of Haskell, it’s just going to be better at TypeScript,” Gazit says. “That changes the incentive before you even start coding.” If an AI tool is going to generate code for me, I want a fast way to know whether that code is correct. Explicit types give me that safety net. Idan Gazit, head of GitHub Next Before AI, picking a language was a tradeoff between runtime, library ecosystem, and personal fluency. After AI, a new constraint appears: How much lift will the model give me if I choose this language? “Python is the dominant language for machine learning, data science, and model training,” Gazit says. “Why would I not choose the one that already has the most robust frameworks and libraries? Those are wheels I don’t need to reinvent.” So TypeScript isn’t winning against Python; each is winning in the situations where it is the right tool for the job, and where AI makes it more valuable. The surprise winners of the AI era: the “duct tape” languages One of the most unexpected signals in the Octoverse data wasn’t about TypeScript or Python—it was about Bash. Shell scripting saw +206% year-over-year growth in AI-generated projects. So what gives? Because AI makes painful languages tolerable. “Very few developers love writing Bash,” Gazit says. “But everybody needs it. It’s the duct tape of software. And now that I can ask an agent to write the unpleasant parts for me, I can use the right tool for the job without weighing that tradeoff.” If AI automates the drudgery layer of programming, the question stops being “Is this language enjoyable?” and becomes “should I consider using it when I don’t have to write the code myself?” Very few developers love writing Bash. But everybody needs it. It’s the duct tape of software. And now that I can ask an agent to write the unpleasant parts for me, I can use the right tool for the job without weighing that tradeoff. Enterprises aren’t asking “Should we adopt AI?” anymore. They’re asking “What happens after we do?” “A lot of enterprises have been sitting on the sidelines, waiting to see when the water is warm enough to jump in,” Gazit says. “Now they’re seeing the value: junior developers ramp faster, and senior developers spend less time on toil and more on architecture.” That creates second-order effects: Before AI After AI Skill measured by lines of code Skill measured by validation, architecture, debugging Juniors slow to ship Juniors ship faster than seniors can review Senior devs write the hardest code Senior devs now judge the hardest code Tooling was mostly a matter of taste—IDEs, linters, build setups, etc. Tooling now defines the surface area AI can operate on: the wrong stack can block or limit agentic assistance Typed languages accelerate this shift—the stronger the safety rails, the more work can be handed to automation. The next horizon: when language stops being a constraint Today, language choice matters because runtimes are still fragmented. Browsers require JavaScript. Models need Python. Firmware expects C. But that’s already eroding. “WebAssembly is starting to change the rules,” Gazit says. “If any language can target Wasm and run everywhere, that removes one key consideration when picking your stack.” Combine that with AI-generated code, and you get a plausible future: Developer writes in Rust (or Go, or Python) AI generates code in that language Compiler targets Wasm The same code runs on web, edge, cloud, local sandbox That’s not a TypeScript-wins future. It’s a portability-wins future, and a natural extension to the rise of containerization over the last decade as a means of packaging and

In October, we experienced four incidents that resulted in degraded performance across GitHub services. October 09 14:45 UTC (lasting 1 hour and 55 minutes) On October 9, 2025, between 14:35 UTC and 15:21 UTC, a network device in maintenance mode that was undergoing repairs was brought back into production before repairs were fully completed. Network traffic traversing this device experienced significant packet loss. Authenticated users of the github.com UI experienced increased latency during the first 5 minutes of the incident. API users experienced up to 7.3% error rates, after which it stabilized to about 0.05% until mitigated. Actions service experienced 24% of runs being delayed for an average of 13 minutes. Large File Storage (LFS) requests experienced minimally increased error rate, with 0.038% of requests erroring. To prevent similar issues, we are enhancing the validation process for device repairs of this category. October 17 13:11 UTC (lasting 1 hour and 1 minute) On October 17, 2025, between 12:51 UTC and 14:01 UTC, mobile push notifications failed to be delivered for a total duration of 70 minutes. This affected github.com and GitHub Enterprise Cloud in all regions. The disruption was related to an erroneous configuration change to cloud resources used for mobile push notification delivery. We are reviewing our procedures and management of these cloud resources to prevent such an incident in the future. October 20 08:56 UTC (lasting 2 hours and 5 minutes) On October 20, 2025, between 08:05 UTC and 10:50 UTC the Codespaces service was degraded, with users experiencing failures creating new codespaces and resuming existing ones. On average, the error rate for codespace creation was 39.5% and peaked at 71% of requests to the service during the incident window. Resume operations averaged 23.4% error rate with a peak of 46%. This was due to a cascading failure triggered by an outage in a third-party dependency required to build devcontainer images. The impact was mitigated when the third-party dependency recovered. We are evaluating options to ensure  this dependency is no longer a critical path in our container build process and improving our monitoring and alerting to reduce the detection time of similar issues in the future. October 29 16:17 UTC (lasting 6 hours and 58 minutes) On October 29, 2025, between 14:07 UTC and 23:15 UTC, GitHub experienced service degradation due to a widespread outage at a third-party provider. Codespaces users faced severe connection issues, with error rates averaging 90% and peaking at 100% across all regions during the incident. GitHub Actions larger hosted runners were also impacted, with 0.5% of workflows and nearly 10% of large runner jobs failing or delayed beyond five minutes. Actions impact recovered by 20:40 UTC. The GitHub Enterprise Importer service was impacted as well, causing migration failures during git push operations and significant delays in processing migrations. Additionally, new trials for GitHub Enterprise Cloud with Data Residency were delayed, and Copilot Metrics API downloads were unavailable, resulting in approximately 100 failed requests until recovery began around 20:25 UTC. Mitigations were applied throughout the incident to reduce impact, but full recovery was only achieved once the service provider resolved its outage. GitHub is now focused on reducing critical path dependencies on external providers and implementing strategies to gracefully degrade services during similar events, aiming to improve resilience against future outages. Follow our status page for real-time updates on status changes and post-incident recaps. To learn more about what we’re working on, check out the engineering section on the GitHub Blog. The post GitHub Availability Report: October 2025 appeared first on The GitHub Blog. ​ Company news, News & insights, GitHub Availability Report The GitHub Blog

Copilot code review (CCR) helps you automate code reviews and ensure your project meets your team’s standards. We recently added support for both copilot-instructions.md and path-specific *.instructions.md files, so now you can customize Copilot’s behavior to fit your workflow. This flexibility empowers you to guide Copilot with clear, actionable rules for effective and consistent reviews. But with this flexibility comes some uncertainty: When is Copilot code review reading your instructions? Why doesn’t it always follow your instructions exactly? How can you ensure Copilot code review listens to your guidance? While you can format your instructions file however you want, Copilot code review is non-deterministic and has specific limitations that will evolve as we improve the product. Understanding how to guide Copilot within its current capabilities is key to getting the most from your reviews. After reviewing many instructions files, common questions, and feedback, we’ve created this guide to help you write instructions that really work—and avoid some pitfalls along the way. ⚠️ Note: While these tips are designed for Copilot code review, you might find some of them useful when writing instructions files for other Copilot products. General tips Getting started is the hardest part. Here are some things to keep in mind when starting with your instructions.  Keep it concise: Copilot works best with focused, short instructions. Start small and iterate. Even a single line can help guide Copilot. On the flip side, long instructions files (over ~1,000 lines) can lead to inconsistent behavior. Structure matters: Use headings and bullet points to keep information organized and easy for Copilot to process. Be direct: Short, imperative rules are more effective than long paragraphs. Show examples: Demonstrate concepts with sample code or explanations—just like you would with a teammate. Repo-wide vs. path-specific instructions In addition to the centralized repo-wide copilot-instructions.md file, we recently expanded your customization options by enabling Copilot code review to read any NAME.instructions.md file with an applyTo frontmatter in your .github/instructions directory. It can be confusing to have two seemingly similar options for customization, but each provides different value! Here are some tips for how to differentiate between the two, and use them both effectively. Place language-specific rules in *.instructions.md files and then use the applyTo frontmatter property to target specific languages (e.g., applyTo: **/*.py or applyTo: documentation/*.md). Place rules meant specifically for only Copilot code review or only Copilot coding agent in *.instructions.md files, and use the excludeAgent frontmatter property to prevent either agent from reading your file. Organize different topics (e.g., security, language-specific guidelines, etc.) into separate *.instructions.md files. Reserve general instructions, team standards, and guidelines for the whole repository for copilot-instructions.md (e.g., “Flag use of deprecated libraries across the codebase”). Rules of thumb Effective instructions files often include: Clear titles A purpose or scope statement to clarify intent Lists of guidelines/rules instead of dense paragraphs Best practice recommendations Style conventions (indentation, naming, organization) Sample code blocks for clarification Section headings for organization Task-specific instructions (e.g., for tests or endpoints) Language/tooling context Emphasis on readability and consistency Explicit directives for Copilot (“Prefer X over Y”) What not to do Certain types of instructions aren’t supported by Copilot code review. Here are common pitfalls to avoid: Trying to change the UX or formatting of Copilot comments (e.g., “Change the font of Copilot code review comments”). Trying to modify the “Pull Request Overview” comment (e.g. prompting to remove it or change its purpose to be something other than provide an overview of the pull request). Requesting Copilot code review performs tasks outside of code review. (e.g., trying to modify the product behavior like asking it to block a pull request from merging). Including external links. Copilot won’t follow them. You should copy relevant info into your instructions files instead. Adding requests meant to generally and non-specifically improve behavior (e.g., “Be more accurate” or “Identify all issues”). Copilot code review is already tuned to do this and adding language like this adds more noise that confuses the LLM. Recommended structure for instructions files Starting off with a blank Markdown file can feel daunting. Here’s one structure that you can use, ready to copy-paste into your instructions file as a starting point! # [Your Title Here] *Example: ReactJS Development Guidelines* ## Purpose & Scope Briefly describe what this file covers and when to use it. — ## Naming Conventions – [Add rules here, e.g., “Use camelCase for variable names.”] ## Code Style – [Add rules here, e.g., “Indent using 2 spaces.”] ## Error Handling – [Add rules here.] ## Testing – [Add rules here.] ## Security – [Add rules here.] — ## Code Examples “`js // Correct pattern function myFunction() { … } // Incorrect pattern function My_function() { … } “` — ## [Optional] Task-Specific or Advanced Sections ### Framework-Specific Rules – [Add any relevant rules for frameworks, libraries, or tooling.] ### Advanced Tips & Edge Cases – [Document exceptions, advanced patterns, or important caveats.] Example: A typescript.instructions.md file Now let’s implement all of these guidelines in an example path-specific instruction file. — applyTo: “**/*.ts” — # TypeScript Coding Standards This file defines our TypeScript coding conventions for Copilot code review. ## Naming Conventions – Use `camelCase` for variables and functions. – Use `PascalCase` for class and interface names. – Prefix private variables with `_`. ## Code Style – Prefer `const` over `let` when variables are not reassigned. – Use arrow functions for anonymous callbacks. – Avoid using `any` type; specify more precise types whenever possible. – Limit line length to 100 characters. ## Error Handling – Always handle promise rejections with `try/catch` or `.catch()`. – Use custom error classes for application-specific errors. ## Testing – Write unit tests for all exported functions. – Use [Jest](https://jestjs.io/) for all testing. – Name test files as `<filename>.test.ts`. ## Example “`typescript // Good interface User { id: number; name: string; } const fetchUser = async (id: number): Promise<User> => { try { // …fetch logic } catch (error) { // handle error } }; // Bad interface user { Id: number;

If you’ve ever been handed a design file and thought, “Wait—what exactly is this supposed to do?” you’re not alone.  The handoff between designers and developers is one of the most common points where product workflows break down. You are looking at components and trying to figure out what’s interactive, what’s responsive, what happens when text gets bigger. The designer is trying to express something that isn’t directly stated on the canvas. Somewhere in that gap, accessibility considerations get missed. Knowledge walks out the door in lost Slack threads. Then it all comes back later as a bug that could have been prevented if messages weren’t missed or if expectations had been clearer upfront. GitHub’s accessibility design team ran into this exact problem internally. They looked at their own accessibility audit data and realized something striking: nearly half of accessibility audit issues (48%) could have been prevented if design intent had been better documented upfront by integrating WCAG (Web Content Accessibility Guidelines) considerations directly into annotations. So they built something to fix it. And now they’ve open sourced it. It’s called the Annotation Toolkit, and it’s a Figma library designed to make the handoff easier. The framework brings structure, clarity, and accessibility-first practices into every design-to-code interaction. What the Annotation Toolkit is (and isn’t) At its core, the Annotation Toolkit is a Figma library of stamps (annotations) that you can drop into your designs. Each annotation lets you: Express design intent beyond what’s visually on the canvas. Document accessibility behaviors like responsive reflow or table handling. Guide engineers clearly by linking numbered stamps to descriptions. Instead of documenting all this in Figma comments (which get lost), Slack threads (which disappear), or scattered one-off clarifications (which nobody can remember later), the annotations live right inside your design file. They’re numbered, they’re portable, and they stay with your work. Think of it like embedding clarity directly into the handoff. Why it matters: Accessibility by default The toolkit was built by GitHub’s accessibility design team specifically so that accessibility considerations aren’t something you bolt on at the end. They’re baked into the design workflow from the start. Each annotation comes with built-in guidance. Want to mark a table? The toolkit addresses nearly every design-preventable accessibility issue under WCAG guidelines, including things like reflow behavior. Adding an image? It prompts you to document the context so developers can write proper alt text. The toolkit doesn’t just let you document accessibility—it teaches you as you go. That’s not a small thing. It means developers stop guessing. It means accessibility isn’t a specialist concern anymore, but is part of the conversation from day one. Real-world application: From pain points to productivity Before this toolkit, GitHub teams relied on a patchwork of Figma comments, Slack threads, and one-off clarifications. This patched approach resulted in knowledge gaps and repeated accessibility oversights. But now, annotations provide: Clarity at scale: engineers no longer guess at intended behaviors.Consistency across teams: designers, product managers (PM), and developers all share a common language. Preventative QA: many issues are resolved at the design stage instead of post-build. Annotations enable Figma to become more than just a canvas. It’s a tool for expressing a much deeper level of information. @hellojanehere, product manager at GitHub Tutorial: How to use the Annotation Toolkit How to get started You’ve got two paths here, so pick whichever feels easier: Option 1: From Figma Community (fastest) Head to the @github profile on Figma (figma.com/@github). Find the Annotation Toolkit and click the link to duplicate it. It goes straight to your drafts. Access the components anytime from your Assets tab. Option 2: From GitHub (if you want all the docs at once) Visit github.com/github/annotation-toolkit. Download the exported Figma file from the repo. Open it in Figma and duplicate it to your workspace. Same deal—find components in your Assets tab. Once you’ve got the toolkit, adding your first annotation is straightforward. Open any design file, drag an annotation stamp into it (say, the Image annotation on a profile picture), and you’ll see a numbered label appear. Pair that number with a description block and write what you need. That’s it. You’ve just documented something that would normally disappear into a Slack thread. The toolkit comes with design checkpoints, which are basically interactive checklists that keep accessibility top of mind as you work. If you want to go deeper, everything is documented. The repo has tutorials for every annotation type, deep dives on WCAG compliance, and guidance on avoiding common handoff friction. Check it out and contribute back if you find gaps. The bigger picture The Annotation Toolkit is a shift in how we think about collaboration. By embedding intent, accessibility, and clarity directly into Figma, GitHub is giving the developer-designer partnership a new foundation. It’s not about replacing conversations. It’s about making them more meaningful. When intent is clear, work flows faster, and the end result is better for everyone. The toolkit is actively maintained by GitHub staff and open to contributions. If you spot something that could be better, head over to github.com/github/annotation-toolkit and open an issue. Report bugs, suggest features, or contribute new annotation types. The team is actively looking for feedback on how you’re using it and what’s missing. 👉 Explore the toolkit on Figma at @GitHub or dive into the repository on GitHub. If you want to see it in action first, check out the walkthrough. Try it, contribute, and help shape the future of accessible, collaborative design. The post Level up design-to-code collaboration with GitHub’s open source Annotation Toolkit appeared first on The GitHub Blog. ​ Collaboration, Enterprise software, Annotation Toolkit, Figma The GitHub Blog

We recently released a new GitHub Copilot feature: custom agents defined in agents.md files. Instead of one general assistant, you can now build a team of specialists: a @docs-agent for technical writing, a @test-agent for quality assurance, and a @security-agent for security analysis. Each agents.md file acts as an agent persona, which you define with frontmatter and custom instructions. agents.md is where you define all the specifics: the agent’s persona, the exact tech stack it should know, the project’s file structure, workflows, and the explicit commands it can run. It’s also where you provide code style examples and, most importantly, set clear boundaries of what not to do. The challenge? Most agent files fail because they’re too vague. “You are a helpful coding assistant” doesn’t work. “You are a test engineer who writes tests for React components, follows these examples, and never modifies source code” does. I analyzed over 2,500 agents.md files across public repos to understand how developers were using agents.md files. The analysis showed a clear pattern of what works: provide your agent a specific job or persona, exact commands to run, well-defined boundaries to follow, and clear examples of good output for the agent to follow.  Here’s what the successful ones do differently. What works in practice: Lessons from 2,500+ repos My analysis of over 2,500 agents.md files revealed a clear divide between the ones that fail and the ones that work. The successful agents aren’t just vague helpers; they are specialists. Here’s what the best-performing files do differently: Put commands early: Put relevant executable commands in an early section: npm test, npm run build, pytest -v. Include flags and options, not just tool names. Your agent will reference these often. Code examples over explanations: One real code snippet showing your style beats three paragraphs describing it. Show what good output looks like. Set clear boundaries: Tell AI what it should never touch (e.g., secrets, vendor directories, production configs, or specific folders). “Never commit secrets” was the most common helpful constraint. Be specific about your stack: Say “React 18 with TypeScript, Vite, and Tailwind CSS” not “React project.” Include versions and key dependencies. Cover six core areas: Hitting these areas puts you in the top tier: commands, testing, project structure, code style, git workflow, and boundaries.  Example of a great agent.md file Below is an example for adding a documentation agent.md persona in your repo to .github/agents/docs-agent.md: — name: docs_agent description: Expert technical writer for this project — You are an expert technical writer for this project. ## Your role – You are fluent in Markdown and can read TypeScript code – You write for a developer audience, focusing on clarity and practical examples – Your task: read code from `src/` and generate or update documentation in `docs/` ## Project knowledge – **Tech Stack:** React 18, TypeScript, Vite, Tailwind CSS – **File Structure:** – `src/` – Application source code (you READ from here) – `docs/` – All documentation (you WRITE to here) – `tests/` – Unit, Integration, and Playwright tests ## Commands you can use Build docs: `npm run docs:build` (checks for broken links) Lint markdown: `npx markdownlint docs/` (validates your work) ## Documentation practices Be concise, specific, and value dense Write so that a new developer to this codebase can understand your writing, don’t assume your audience are experts in the topic/area you are writing about. ## Boundaries – ✅ **Always do:** Write new files to `docs/`, follow the style examples, run markdownlint – ⚠️ **Ask first:** Before modifying existing documents in a major way – 🚫 **Never do:** Modify code in `src/`, edit config files, commit secrets Why this agent.md file works well States a clear role: Defines who the agent is (expert technical writer), what skills it has (Markdown, TypeScript), and what it does (read code, write docs). Executable commands: Gives AI tools it can run (npm run docs:build and npx markdownlint docs/). Commands come first. Project knowledge: Specifies tech stack with versions (React 18, TypeScript, Vite, Tailwind CSS) and exact file locations. Real examples: Shows what good output looks like with actual code. No abstract descriptions. Three-tier boundaries: Set clear rules using always do, ask first, never do. Prevents destructive mistakes. How to build your first agent Pick one simple task. Don’t build a “general helper.” Pick something specific like: Writing function documentation Adding unit tests Fixing linting errors Start minimal—you only need three things: Agent name: test-agent, docs-agent, lint-agent Description: “Writes unit tests for TypeScript functions” Persona: “You are a quality software engineer who writes comprehensive tests” Copilot can also help generate one for you. Using your preferred IDE, open a new file at .github/agents/test-agent.md and use this prompt: Create a test agent for this repository. It should: – Have the persona of a QA software engineer. – Write tests for this codebase – Run tests and analyzes results – Write to “/tests/” directory only – Never modify source code or remove failing tests – Include specific examples of good test structure Copilot will generate a complete agent.md file with persona, commands, and boundaries based on your codebase. Review it, add in YAML frontmatter, adjust the commands for your project, and you’re ready to use @test-agent. Six agents worth building Consider asking Copilot to help generate agent.md files for the below agents. I’ve included examples with each of the agents, which should be changed to match the reality of your project.  @docs-agent One of your early agents should write documentation. It reads your code and generates API docs, function references, and tutorials. Give it commands like npm run docs:build and markdownlint docs/ so it can validate its own work. Tell it to write to docs/ and never touch src/.  What it does: Turns code comments and function signatures into Markdown documentation   Example commands: npm run docs:build, markdownlint docs/ Example boundaries: Write to docs/, never modify source code @test-agent This one writes tests. Point it at your test framework (Jest, PyTest, Playwright) and give it the command to run tests. The boundary