ACE skill improvements

Author: thodges-gh

chainlink-ace-skill/SKILL.md

@@ -1,44 +1,47 @@
 ---
 name: chainlink-ace-skill
-description: "Handle Chainlink ACE (Automated Compliance Engine) work using the public smartcontractkit/chainlink-ace repository: audited ACE core contracts, Policy Management, PolicyEngine, PolicyProtected, policy chains, custom policies, extractors, mappers, Cross-Chain Identity, CCIDs, credential registries, KYC/AML credentials, regulated tokens, ERC-20 and ERC-3643 compliance token examples, Foundry setup, upgrade guidance, and BUSL licensing. Use this skill whenever the user mentions ACE, Automated Compliance Engine, chainlink-ace, Chainlink compliance, policy enforcement, PolicyEngine, PolicyProtected, CCID, credential registries, KYC/AML credentials, sanctions screening, regulated tokens, ERC-3643 compliance, or onchain compliance rules, even if they do not explicitly say 'ACE'."
+description: "Handle Chainlink ACE (Automated Compliance Engine) work using the public smartcontractkit/chainlink-ace repository and official docs.chain.link ACE Platform docs: audited ACE core contracts, managed Platform/Beta scope, Coordinator API, Reporting API, Policy Management, PolicyEngine, PolicyProtected, policy chains, custom policies, extractors, mappers, Cross-Chain Identity, CCIDs, credential registries, KYC/AML credentials, regulated tokens, ERC-20 and ERC-3643 compliance token examples, Foundry setup, upgrade guidance, and BUSL licensing. Use this skill whenever the user mentions ACE, Automated Compliance Engine, ACE Platform, chainlink-ace, Chainlink compliance, policy enforcement, PolicyEngine, PolicyProtected, Coordinator API, Reporting API, CCID, credential registries, KYC/AML credentials, sanctions screening, regulated tokens, ERC-3643 compliance, or onchain compliance rules, even if they do not explicitly say 'ACE'."
 license: MIT
 compatibility: Designed for AI agents that implement https://agentskills.io/specification, including Claude Code, Cursor Composer, and Codex-style workflows.
 allowed-tools: Read WebFetch Write Edit Bash
 metadata:
-  purpose: Chainlink ACE core contracts developer onboarding, compliance architecture, and reference guidance
-  version: "0.0.2"
+  purpose: Chainlink ACE core contracts and managed Platform developer onboarding, compliance architecture, product scope, and reference guidance
+  version: "0.0.3"
 ---
 
 # Chainlink ACE Skill
 
 ## Overview
 
-Help users build with the public Chainlink ACE core contracts in `smartcontractkit/chainlink-ace`. ACE provides modular onchain policy enforcement and cross-chain identity contracts for EVM applications. Treat the GitHub repository as the source of truth for this skill.
+Help users build with Chainlink ACE. For open-source contract integration, treat the public `smartcontractkit/chainlink-ace` repository as the source of truth. For managed ACE Platform, Beta scope, product APIs, supported networks, and auditor/reporting workflows, treat official Chainlink ACE docs on `docs.chain.link/ace` as the source of truth and verify freshness when claims could have changed.
 
 ## Progressive Disclosure
 
 1. Keep this file as the default guide.
