AGENTS.md ยท diff
git:20260820.4dbe9e4 to git:20260821.1b830a3
31 added, 9 removed. Audit A to A.
- This project is formerly known as Vibe Code Protocol Suite, but has expanded into Takomi after so many iterations to a bunch of things, including a custom PI harness, basically hosting PI extensions that customize PI into what we now know as Takomi CLI.
+ # Takomi / VibeCode Protocol Suite Agent Guidelines
- A bunch of really comprehensive skills and workflows that I use, which you can find in the assets folder.
+ This repository provides Takomi CLI, Pi harness extensions, and a curated skills ecosystem (`assets/.agent/skills/`). Follow these rules when developing, adding, or modifying skills and workflows.
- Some things worth noting: when updating a skill or when adding a skill that I am importing from either someone else's product or my own project, the descriptions of the skills must be descriptions of how the skill will be invoked.
+ ---
- It's not going to just be, "Oh, this skill does blah, blah, blah, blah." It's going to be used when [a user wants to do X], then a nice description, at most two sentences.
+ ## 1. Skill Taxonomy & Architecture Rules
- Also, it's worth noting that in the front matter of skills, we like to add an author, version, co-author. If I'm not the original author of the skill and I'm actually making changes to the original skill, then we add a co-author meta flag in front. You can see an example of what the front matter looks like below.
+ To prevent context saturation (prompt bloat) across AI agent harnesses, skills follow the **Lean Unified Skills Architecture** (`docs/features/Lean_Unified_Skills_Architecture.md`):
+ 1. **Add to Existing Umbrella Suites**: If a new skill relates to an established domain (testing, Next.js, code intelligence, git operations, agent prompts, UI, office docs, media), add it as a sub-skill inside the relevant suite folder.
+ 2. **Update Router Context Pointers**: When adding a sub-skill, update the parent suite's top-level `SKILL.md` frontmatter `description` to include keyword triggers for the new sub-skill. This enables natural keyword discovery without requiring the user to type the suite name.
+ 3. **When to Create a New Suite**: Create a new umbrella suite only when a cluster of 3+ related sub-skills introduces a distinct engineering or creative domain not covered by the existing 12 suites.
+ 4. **When to Keep a Skill Standalone**: Keep a skill standalone at the top level only if it is a single-purpose CLI binary wrapper (e.g., `audit-website`, `context7`, `jules`), a global communication mode (e.g., `wait-what`, `bro`, `poteto-mode`), or an isolated cross-domain utility.
+ 5. **Core Essentials Policy**: Never unilaterally add or promote a skill to Core Essentials. The 8 Core Essentials (`takomi`, `grill-me`, `code-review`, `sync-docs`, `security-audit`, `agent-recovery`, `avoid-feature-creep`, `git-commit-generation`) are always active; promotions to Core are decided by the user.
+ 6. **Check for Merges & Duplicates**: Before importing any new skill, search existing suites for overlaps. Present candidates to the user to merge, upgrade, or deprecate redundant skills.
+
---
+
+ ## 2. Skill Frontmatter Standard
+
+ Every `SKILL.md` must start with YAML frontmatter specifying:
+ * `name`: Kebab-case identifier.
+ * `description`: Actionable trigger starting with `"Use when [user wants to do X]..."` (maximum two sentences).
+ * `author`: Original author.
+ * `coauthored`: `J StaR Films / Takomi` when modifying or adapting external work.
+ * `version`: Semantic version string.
+
+ ```yaml
+ ---
name: git-commit-generation
- description: Use when the user wants or you need to generate clear, conventional git commit messages based on staged changes or recent repository diffs.
+ description: Use when generating clear, conventional git commit messages based on staged changes or recent repository diffs.
author: Kilo Code
coauthored: J StaR Films / Takomi
version: 2.0.0
---
+ ```
- The main point of this whole repo is two things:
+ ---
- First of all, I wanted that if for any reason I need to migrate to a new computer, within a few commands, I can set up everything as if I never left. Secondly, if I'm trying to help my friends onboard into the whole Vibe Coding thing, I want them to be able to have these skills and workflows without stress. It's kind of like the whole simple installation process. We also don't want to slow down the agent, and I have a bunch of different things I do normally that are not just coding-related, so it's very nice for us to have all these collections of skills and workflows that help us go through all these things.
+ ## 3. Writing & Unslop Skill
- When working on a new skill or importing a new skill, always check if there are other potential skills that might have something similar. Then you can bring it to my attention so we might merge them or completely depreciate one or the other.
+ * **Always Use Unslop Skill**: When writing any text, chat responses, documentation, UI copy, or skill instructions, always read and follow the `unslop` skill (`.agents/skills/unslop/SKILL.md`).
+ * **Relative Links**: Internal skill references to formats, scripts, or sibling docs must use correct local relative paths (`view_file` targets).
+ * **Positive Prompting**: Describe what the agent *should* do directly rather than listing negative prohibitions.