diff --git a/README.md b/README.md
index 254b21e5..9f633d5e 100644
--- a/README.md
+++ b/README.md
@@ -39,10 +39,78 @@ RBAC-based And Policy-based Multi-Tenant Reactive Security Framework.
 
 ![ActionMatcher](document/design/assets/ActionMatcher.svg)
 
+#### How to customize `ActionMatcher` (SPI)
+
+> Refer to [RegularActionMatcher](cosec-core/src/main/kotlin/me/ahoo/cosec/policy/action/RegularActionMatcher.kt) 
+
+```kotlin
+class CustomActionMatcherFactory : ActionMatcherFactory {
+    companion object {
+        const val TYPE = "[CustomActionType]"
+    }
+
+    override val type: String
+        get() = TYPE
+
+    override fun create(onfiguration: Configuration): ActionMatcher {
+        return CustomActionMatcher(onfiguration)
+    }
+}
+class CustomActionMatcher(configuration: Configuration) :
+    AbstractActionMatcher(CustomActionMatcherFactory.TYPE, configuration) {
+    override val type: String
+        get() = CustomActionMatcherFactory.TYPE
+
+    override fun internalMatch(request: Request, securityContext: SecurityContext): Boolean {
+        //Custom matching logic
+    }
+}
+```
+
+> META-INF/services/me.ahoo.cosec.policy.action.ActionMatcherFactory
+
+```properties
+# CustomActionMatcherFactory fully qualified name
+```
+
 ### ConditionMatcher
 
 ![ConditionMatcher](document/design/assets/ConditionMatcher.svg)
 
+#### How to customize `ConditionMatcher` (SPI)
+
+> Refer to [ContainsConditionMatcher](cosec-core/src/main/kotlin/me/ahoo/cosec/policy/condition/part/ContainsConditionMatcher.kt)
+
+```kotlin
+class CustomConditionMatcherFactory : ConditionMatcherFactory {
+    companion object {
+        const val TYPE = "[CustomConditionType]"
+    }
+
+    override val type: String
+        get() = TYPE
+
+    override fun create(configuration: Configuration): ConditionMatcher {
+        return CustomConditionMatcher(configuration)
+    }
+}
+class CustomConditionMatcher(configuration: Configuration) :
+    AbstractActionMatcher(CustomActionMatcherFactory.TYPE, configuration) {
+    override val type: String
+        get() = CustomConditionMatcherFactory.TYPE
+
+    override fun internalMatch(request: Request, securityContext: SecurityContext): Boolean {
+        //Custom matching logic
+    }
+}
+```
+
+> META-INF/services/me.ahoo.cosec.policy.condition.ConditionMatcherFactory
+
+```properties
+# CustomConditionMatcherFactory fully qualified name
+```
+
 ## Policy Schema
 
 [Policy Schema](document/cosec-policy.schema.json)
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 5f507d62..fc905e40 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -39,10 +39,78 @@
 
 ![ActionMatcher](document/design/assets/ActionMatcher.svg)
 
+#### 如何自定义 `ActionMatcher` (SPI)
+
+> 参考 [RegularActionMatcher](cosec-core/src/main/kotlin/me/ahoo/cosec/policy/action/RegularActionMatcher.kt)
+
+```kotlin
+class CustomActionMatcherFactory : ActionMatcherFactory {
+    companion object {
+        const val TYPE = "[CustomActionType]"
+    }
+
+    override val type: String
+        get() = TYPE
+
+    override fun create(onfiguration: Configuration): ActionMatcher {
+        return CustomActionMatcher(onfiguration)
+    }
+}
+class CustomActionMatcher(configuration: Configuration) :
+    AbstractActionMatcher(CustomActionMatcherFactory.TYPE, configuration) {
+    override val type: String
+        get() = CustomActionMatcherFactory.TYPE
+
+    override fun internalMatch(request: Request, securityContext: SecurityContext): Boolean {
+        //Custom matching logic
+    }
+}
+```
+
+> META-INF/services/me.ahoo.cosec.policy.action.ActionMatcherFactory
+
+```properties
+# CustomActionMatcherFactory fully qualified name
+```
+
 ### ConditionMatcher
 
 ![ConditionMatcher](document/design/assets/ConditionMatcher.svg)
 
+#### 如何自定义 `ConditionMatcher` (SPI)
+
+> 参考 [ContainsConditionMatcher](cosec-core/src/main/kotlin/me/ahoo/cosec/policy/condition/part/ContainsConditionMatcher.kt)
+
+```kotlin
+class CustomConditionMatcherFactory : ConditionMatcherFactory {
+    companion object {
+        const val TYPE = "[CustomConditionType]"
+    }
+
+    override val type: String
+        get() = TYPE
+
+    override fun create(configuration: Configuration): ConditionMatcher {
+        return CustomConditionMatcher(configuration)
+    }
+}
+class CustomConditionMatcher(configuration: Configuration) :
+    AbstractActionMatcher(CustomActionMatcherFactory.TYPE, configuration) {
+    override val type: String
+        get() = CustomConditionMatcherFactory.TYPE
+
+    override fun internalMatch(request: Request, securityContext: SecurityContext): Boolean {
+        //Custom matching logic
+    }
+}
+```
+
+> META-INF/services/me.ahoo.cosec.policy.condition.ConditionMatcherFactory
+
+```properties
+# CustomConditionMatcherFactory fully qualified name
+```
+
 ## 策略 Schema
 
 [Policy Schema](document/cosec-policy.schema.json)