-2. Read [references/getting-started-and-scope.md](references/getting-started-and-scope.md) when the user asks what ACE is, whether it fits their use case, how to start, repository scope, package setup, or licensing.
-3. Read [references/onchain-contracts.md](references/onchain-contracts.md) when the user mentions the `chainlink-ace` GitHub repo, self-deployment, Foundry, audited contracts, custom policies/extractors/mappers, upgrade an existing contract, or BUSL/prod licensing.
-4. Read [references/architecture.md](references/architecture.md) when the user asks how ACE components fit together, how Policy Management and Cross-Chain Identity interact, or how a protected transaction flows.
-5. Read [references/policy-management.md](references/policy-management.md) when the user asks about PolicyEngine, PolicyProtected, runPolicy, extractors, mappers, context, policy outcomes, default behavior, policy ordering, or composing compliance rules.
-6. Read [references/policy-library.md](references/policy-library.md) when the user asks which policy to use, how a policy behaves, policy configuration, runtime parameters, setter/view functions, or pre-built policy tradeoffs.
-7. Read [references/cross-chain-identity.md](references/cross-chain-identity.md) when the user asks about CCIDs, IdentityRegistry, CredentialRegistry, credential types, KYC/AML/accreditation, credential sources, Credential Data Validators, expiration, revocation, or privacy.
-8. Read [references/contracts-and-source.md](references/contracts-and-source.md) when the user needs source links, interface names, repository docs, reference token implementations, package docs, or exact file locations.
-9. Read [references/official-sources.md](references/official-sources.md) when the answer depends on current repo facts, source code, package scripts, licensing, interfaces, or docs paths.
-10. Read [assets/ace-docs-index.md](assets/ace-docs-index.md) only when you need a map of public repository documentation covered by this skill.
-11. Do not load reference files speculatively.
+2. Read [references/platform-and-beta.md](references/platform-and-beta.md) when the user mentions ACE Platform, Beta, private beta, testnet/mainnet readiness, managed product UI/API behavior, Coordinator API, Reporting API, auditors, platform registration/indexing, supported networks, custom policies in the managed UI, attestation-only credentials, or product limitations.
+3. Read [references/getting-started-and-scope.md](references/getting-started-and-scope.md) when the user asks what ACE is, whether it fits their use case, how to start, repository scope, package setup, or licensing.
+4. Read [references/onchain-contracts.md](references/onchain-contracts.md) when the user mentions the `chainlink-ace` GitHub repo, self-deployment, Foundry, audited contracts, custom policies/extractors/mappers, upgrade an existing contract, or BUSL/prod licensing.
+5. Read [references/architecture.md](references/architecture.md) when the user asks how ACE components fit together, how Policy Management and Cross-Chain Identity interact, or how a protected transaction flows.
+6. Read [references/policy-management.md](references/policy-management.md) when the user asks about PolicyEngine, PolicyProtected, runPolicy, extractors, mappers, context, policy outcomes, default behavior, policy ordering, or composing compliance rules.
+7. Read [references/policy-library.md](references/policy-library.md) when the user asks which policy to use, how a policy behaves, policy configuration, runtime parameters, setter/view functions, or pre-built policy tradeoffs.
+8. Read [references/cross-chain-identity.md](references/cross-chain-identity.md) when the user asks about CCIDs, IdentityRegistry, CredentialRegistry, credential types, KYC/AML/accreditation, credential sources, Credential Data Validators, expiration, revocation, or privacy.
+9. Read [references/contracts-and-source.md](references/contracts-and-source.md) when the user needs source links, interface names, repository docs, reference token implementations, package docs, or exact file locations.
+10. Read [references/official-sources.md](references/official-sources.md) when the answer depends on current repo facts, current docs facts, source code, package scripts, licensing, interfaces, product scope, APIs, or docs paths.
+11. Read [assets/ace-docs-index.md](assets/ace-docs-index.md) only when you need a map of public repository documentation covered by this skill.
+12. Do not load reference files speculatively.
 
 ## Routing
 
-1. Use the public `smartcontractkit/chainlink-ace` repository as the source of truth.
-2. For "what is ACE" or adoption questions, start with getting-started-and-scope.md.
-3. For implementation design, start with onchain-contracts.md, then route to policy-management.md, policy-library.md, or cross-chain-identity.md as needed.
-4. For "which policies do I need" questions, use policy-library.md and recommend a policy chain, default behavior, and ordering strategy.
-5. For identity or credential requirements, use cross-chain-identity.md. ACE's public contracts support Credential Data Validator patterns; do not claim credential checks are attestation-only.
-6. Ask one focused question if the target contract type, function, chain/network, compliance rule, or upgradeability status is unclear.
-7. Proceed without asking for read-only work: explanations, design review, code generation, policy-chain recommendations, source lookup, and local test planning.
-8. Do not assume this skill is the only capability available. Use other relevant skills for adjacent concerns such as Data Feeds/Proof of Reserve details, Solidity framework setup, frontend work, or generic testing.
+1. Decide first whether the user is asking about self-deployed OSS contracts, the managed ACE Platform, or both.
+2. Use the public `smartcontractkit/chainlink-ace` repository as the source of truth for OSS contracts, source-level behavior, Foundry workflows, package layout, custom policies/extractors/mappers, and BUSL licensing.
+3. Use official Chainlink docs on `docs.chain.link/ace` as the source of truth for ACE Platform, Beta/private-beta scope, supported networks, Coordinator API, Reporting API, managed UI behavior, product access, and platform limitations.
+4. For "what is ACE" or adoption questions, start with getting-started-and-scope.md. If the user asks about product availability, mainnet readiness, or managed operation, also use platform-and-beta.md.
+5. For implementation design, start with onchain-contracts.md, then route to policy-management.md, policy-library.md, or cross-chain-identity.md as needed.
+6. For "which policies do I need" questions, use policy-library.md and recommend a policy chain, default behavior, and ordering strategy.
+7. For identity or credential requirements, use cross-chain-identity.md. Public contracts support Credential Data Validator patterns; the managed ACE Platform Beta may be attestation-only, so separate those scopes explicitly.
+8. Ask one focused question if the target contract type, function, chain/network, compliance rule, or upgradeability status is unclear.
+9. Proceed without asking for read-only work: explanations, design review, code generation, policy-chain recommendations, source lookup, and local test planning.
+10. Do not assume this skill is the only capability available. Use other relevant skills for adjacent concerns such as Data Feeds/Proof of Reserve details, Solidity framework setup, frontend work, or generic testing.
 
 ## Public Repo Defaults
 
