tangcent/easy-yapi/easy-yapi-assistant

EasyYapi Rule Authoring Assistant

This skill is the external mirror of EasyYapi's built-in rule-authoring agent. It helps you write or modify EasyYapi rule files (.rules / .properties files in .easyapi/) that the EasyYapi IntelliJ plugin reads to customise API export (YApi/Postman/Markdown), field naming, annotations, and more.

It runs the same perceive → reason → act loop as the built-in agent and exposes the same capability surface: the same rule guide and key catalog, and CLI equivalents of every built-in perception tool. The only difference is how each capability is delivered — the built-in agent calls IntelliJ PSI tools; you read files and search the codebase directly.

When to Use

Invoke this skill when:

• The user opens or edits any file in the project's .easyapi/ folder or

the global ~/.easyapi/ folder.

• The user asks to "add a rule", "rename a field", "ignore a class", "add a

header to every POST", etc. in the EasyYapi context.

• The user mentions easy.api, EasyApi, EasyYapi, or easyapi in a request about

config or rule authoring.

Bundled Knowledge Base (read these first — they ARE the built-in agent's docs)

This skill ships mirrors of the in-plugin agent's authoritative sources, kept in sync by Gradle tasks in the easy-yapi repo. Run `./gradlew syncSkill` to refresh all four mirrors in one command (it aggregates syncKnowledgeBase, syncAgentCatalog, syncRuleKeySchemes, and syncRuleContexts):

1. `docs/` — the long-form knowledge-base pages the plugin bundles for its

built-in agent's get_plugin_doc tool. Kept in sync by the syncKnowledgeBase Gradle task.

1. `ai/detection/` + `ai/key-guides/` — the per-detection / per-key guide

catalog the in-plugin agent loads via PromptCatalog (the same files get_detection_prompt and get_rule_detail read at runtime). Kept in sync by the syncAgentCatalog Gradle task.

1. `rule-keys.json` + `rule-keys.md` — the auto-generated rule-key

scheme catalog. RuleKeySchemeExporter reflects every *RuleKeys object (general + channel + framework) and the implicit keys, and emits the full self-describing scheme of each key — the same information the in-plugin agent gets from its list_rule_keys tool. Regenerated by the syncRuleKeySchemes Gradle task, so any key added to a `*RuleKeys` object is picked up automatically (a brand-new channel/framework must be registered in RuleKeyCatalog.SOURCES).

1. `rule-contexts.json` + `rule-contexts.md` — the auto-generated

script-context mirror of the in-plugin get_rule_context tool. RuleContextExporter reuses the exact same key assembly (so it covers rule keys and the implicit keys read via configReader.getFirst — one interface, the same one the built-in agent sees) and, per key, reflects the runtime bindings + script-object method signatures. Regenerated by the syncRuleContexts Gradle task.

All mirrors are content-equality-checked and idempotent, so the rule content the built-in and external agents produce is identical. Always read the relevant page first — do not rely on memory or guess syntax.

All generated files (rule-keys.*, rule-contexts.*, tools.md, locales.md, extensions.md) are refreshed by ./gradlew syncSkill and must never be edited by hand.

Toolset — CLI mirrors of the built-in agent tools

The mechanical inventory of the built-in tools (name, kind, approval,

timeout, description, registry membership, which have a CLI mirror) is

generated — see `tools.md`. The tables below add the

emulation guidance: how to achieve each tool's job with your own

file/rg capabilities, which is not derivable from code.

The built-in agent has a fixed set of perception/action tools. You provide equivalent capability by reading files and searching the codebase. Use the mapping below so your workflow tracks the built-in agent's.

EasyYapi-domain tools (bundled as scripts/)

These mirror the EasyYapi-specific perception tools. Run them from the project root (the CWD when the assistant is invoked). They auto-detect the project root and ~/.easyapi/ so you never hard-code paths.

Usage examples:

# List all rule files the plugin will load
scripts/list_rule_files.sh
 
# Read a rule file by name (scope-prefixed or bare)
scripts/read_rule_file.sh security.properties
scripts/read_rule_file.sh global:jwt.rules
scripts/read_rule_file.sh project:custom.rules
 
# Check if a key is already configured (avoid duplicates — Quality Rule 1)
scripts/get_existing_rules_for_key.sh field.name
scripts/get_existing_rules_for_key.sh api.tag method.additional.header

Catalog recipe tools (mirrors of in-plugin get_detection_prompt / get_rule_detail)

The built-in agent's decomposed prompt catalog (Phase A of the in-plugin agent) lives under src/main/resources/ai/{detection,key-guides}/ in the easy-yapi repo. This skill ships a verbatim copy under ai/{detection,key-guides}/ next to SKILL.md, kept in sync by the syncAgentCatalog Gradle task. CLI scripts mirror the in-plugin perception tools that read that catalog — same id space, same body content, same error shape — so your workflow tracks the in-plugin agent's exactly.

Key discovery now goes through rule-keys.md (the auto-generated full catalog, mirror of the in-plugin list_rule_keys tool): it lists every supported rule key — including the implicit keys with no RuleKey constant — with its full self-describing scheme. The key-guide index (which keys carry a per-key guide file) is folded into get_key_guide.sh --list.

Usage examples:

# Discover which detection families exist before proposing rules
scripts/list_detections.sh
 
# Fetch the recipe for one detection family
scripts/get_detection_prompt.sh spring-filters-interceptors
scripts/get_detection_prompt.sh static-auth
 
# Discover which per-key guides exist
scripts/get_key_guide.sh --list
 
# Fetch the guide for one rule key (before drafting a rule for that key)
scripts/get_key_guide.sh postman.test
scripts/get_key_guide.sh method.additional.header
scripts/get_key_guide.sh markdown.curl.host
 
# Fetch the runtime script-context of a key when authoring a script value
scripts/get_key_context.sh postman.test
scripts/get_key_context.sh api.class.parse.after

Catalog recipe access priority (mirrors the in-plugin agent's agent-base.md): for a detection-family question, the preferred first stop is scripts/get_detection_prompt.sh <id>; for a per-key guide question, the preferred first stop is scripts/get_key_guide.sh <key>. The long-form docs/rule-guide.md stays the reference for cross-cutting context (Workflow Patterns, Multi-Application Namespace, the full filter-prefix table). Memory is never a substitute for the catalog — always read the guide before drafting.

General codebase-perception tools (your file/grep capabilities)

The built-in agent has PSI tools to inspect source. You use file reads + rg/grep instead. rg is assumed available (it ships with most AI coding assistants); fall back to grep -rn if it isn't.