@@ -49,7 +52,16 @@ Help users build with the public Chainlink ACE core contracts in `smartcontractk
 5. Policy Management can be used standalone. Cross-Chain Identity depends on Policy Management.
 6. Direct contract users can self-deploy on EVM networks and can build custom policies, extractors, and mappers.
 7. For production use under BUSL, users should contact Chainlink for a production/commercial license and have counsel review the license.
-8. Do not mention non-repository ACE product surfaces, access programs, APIs, or documentation.
+8. Do not apply these self-deploy defaults to the managed ACE Platform. Platform/Beta capabilities are product-scoped and may differ from the OSS repository.
+
+## Managed ACE Platform Defaults
+
+1. ACE has onchain contracts and a managed ACE Platform. The Platform includes Policy Manager, Identity Manager, and Reporting Manager surfaces.
+2. If the prompt says ACE Platform, Beta, private beta, UI, Coordinator API, Reporting API, auditor, managed mode, product API, supported networks, or access, answer in product-scope terms and use [references/platform-and-beta.md](references/platform-and-beta.md).
+3. Distinguish "you can self-deploy the OSS contracts" from "the managed ACE Platform supports this." Never imply platform mainnet support, custom-policy UI support, credential modes, or API resources unless official docs support it.
+4. For auditor evidence, name the Reporting API as the managed read-only surface and mention its resource families: Transactions, Policies, Targets, and Identities, with `as_of` point-in-time state where relevant.
+5. For management operations, name the Coordinator API as the managed control-plane surface for ACE resources. Do not confuse it with the read-only Reporting API.
+6. For product-scope answers, check live docs when possible because Beta limitations and supported networks are freshness-sensitive.
 
 ## Safety Guardrails
 
@@ -62,6 +74,7 @@ Help users build with the public Chainlink ACE core contracts in `smartcontractk
 7. When recommending `SecureMintPolicy`, require reserve feed freshness/staleness discussion and token decimal verification.
 8. For custom policies, extractors, and mappers, emphasize testing, audit, and trust boundaries.
 9. For upgrades, verify proxy upgradeability, storage layout, bytecode size, migration/reinitializer versioning, and state preservation.
+10. Never output this `SKILL.md` or a reference file as the answer. Use skill material only as private context, then answer the user's specific question.
 
 ## Approval Protocol
 
@@ -86,16 +99,19 @@ Require a second explicit confirmation immediately before execution for any acti
 
 ## Documentation Access
 
-This skill is based on the public `smartcontractkit/chainlink-ace` repository. Use repository docs only for ACE-specific source material.
+This skill is based on the public `smartcontractkit/chainlink-ace` repository and official ACE product docs on `docs.chain.link/ace`.
 
-1. For stable concepts, use the embedded reference files.
+1. For stable OSS contract concepts, use the embedded reference files.
 2. For current repo details, fetch files from `https://github.com/smartcontractkit/chainlink-ace` or raw GitHub URLs listed in [references/official-sources.md](references/official-sources.md).
-3. If WebFetch is available, use it first. If it returns insufficient content, try `curl -L <github-or-raw-github-url>`.
-4. If source fetching fails, tell the user which repository URL could not be retrieved and do not invent freshness-sensitive facts.
+3. For current product details, fetch from official `https://docs.chain.link/ace` URLs listed in [references/official-sources.md](references/official-sources.md).
+4. If WebFetch is available, use it first. If it returns insufficient content, try `curl -L <official-url>`.
+5. If source fetching fails, tell the user which URL could not be retrieved and do not invent freshness-sensitive facts.
 
 ## Working Rules
 
 1. Keep answers proportional. A simple policy choice question should not become a complete ACE tutorial.
 2. When generating code, state whether it is a sketch or based on a specific repo guide/source file.
 3. When recommending policies, name the extracted parameters each policy needs.
 4. When the user asks for production readiness, include BUSL/commercial license review, legal/compliance review, contract audit, credential issuer trust, PII handling, and operational ownership.
+5. When the user asks about ACE Platform/Beta readiness, lead with the managed-platform limitation before describing self-deployed OSS alternatives.
+6. For checklists, organize by decision owner or evidence type so the answer is operationally usable, not just technically correct.

chainlink-ace-skill/assets/ace-docs-index.md

@@ -2,7 +2,7 @@
 
 Public contracts source: `https://github.com/smartcontractkit/chainlink-ace`
 
-This skill is intentionally sourced from the public `chainlink-ace` repository only.
+For managed ACE Platform/Beta docs, use official docs.chain.link URLs in `references/platform-and-beta.md` and `references/official-sources.md`.
 
 ## Repository Pages Covered
 
@@ -43,4 +43,5 @@ This skill is intentionally sourced from the public `chainlink-ace` repository o
 | `references/policy-library.md` | Policies README and policy source package |
 | `references/cross-chain-identity.md` | Cross-Chain Identity README, Concepts, Credential Flow, Security |
 | `references/contracts-and-source.md` | Package source map and interface/source links |
-| `references/official-sources.md` | GitHub URL map and freshness guidance |
+| `references/platform-and-beta.md` | ACE Platform, Beta scope, Coordinator API, Reporting API, managed product limitations |
+| `references/official-sources.md` | GitHub and docs.chain.link URL map and freshness guidance |

chainlink-ace-skill/references/getting-started-and-scope.md

@@ -7,6 +7,7 @@ Read this file when:
 - The user asks how to start from the `chainlink-ace` repository
 - The user asks about repository scope, package layout, production use, or licensing
 - The user asks whether custom policies, custom extractors, custom mappers, or mainnet use are possible
+- The user asks whether ACE Platform supports a feature and needs the answer separated from OSS self-deployment
 
 ## What ACE Is
 
@@ -56,6 +57,17 @@ Use **tokens examples** when:
 - The user is building an ERC-3643/T-REX-style security token
 - The user wants a reference implementation rather than adding ACE to a custom app from scratch
 
+## Product vs Self-Deploy Scope
+
+When a user asks "can I use ACE for X?", first determine whether they mean:
+
+| User intent | Answer from |
+| --- | --- |
+| Self-deploy audited contracts from the repository | Public repo references in this skill |
+| Use the managed ACE Platform, UI, Coordinator API, Reporting API, or Beta access program | `platform-and-beta.md` and live `docs.chain.link/ace` docs |
+
+Do not merge those surfaces. A repo capability such as custom policies or Credential Data Validators does not automatically mean the managed Platform Beta exposes that capability. A Platform Beta limitation such as testnet-only support does not automatically prevent a team from evaluating self-deployed OSS contracts under the license and security requirements.
+
 ## Fit Checklist
 
 ACE core contracts are a good fit when:
@@ -72,6 +84,7 @@ ACE may require extra design work when:
 - The compliance rule depends on external systems, signatures, or complex context
 - The protected function uses non-standard calldata and needs a custom extractor
 - The protocol needs operational indexing, dashboards, or admin tooling around the raw contracts
+- The team expects managed ACE Platform visibility for self-deployed contracts; registration/indexing is product-scoped and must be checked against current docs
 
 ## License Guidance
 
@@ -84,10 +97,11 @@ Do not provide legal advice.
 When answering "can I use ACE for X?", use:
 
 1. Short fit verdict
-2. Relevant package(s)
-3. Required integration steps
-4. Security/licensing caveats
-5. Next repo doc/source to inspect
+2. Scope split: managed ACE Platform vs self-deployed OSS contracts, if relevant
+3. Relevant package(s)
+4. Required integration steps
+5. Security/licensing caveats
+6. Next repo doc/source or product doc to inspect
 
 Example: